Skip to main content
Docker Compose is the shortest complete self-hosted path. The checked-in stack runs the control plane and PostgreSQL, publishing the API on 127.0.0.1:8080. It does not include a browser console; visiting / returns 404.

​
Prerequisites

You need Docker with Docker Compose, an available port 8080, persistent local storage, and outbound HTTPS access to your configured Anthropic or Z.AI model provider. Create the credential files described in .env.example; supported credential settings always name files and never contain secret values. Set the required OPENCLUSTER_* file paths, provider and model, and numeric non-root OPENCLUSTER_RUNTIME_UID and OPENCLUSTER_RUNTIME_GID values. The PostgreSQL DSN uses host postgres, user and database opencluster, and the password from the mounted PostgreSQL password file.

​
Start and verify

From the repository root, run:
PostgreSQL should become healthy; the control plane should remain running. Verify the process probes directly:
/healthz confirms the process is alive. /readyz becomes successful only when the deployment can serve traffic. These operational probes are intentionally not part of the generated product API reference. Use the API to bootstrap the first Organization and its Admin User. Follow the Quickstart to connect an alert source and verify an Investigation.

​
Persistence and shutdown

PostgreSQL stores durable product state in the named postgres_data volume. A normal restart or this shutdown command retains it:
Adding --volumes deletes that local database. Back up PostgreSQL and retain custody of the encryption key before moving or rebuilding a production deployment; without the same key, sealed integration credentials cannot be opened.

​
Replace an older pre-release deployment

Stop every old control-plane replica and back up PostgreSQL before replacing the image. Do not run mixed versions against one database. The current ledgered baseline migrates in place only when retained user Message attribution agrees with each Conversation source and every retained nonempty Investigation question has assigned user Messages. Any nonempty retained Postmortem reviewer must also be the UUID of an existing User. If a check fails, startup refuses the migration and leaves the old schema unchanged. Repair the data with the old version or restore the backup before retrying. Unknown or unledgered pre-release schemas are still refused before mutation and require a fresh application database. Removing the postgres_data volume deletes retained history, Organizations, Users, Integrations, and credentials, so complete setup again after starting the new version. Do not delete individual rows merely to force startup. This migration changes the API contract: Conversations expose source (web or slack) instead of surface and no lifecycle state; Message roles are user and assistant, Message attribution uses authorId and authorName, and replies are assistant Messages rather than Turn answers. Final hypotheses have no ID or exploring status; Investigation event envelopes use schemaVersion: 2 with the seven payloads documented in the API reference. Update clients before bringing the new replicas online.

​
Failure states

  • If PostgreSQL stays unhealthy, verify that the password file and DSN agree and that the DSN uses host postgres.
  • If the control plane exits, inspect docker compose -f deploy/compose/compose.yaml logs control-plane for a missing file, invalid key length, or provider configuration error.
  • If /healthz works but /readyz fails, inspect PostgreSQL connectivity and service logs before accepting traffic.
  • If the API is unreachable, confirm that port 8080 is free and the control-plane service is running.

​
Next step

Continue with the Quickstart. Use Configuration for supported settings and Troubleshooting when a verification step fails.