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
| Requirement | Version | Why |
|---|---|---|
| Docker Engine | 24 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 Compose | v2, the docker compose plugin (validated against v2.40.3), not the standalone Python docker-compose v1 | The top-level name: key and the features above require the Compose Spec, which v1 doesn't implement. |
openssl | any recent version | Generating auth tokens; see below. |
| ~1 GiB free RAM | n/a | Base (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:
docker --versiondocker compose versionEvery port
| Var | Default | What it's for |
|---|---|---|
WEB_HOST_PORT | 3000 | Host port published for web. Change this, not the container port. |
ORBIT_API_HOST_PORT | 8080 | Host port published for orbit-api, for local debugging; the browser should never need it directly (see architecture.md). |
NOCTURNE_HOST_PORT | 8081 | Host 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_PORT | 8082 | The telemetry engine's API on loopback, for a local agent's remote-write or a curl. |
ORBIT_STACK_METRICS_HOST_PORT | 9092 | The 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):
openssl rand -hex 32 # → ORBIT_AUTH_TOKENopenssl rand -hex 32 # → NOCTURNE_AUTH_TOKENIf 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:
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:
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:
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:
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.
cp .env.example .envAppend 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):
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=:9090EOFReplace 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):
make upEquivalent without make:
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-orphansProduction-shaped (published images, static auth, requires the tokens above to be
real):
make up-prodEquivalent without make:
docker compose --project-name sreorbit --env-file .env \ -f deploy/compose/docker-compose.yml \ up -d --remove-orphansWhat a healthy install looks like
docker compose --project-name sreorbit --env-file .env \ -f deploy/compose/docker-compose.yml -f deploy/compose/docker-compose.override.yml psAll 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):
echo "ORBIT_ADMIN_USER=admin" >> .envecho "ORBIT_ADMIN_PASSWORD_VERIFIER=$(node apps/web/scripts/hash-password.mjs < admin-password)" >> .envadmin-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
curl -fsS http://localhost:${ORBIT_API_HOST_PORT:-8080}/healthzcurl -fsS http://localhost:${ORBIT_API_HOST_PORT:-8080}/readyzEvery 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:
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:
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-orphansThe 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:
# 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-orphansIf 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
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-orphansThis 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
- Every variable used above, with full meaning:
../configuration.md. - What each healthcheck asserts, and the
web-probes-/healthztrap:../troubleshooting.md. - Moving to a real cluster:
helm.md.