Overview

Run Observal entirely on your own infrastructure. No SaaS, no egress, every byte of telemetry stays inside your network.

For a packaged single-node install, install-server.sh generates restricted credential files under secrets/, records their NAME_FILE paths in .env, and binds host ports to loopback. It prompts when a terminal is available and applies the same safe defaults automatically in headless CI or agent environments. The source Compose path remains available for development and accepts direct .env values.

Architecture at a glance

Seven services:

Service	Image	Ports	Purpose
observal-api	built from docker/Dockerfile.api	8000	FastAPI backend
observal-web	built from docker/Dockerfile.web	3000	Next.js web UI
observal-db	postgres:16	5432	Registry, users, config
observal-clickhouse	clickhouse/clickhouse-server:26.3	8123	Session and audit events
observal-redis	redis:7-alpine	6379	Job queue (arq) + pub/sub
observal-worker	built from docker/Dockerfile.api	(internal)	Background async jobs
observal-grafana	grafana/grafana-oss:11.6.5	3001	Dashboards (optional)

All services run on a private observal-net bridge network. Named volumes (pgdata, chdata, redisdata, grafanadata, apidata) hold persistent data.

Deployment tiers

Choose the deployment model that fits your team:

	Single-node	Kubernetes	Production
How	Docker Compose on one VM	Official Helm chart	Terraform on AWS or GCP
Best for	≤50 users, internal tools, POCs	Cloud-native teams, existing K8s infra	Enterprise, SLA-bound, 50+ users
Cost	$20 to $150/mo	Variable	~$180 to $255/mo
HA	No	Pod resilience & horizontal scaling	Yes (Multi-AZ databases, autoscaling)
Time to deploy	10 minutes	10 to 15 minutes	20 to 30 minutes

Start here:

If you want to...	Read
Deploy on a single VM (simplest)	Single-node deployment
Deploy on Kubernetes with Helm	Kubernetes deployment with Helm
Deploy a production HA stack	Production deployment
Deploy on AWS specifically	AWS deployment with Terraform
Deploy on GCP specifically	GCP deployment with Terraform

Then configure and operate:

If you want to...	Read
Confirm your machine can run Observal	Requirements
Get the stack running locally for dev	Docker Compose setup
Know every env var that matters	Configuration
See every port and volume at a glance	Ports and volumes
Understand the DBs and retention	Databases
Set up SSO, JWT keys, demo accounts	Authentication and SSO
Understand session delivery	Session tracking and reconciliation
Upgrade safely	Upgrades
Back up and restore	Backup and restore
Fix something that's broken	Troubleshooting

Production checklist

Before putting Observal in front of real users:

1. Protect SECRET_KEY: server-package setup generates it in secrets/; source deployments must set a strong direct value or SECRET_KEY_FILE.
2. Protect database passwords: server-package setup generates restricted PostgreSQL and ClickHouse credential files; source deployments must replace the .env.example defaults.
3. Scope CORS_ALLOWED_ORIGINS to your real frontend host.
4. Configure SSO in Admin → SSO, including deployment.sso_only if you want SSO-only login.
5. Tune rate limits (RATE_LIMIT_AUTH, RATE_LIMIT_AUTH_STRICT).
6. Set DATA_RETENTION_DAYS to match your retention policy (default 90 days).
7. Back up the JWT key volume (apidata): losing it invalidates every session.
8. Remove demo accounts: remove DEMO_* variables and generated demo password files before a real deployment, then delete any already-seeded demo users.

Each of these is covered in the linked deep-dive below. Start with Requirements.