Skip to content

Install

Docker Compose

Single host, no Kubernetes. The fastest path to a running stack, and what CI uses for a smoke test. Two shapes: a zero-credential dev loop (make up) and a production-shaped install (make up-prod). This page covers both; their auth postures differ on purpose (see "Auth: two shapes" below).

Prerequisites

RequirementVersionWhy
Docker Engine24 or newer (validated against 29.1.3)The compose files use read_only, tmpfs entries with size/mode/uid/gid, and per-service deploy.resources outside Swarm mode: all Compose-Spec features, not legacy docker-compose.yml v2/v3 syntax.
Docker Composev2, the docker compose plugin (validated against v2.40.3), not the standalone Python docker-compose v1The top-level name: key and the features above require the Compose Spec, which v1 doesn't implement.
opensslany recent versionGenerating auth tokens; see below.
~1 GiB free RAMn/aBase (up-prod) resource limits sum to ~1 GiB (web 512 MiB + orbit-api 256 MiB + nocturne 256 MiB). The dev override (up) raises limits to ~2 GiB combined to give a local build headroom. That is a ceiling, not a requirement; usage at idle is far lower.

Confirm what you have:

bash
docker --versiondocker compose version

Every port

VarDefaultWhat it's for
WEB_HOST_PORT3000Host port published for web. Change this, not the container port.
ORBIT_API_HOST_PORT8080Host port published for orbit-api, for local debugging; the browser should never need it directly (see architecture.md).
NOCTURNE_HOST_PORT8081Host port published for nocturne, with the same debugging caveat, only stronger: in a real deployment nocturne must not be reachable from outside this host.
ORBIT_STACK_HOST_PORT8082The telemetry engine's API on loopback, for a local agent's remote-write or a curl.
ORBIT_STACK_METRICS_HOST_PORT9092The engine's metrics listener on loopback.

Container ports are fixed by CONTRACT.md and are not configurable: web on 3000, orbit-api on 8080 (API) and 9090 (metrics, Addendum v0.2), nocturne on 8081 (API) and 9090 (metrics), orbit-stack on 8082 (API) and 9090 (metrics).

Storage

Every container runs with a read-only root filesystem and a tmpfs at /tmp. Two keep state on a named volume. orbit-stack keeps its blocks, its write-ahead logs and its trace segments on orbit-stack-data, mounted at /data. orbit-api keeps users, roles, sessions, saved dashboards and the audit trail on orbit-api-data, mounted at /var/lib/sreorbit (ORBIT_DATA_DIR). make down removes both together with the network (it runs docker compose down --volumes), so every account, dashboard and audit line goes with them; to keep them across a teardown, stop the stack with docker compose stop instead, or back the volumes up first (../operations.md has the commands). Size the engine's volume for ORBIT_STACK_RETENTION days at the bytes per sample of your workload (the benchmark page gives 1.7 B per sample on a scrape-shaped one), plus one block duration of write-ahead log.

Auth: two shapes, and why they differ

docker-compose.override.yml exists for one reason, stated in its own header: "the stack runs with zero credentials." The addendum-complete dev loop (make up, base + override) runs both backend services with ORBIT_AUTH_MODE=disabled / NOCTURNE_AUTH_MODE=disabled: no token to generate, no token to leak from a laptop. make up-prod (base file alone, publishing images instead of building) runs static mode, matching CONTRACT.md's own default, and requires real tokens or the backend services refuse to start.

Generate them once, regardless of which shape you're using (you'll need them the moment you switch to up-prod):

bash
openssl rand -hex 32   # → ORBIT_AUTH_TOKENopenssl rand -hex 32   # → NOCTURNE_AUTH_TOKEN

If your checked-out docker-compose.yml predates Addendum v0.2

services/ and deploy/ are under active development as this page is written; status.md lists what has landed. If the steps below don't take effect (the containers start but the vars aren't visible inside them), your compose files don't yet pass these variables through, and you need to add them yourself. Compose only forwards variables a service's environment: block explicitly references; setting something in .env alone is not enough. Add:

To deploy/compose/docker-compose.yml, web.environment:

