Deploy with Docker Compose
Run the whole stack on one machine with the docker-compose.yml at the root of the repository, with optional automatic HTTPS through Caddy.
The root docker-compose.yml runs everything OpenDash needs on a single machine. It is the recommended way to evaluate OpenDash and to run it for a small team. CI runs this exact stack end to end on every change (infra/selfhost-smoke.sh).
Deploy
Clone the repository
git clone https://github.com/getopendash/opendash.git
cd opendashCreate your settings
cp infra/selfhost.env.example .envFill in .env. The file explains each value; the ones you must set are:
| Variable | What to put there |
|---|---|
POSTGRES_PASSWORD, OPENDASH_DB_*_PASSWORD | A URL-safe password for Postgres and each OpenDash role: openssl rand -hex 24 |
OPENDASH_KEK | The master encryption key: openssl rand -base64 32. Back it up. |
BETTER_AUTH_SECRET | Signs sessions and email links: openssl rand -base64 32 |
BETTER_AUTH_URL, BETTER_AUTH_TRUSTED_ORIGINS | The HTTPS address people open, e.g. https://opendash.example.com for both |
OPENDASH_BOOTSTRAP_ADMIN_EMAIL | The first admin's email. Required on a new, invite-only instance |
EMAIL_FROM and RESEND_API_KEY or SMTP_URL | How OpenDash sends sign-in emails |
ANTHROPIC_API_KEY, OPENAI_API_KEY, GOOGLE_GENERATIVE_AI_API_KEY or AI_GATEWAY_API_KEY | At least one, unless every workspace brings its own provider |
The configuration reference lists everything else.
Dashboards need an origin of their own
A dashboard's code runs in a sandboxed frame served from a second domain pointed at the same server, so it never runs where an OpenDash session does. Set it in OPENDASH_FRAMES_URL, for example https://frames.opendash.example.com. It is written into the web image's security headers when the image is built, and read again when it runs, so it must be set at both times. The bundled docker-compose.yml, the Caddy profile and the published images don't pass it yet: until they do, dashboards don't open on a Docker Compose install. Everything else works.
Start the stack
docker compose up -dTo let Caddy get a Let's Encrypt certificate for you, set OPENDASH_DOMAIN (its DNS pointing at this machine) and add the profile:
docker compose --profile caddy up -dSign in
Open your BETTER_AUTH_URL and sign up with the bootstrap admin's email. That address can sign up once, while nobody else has; everyone else joins by invitation. Then create a workspace and connect a source.
Want sample data first?
Set OPENDASH_SEED_DEMO=true and OPENDASH_DEMO_READER_PASSWORD before the first start. Setup seeds a sample SaaS company once, as its own database opendash_demo with a read-only user opendash_demo_reader. Connect it under Data → Connect source with host postgres.
What runs
The compose project is called opendash-selfhost. Its services start in this order:
| Service | What it does |
|---|---|
postgres | PostgreSQL with pgvector. Data lives in the pgdata volume; the port is not published. |
setup | One-shot: creates roles, schemas and extensions, runs migrations under an advisory lock and installs the job queues. web and worker wait for it. |
web | The UI and API on 127.0.0.1:3000 (change with OPENDASH_BIND and OPENDASH_PORT). Its health check holds the deploy until the database answers. |
worker | All worker pools (WORKER_POOLS=all). |
caddy | Only with --profile caddy: TLS in front of web. |
web binds to localhost on purpose. Put a TLS proxy in front of it (yours, or the Caddy profile), and never expose it directly: see Networking and security.
Use published images
To run released images instead of building from the clone, set them in .env:
OPENDASH_WEB_IMAGE=ghcr.io/getopendash/opendash-web:v1.2.3
OPENDASH_WORKER_IMAGE=ghcr.io/getopendash/opendash-worker:v1.2.3Pin a version tag rather than a moving one, so an upgrade is always a decision you make. See Upgrades and versioning.
Overview
Run OpenDash on your own infrastructure. The same two images serve a laptop, a single VM and a scaled deployment, with PostgreSQL as the only stateful dependency.
Configuration
Every environment variable a self-hosted OpenDash reads, grouped by what it controls. Both images read the same settings.