Skip to main content
Step-by-step bring-up of the Observal stack. End state: the core services are healthy, API responding at http://localhost/health, web UI at http://localhost. Prometheus and Grafana are optional.

1. Clone and configure

The .env.example ships with working direct-value defaults for local source development, including demo account credentials. You do not need to edit it for local development. Production server-package installs use generated files under secrets/ instead; see Configuration.
[!NOTE] You need Docker Engine ≥ 24.0 with Compose v2 (docker compose, not docker-compose). Homebrew’s Docker formula is outdated. Install Docker Desktop or use your distro’s upstream packages. Verify with docker version and docker compose version.

2. Start the stack

Core stack only:
With Prometheus only:
With Prometheus and Grafana:
First build takes a few minutes (pulls images, builds observal-api and observal-web). Subsequent starts are fast.

3. Verify health

Every service should show healthy or running. The API waits for Postgres, ClickHouse, and Redis to pass health checks before starting. Expect 15–30 seconds on first boot. Hit the health endpoint:

4. Configure TLS (production only)

For local dev, http://localhost is fine. For production, put a TLS-terminating reverse proxy in front of the nginx LB. See Requirements → TLS / HTTPS.

5. Bootstrap the first user

Option A - demo accounts (fastest for trying it out)

.env.example seeds four demo accounts on first startup: Log in with the CLI:
Remove demo accounts before real deployment. Unset the DEMO_* env vars in .env and restart. Already-seeded accounts stay until you delete them manually (observal admin delete-user <email>). Remove DEMO_* from .env and start the stack. Run:
The CLI detects that no users exist and interactively creates the first admin. The /api/v1/auth/bootstrap endpoint is restricted to localhost access for security.

6. Verify with the CLI

7. Stop, restart, rebuild

Makefile shortcuts from the repo root:

8. Logs

9. Port conflicts

If docker compose up fails with port is already allocated, remap host ports via env vars:
Every host port is configurable. See Ports and volumes for the full list.

Next

→ Configuration: which env vars to change for production.