Skip to content

Install

Docker Compose

The compose files, what they run, and what to change for production.

The deploy/ folder of the repository is the reference install.

deploy/
  Dockerfile ## the app image
  docker-compose.yml ## app and Postgres, local-disk storage
  docker-compose.s3.yml ## overlay: a local MinIO and S3 storage
  docker-compose.caddy.yml ## overlay: Caddy for TLS and sites
  Caddyfile
  caddy/
    Dockerfile ## Caddy with the Route53 DNS module
  .env.example ## copy to .env

docker compose up -d --build runs two services:

  • postgres (postgres:18-alpine) with a named volume pgdata, a health check, user and database circi, and the password from POSTGRES_PASSWORD.
  • circi, built from deploy/Dockerfile, command all (server and worker in one process), published on CIRCI_PORT (default 3000). Files go to the files volume at /var/lib/circi/files. It waits for Postgres to be healthy, then applies migrations on start.

Everything the app reads comes from the environment: list, filled from .env. The compose file passes through the common variables (URLs, SMTP, sign-in, GitHub App, sites, timeouts, diff engine). A variable that isn't in that list is not passed to the container: for example SMTP_SECURE, SLACK_CLIENT_ID, AUTH_GITLAB_*, CIRCI_DIFF_THREADS and DATABASE_POOL_MAX. Add it to the environment: block (or use an env_file) when you need it.

Copy .env.example to .env. POSTGRES_PASSWORD and BETTER_AUTH_SECRET are required. For production also set:

Variable Why
PUBLIC_URL The https address people use, e.g. https://ci.acme.io. Links in emails, pull request comments and OAuth redirects use it.
TRUSTED_PROXIES The reverse proxy's address or range, so sign-in rate limits see real client addresses.
SMTP_* Email codes and invitations.

Every variable is in the environment variable reference.

Terminal window
# S3-compatible storage with a local MinIO (development)
docker compose -f docker-compose.yml -f docker-compose.s3.yml up -d --build
# TLS for the dashboard and the sites domain, with Caddy
docker compose -f docker-compose.yml -f docker-compose.caddy.yml up -d --build

For production S3 point S3_* at AWS S3, Cloudflare R2, Backblaze B2 or similar instead of running MinIO. See Storage and TLS and reverse proxy.

command: ['all'] is right for a small install. To scale, run two services from the same image with command: ['serve'] and command: ['worker']. See Scaling the worker.

Open PUBLIC_URL and follow the setup page, or script it. The server commands run inside the container.

  1. Print the setup code. The setup page asks for it.

    Terminal window
    docker compose exec circi circi admin setup-code
  2. Create the first account. Make it an instance admin.

    Terminal window
    docker compose exec circi circi admin user create --email you@acme.io --name "You" --instance-admin
  3. Create a workspace and a project. The project command prints its CI token once.

    Terminal window
    docker compose exec circi circi admin workspace create --name "Acme" --owner you@acme.io
    docker compose exec circi circi admin project create --org acme --name "Web app"
  4. Check the install.

    Terminal window
    docker compose exec circi circi admin doctor

One bundle, /app/dist/main.mjs, plus /app/migrations (CIRCI_MIGRATIONS), /app/web (CIRCI_WEB_DIST) and a small node_modules (sharp, pg, the AWS SDK). The image sets NODE_OPTIONS=--enable-source-maps, so stack traces point at source files. The image doesn't contain the upload CLI.

Health endpoints: GET /healthz (liveness) and GET /readyz (the database and storage answer).