Quickstart

This guide takes you from a freshly installed cerbix to a Service whose availability is computed from a declared SLI and quoted against an objective. You need Docker with Compose and about 15 minutes, plus the time it takes for the first window to fill.

Installation itself is covered by Install. This guide runs that installation on localhost for evaluation, without TLS, and continues from the first sign-in.

1. Start cerbix

Follow Install › Option A — Docker Compose, steps 1 and 2, on the machine you evaluate on. Skip step 3, TLS: on localhost it is not needed (see the caution in step 2 below). When you fill in docker/.env, mind three details:

• CERBIX_ENCRYPTION_KEY takes the output of openssl rand -base64 32. Compose does not run commands in an env file, so a line CERBIX_ENCRYPTION_KEY=$(openssl rand -base64 32) passes that text literally. Run the command and paste its result.
• docker/config.prod.yaml sets local.min_password_length: 12, so CERBIX_ADMIN_PASSWORD must be at least 12 characters, or startup fails.
• Keep CERBIX_RABBITMQ_IMAGE as the example file sets it.

Continue when the health endpoint answers:

curl -s http://127.0.0.1:8080/healthz

{"status":"ok"}

The port is bound to 127.0.0.1:8080 only.

2. Sign in

Open http://localhost:8080/ and sign in with CERBIX_ADMIN_EMAIL and CERBIX_ADMIN_PASSWORD. Change the password afterwards under Settings → Security.

Caution

session.secure defaults to true, so the session cookie is marked Secure. Browsers accept it on http://localhost, which is why this quickstart works without TLS. On any other host name, put TLS in front as described in Install, and do not publish the port beyond 127.0.0.1 without it.

3. Create an organization, a project and a monitor

On a fresh instance the Dashboard shows a setup guide. Reopen it at any time with Get started. The guide reads its progress from the server, so a step counts as done only when the resource exists.

1. Select Create organization. Enter a name, for example Example. The slug is derived from the name and can be edited. You become the organization’s first admin.
2. Select Create project. Enter a name, for example Payments.
3. Pick HTTP (or open the full monitor form). Enter a name such as checkout-api, enter a URL under Target, for example https://example.com/, and select Create monitor.

The guide then says the monitor is waiting for its first real result. A saved monitor is not “healthy yet”. The first heartbeat arrives after the first scheduled run (the default interval is 60 s). A first result of DOWN also completes the guide: it is real evidence, and the guide links to the monitor so you can inspect the message and code.

Tip

Create two or three monitors for the same system, for example an HTTP health check and a TCP check on its port. A Service can then show the difference between what counts and what is only context.

4. Declare a Service

A Service is where you state what reliability means for one operational unit. Monitors are observations; the Service decides which of them count. See Services.

1. Open Services and select New service.
2. Enter a Name (Checkout) and a Slug (checkout). The slug is project-unique and immutable. Select Create service.
3. The new Service has no declaration. It reports no availability, not 100%. Select Edit declaration.
4. Under Operational context, tick the monitors that belong to this Service.
5. Under Reliability inputs, tick the monitors that count toward availability. These are the SLI members. A monitor must be in the operational context before it can be an input; context-only monitors are shown as diagnostic only.
6. Leave Aggregation at all and Missing data at unknown, or adjust them. See How the SLI is computed.
7. Select Save as revision 1.

Each save creates a new, immutable definition revision. It takes effect at the next bucket boundary; history already sealed keeps the meaning it was measured with.

5. Set an objective

On the Service page, the Reliability card has window tabs: 24h, 7d, 30d (selected by default) and 90d. An objective is set per window.

1. Pick a window, for example 30d.
2. In the Error budget tile, select set one next to “no objective set”.
3. Enter a target above 0 and below 100 (maximum 99.9999), for example 99.9, and select Save.

The error budget and burn rate need an objective; availability does not. See SLO, error budget and burn rate.

6. Read the window report

The report covers [sealed_through − window, sealed_through). It ends at the seal watermark, never at the current time. Service facts are kept in one-minute buckets, and a bucket seals two minutes after it ends.

Expect these states on a new Service:

Status	What the card shows	What to do
insufficient_sealed_coverage	Nothing is sealed yet.	Wait a few minutes for the first buckets to seal.
insufficient_history	The window reaches before this Service’s history begins.	Wait until the history covers the whole window. The 24h window fills first.
ok	Availability, error budget and burn rate.	Read the numbers against the objective.
partial	A number, marked partial, with its reason.	Inspect the reason, for example coverage below the minimum.
unavailable	Nothing was measured in the window.	Inspect the SLI monitors.

A number that cannot be defended is shown as a dash with its reason. It is never rounded to 100%. See Truthful rendering.

The Health card shows the live signal straight away. It is a separate, explicitly unstable view and is not a window number.

Note

If your monitors already have history when you write the first declaration, set Backfill from under Adopt existing history before you save revision 1. The result is labelled a declared reconstruction: it is evaluated with today’s members. Only the first revision can be retroactive.

Do the same with the API

Each step above has a REST API equivalent. To script it, issue a token under Settings → API tokens → Issue token with the role editor, scoped to your project. The secret is shown once.

export CERBIX_URL=http://localhost:8080
export CERBIX_TOKEN=<token>
P=<project-id>   # from GET /api/v1/organizations/<org-id>/projects

# Create the service
curl -sS -X POST "$CERBIX_URL/api/v1/projects/$P/services" \
  -H "Authorization: Bearer $CERBIX_TOKEN" -H "Content-Type: application/json" \
  -d '{"slug":"checkout","name":"Checkout"}'

# Declare context and SLI members (monitor IDs from GET /api/v1/projects/$P/monitors)
curl -sS -X PUT "$CERBIX_URL/api/v1/projects/$P/services/<service-id>/declaration" \
  -H "Authorization: Bearer $CERBIX_TOKEN" -H "Content-Type: application/json" \
  -d '{"expected_revision":0,"monitors":["<monitor-id-1>","<monitor-id-2>"],"sli":["<monitor-id-1>"]}'

# Set the 30d objective
curl -sS -X PUT "$CERBIX_URL/api/v1/projects/$P/services/<service-id>/sla-target" \
  -H "Authorization: Bearer $CERBIX_TOKEN" -H "Content-Type: application/json" \
  -d '{"window":"30d","objective":99.9}'

# Read the window report
curl -sS "$CERBIX_URL/api/v1/projects/$P/services/<service-id>/reliability?window=30d" \
  -H "Authorization: Bearer $CERBIX_TOKEN"

expected_revision is the revision you last saw; 0 means no declaration yet. A stale value returns 409 revision_conflict. Every sli member must also be listed in monitors, otherwise the request returns 400 sli_not_in_monitors. See the REST API reference.

To keep monitors and services in version control instead, see Monitoring as code.

Next steps

• Page on the Service instead of each monitor: Incidents and On-call.
• Publish the Service on a status page.
• Let a pipeline ask the error budget before a deploy: Release gate.
• Tune the instance: Configuration.