Skip to main content
Minimum and recommended specs for running the Observal stack.

Hardware

Default Docker memory limits (the API, worker and web limits differ between source Compose and the one-line server package): ClickHouse has the largest memory limit. Tune CLICKHOUSE_MEMORY_LIMIT for your workload; see resource tuning.

Disk: where the data goes

The heaviest user of disk is ClickHouse. Growth depends on:
  • Number and length of harness sessions
  • Raw transcript record size
  • DATA_RETENTION_DAYS
Session transcripts vary significantly by harness and tool output size. Measure representative workloads and plan 2 to 3 times headroom over observed growth. Postgres stays under 500 MB for most deployments; it holds only registry metadata and user accounts.

Software

[!NOTE] Homebrew’s Docker formula is outdated and may ship an older Compose version. Install Docker Desktop or use your distro’s upstream packages to get Docker Engine ≥ 24.0 with Compose v2.
For the CLI (developer machines, not the server):
  • Standalone binary (recommended) — no dependencies, just curl | bash
  • Or Python 3.11, 3.12, or 3.13 with uv, pipx, or pip

Network

  • Outbound HTTPS: required for image downloads and enabled integrations such as OAuth, webhooks, external Git repositories, or model providers.
  • Inbound: the server package routes the UI, API, and session telemetry through nginx on port 8000.
  • Between services: the private observal-net bridge handles application traffic.
  • Host bindings: new server-package installs bind nginx, the direct web port, PostgreSQL, ClickHouse, Redis, Prometheus, and Grafana to 127.0.0.1 by default.
  • Secret access: server-package setup records the operator’s group as OBSERVAL_SECRET_GID; only that group is added to containers that need their service-specific files.

TLS / HTTPS

Local loopback access can use HTTP. For every remote deployment, terminate TLS 1.2 or later with Caddy, nginx, an enterprise load balancer, or a cloud ingress. Point the proxy at the loopback nginx listener on localhost:8000. Example Caddy configuration:
Set OBSERVAL_BIND_ADDRESS to a non-loopback address only when an external TLS proxy cannot reach loopback, or when plaintext access is an intentional private-network risk. Existing server-package installations retain their previous bind address during setup upgrades. See the security assurance case for trust boundaries and residual network risks.

Next

→ Docker Compose setup