yaml
      ORBIT_API_URL: ${ORBIT_API_URL:-http://orbit-api:8080}
      ORBIT_AUTH_TOKEN: ${ORBIT_AUTH_TOKEN:-}

To deploy/compose/docker-compose.yml, orbit-api.environment:

yaml
      ORBIT_AUTH_MODE: ${ORBIT_AUTH_MODE:-static}
      ORBIT_AUTH_TOKEN: ${ORBIT_AUTH_TOKEN:-}
      ORBIT_OIDC_ISSUER: ${ORBIT_OIDC_ISSUER:-}
      ORBIT_OIDC_AUDIENCE: ${ORBIT_OIDC_AUDIENCE:-}
      ORBIT_METRICS_ADDR: ${ORBIT_METRICS_ADDR:-:9090}
      NOCTURNE_AUTH_TOKEN: ${NOCTURNE_AUTH_TOKEN:-}

To deploy/compose/docker-compose.yml, nocturne.environment:

yaml
      NOCTURNE_AUTH_MODE: ${NOCTURNE_AUTH_MODE:-static}
      NOCTURNE_AUTH_TOKEN: ${NOCTURNE_AUTH_TOKEN:-}
      NOCTURNE_OIDC_ISSUER: ${NOCTURNE_OIDC_ISSUER:-}
      NOCTURNE_OIDC_AUDIENCE: ${NOCTURNE_OIDC_AUDIENCE:-}
      NOCTURNE_METRICS_ADDR: ${NOCTURNE_METRICS_ADDR:-:9090}

And to deploy/compose/docker-compose.override.yml, so the zero-credential dev loop stays zero-credential:

yaml
  orbit-api:
    environment:
      ORBIT_AUTH_MODE: disabled
  nocturne:
    environment:
      NOCTURNE_AUTH_MODE: disabled

(Neither compose file passes NEXT_PUBLIC_API_URL any more: apps/web/Dockerfile does not consume it, and a stale copy in your own override would be a no-op Docker warns about. Delete it if you carried one over.)

Install

The repository is not public, and nothing on this page downloads it. Run every command below from the root of the SRE Orbit source tree you were given, the directory that holds the Makefile, .env.example and deploy/. make up-prod needs only that tree's deploy/compose/ and .env, and pulls the published images; make up builds them from the tree.

bash
cp .env.example .env

Append the two tokens you generated above (needed for up-prod; harmless to set even if you're only running up, since the dev override forces disabled mode regardless):

bash
cat >> .env <<'EOF' # --- Addendum v0.2 ----------------------------------------------------------ORBIT_AUTH_MODE=staticORBIT_AUTH_TOKEN=REPLACE_WITH_YOUR_FIRST_GENERATED_TOKENORBIT_METRICS_ADDR=:9090NOCTURNE_AUTH_MODE=staticNOCTURNE_AUTH_TOKEN=REPLACE_WITH_YOUR_SECOND_GENERATED_TOKENNOCTURNE_METRICS_ADDR=:9090EOF

Replace both REPLACE_WITH_... placeholders with the two openssl rand -hex 32 outputs from above before continuing, with sed -i or your editor. Do not leave the literal placeholder text in .env.

Then bring the stack up. Dev loop (build from source, zero credentials, demo data):

bash
make up

Equivalent without make:

bash
docker compose --project-name sreorbit --env-file .env \  -f deploy/compose/docker-compose.yml \  -f deploy/compose/docker-compose.override.yml \  up -d --build --remove-orphans

Production-shaped (published images, static auth, requires the tokens above to be real):

bash
make up-prod

Equivalent without make:

bash
docker compose --project-name sreorbit --env-file .env \  -f deploy/compose/docker-compose.yml \  up -d --remove-orphans

What a healthy install looks like

bash
docker compose --project-name sreorbit --env-file .env \  -f deploy/compose/docker-compose.yml -f deploy/compose/docker-compose.override.yml ps

All five services show Up with health (healthy): web's healthcheck starts passing within its 20s start_period; the backend services within 10s. The fifth is orbit-shop, the demo shop: eight small services in one process that send traces to the engine, so the APM pages have something to show (../apm.md → "The demo shop"). ORBIT_SHOP_RPS in .env sets its load (default 5 requests a second), and docker compose --project-name sreorbit --env-file .env -f deploy/compose/docker-compose.yml stop orbit-shop stops it. If any service shows (unhealthy) or keeps restarting, go straight to troubleshooting.md.

Sign in

The console asks for a user. Compose runs orbit-api on demo data (ORBIT_DEMO_DATA=true), so on its first start, with an empty volume, it creates three accounts, admin, editor and viewer, sharing the password in ORBIT_DEMO_PASSWORD, or a random one when .env leaves it empty, printed once in docker compose logs orbit-api (the demo_password field). The login page lists them: pick one to see what that role sees. To start with your own admin instead, add the pair to .env before the first up (../identity.md → "The first admin" generates the verifier):

bash
echo "ORBIT_ADMIN_USER=admin" >> .envecho "ORBIT_ADMIN_PASSWORD_VERIFIER=$(node apps/web/scripts/hash-password.mjs < admin-password)" >> .env

admin-password is a file holding the admin's password, 15 characters or more. The pair only counts while the volume holds no user; to start over, make down (which deletes the volume) and up again.

Verify

bash
curl -fsS http://localhost:${ORBIT_API_HOST_PORT:-8080}/healthzcurl -fsS http://localhost:${ORBIT_API_HOST_PORT:-8080}/readyz

Every other route needs a session, and with auth static (make up-prod) the bearer too. With auth disabled (the make up dev loop) the bearer is ignored, so the same commands work on both; set TOKEN to the ORBIT_AUTH_TOKEN in your .env:

bash
TOKEN=REPLACE_WITH_YOUR_ORBIT_AUTH_TOKENDEMO_PASSWORD="$(docker compose logs orbit-api | grep -o '"demo_password":"[^"]*"' | cut -d'"' -f4)"curl -fsS -H "Authorization: Bearer $TOKEN" http://localhost:${ORBIT_API_HOST_PORT:-8080}/api/v1/auth/stateSESSION="$(curl -fsS -H "Authorization: Bearer $TOKEN" -H 'content-type: application/json' \  -d "{\"username\":\"admin\",\"password\":\"$DEMO_PASSWORD\"}" http://localhost:${ORBIT_API_HOST_PORT:-8080}/api/v1/auth/login \  | python3 -c 'import json,sys; print(json.load(sys.stdin)["token"])')"curl -fsS -H "Authorization: Bearer $TOKEN" -H "X-Orbit-Session: $SESSION" \  http://localhost:${ORBIT_API_HOST_PORT:-8080}/api/v1/version

(DEMO_PASSWORD is the demo accounts' password, from the first start's log; with your own admin, use its password.) Then open http://localhost:${WEB_HOST_PORT:-3000}/ in a browser: the marketing site renders, and /deck asks you to sign in, then shows the demo estate.

Upgrade

Replace the source tree with the new release you were given, keep your .env, and rebuild:

bash
docker compose --project-name sreorbit --env-file .env \  -f deploy/compose/docker-compose.yml -f deploy/compose/docker-compose.override.yml \  up -d --build --remove-orphans

The named volumes survive an upgrade: users, dashboards, the audit trail and telemetry stay.

For up-prod, bump IMAGE_TAG in .env to the new published version first, then run the up-prod command again; compose pulls the new tag and recreates containers whose image or config changed, leaving the others untouched.

Roll back

Compose has no built-in release history. Unlike Helm, "rollback" here means "reinstall the previous version yourself," so you need to know what that version was:

bash
# IMAGE_TAG in .env: set it back to the last known-good value, then:docker compose --project-name sreorbit --env-file .env \  -f deploy/compose/docker-compose.yml up -d --remove-orphans

If you built locally instead of pulling published images, this only works if the old image is still in your local Docker cache (docker image ls | grep sreorbit); otherwise compose has nothing to roll back to. install/helm.md's digest-pinning closes this gap; if byte-identical rollback matters to you, use that path instead of compose.

Uninstall cleanly

bash
make down# equivalent:docker compose --project-name sreorbit --env-file .env \  -f deploy/compose/docker-compose.yml -f deploy/compose/docker-compose.override.yml \  down --volumes --remove-orphans

This removes the containers, the sreorbit network, and the two named volumes, orbit-stack-data (telemetry and traces) and orbit-api-data (users, dashboards and the audit trail): back them up first if you want them. It does not remove .env (it holds your generated tokens; delete it yourself if you're done: rm .env) or any images you pulled/built (docker image rm ghcr.io/sreorbit/{web,orbit-api,nocturne,orbit-stack}:$IMAGE_TAG, or make clean for the dev-tagged local builds).

Where to go next