Skip to content

Docker Compose

deploy/compose/docker-compose.yml runs the whole stack on one host:

  • postgres: Postgres 18, data in the pgdata volume.
  • migrate: applies database migrations, then exits. api and worker wait for it to succeed.
  • api (ROLE=api) and worker (ROLE=worker), sharing the files volume for disk storage.
  • app: the web app on APP_PORT (default 8080), proxying /api to api.
  • Profiles: minio (S3-compatible storage), monitoring (Prometheus and Jaeger, see Observability) and site (the marketing site).

From deploy/compose:

Terminal window
cp .env.example .env
# Set POSTGRES_PASSWORD and BETTER_AUTH_SECRET (openssl rand -base64 32),
# and BETTER_AUTH_URL to the URL people will open.
docker compose up -d --build

BETTER_AUTH_URL must match the URL in the browser: if you change APP_PORT, change it too, or sign-in fails.

--build builds the images from the checkout. To use images from a registry instead, set NECODOC_API_IMAGE and NECODOC_APP_IMAGE in .env and drop --build.

Open http://localhost:8080 and sign up. The first account becomes the admin. Check readiness:

Terminal window
curl http://localhost:8080/api/health/ready
# {"ready":true,"role":"api","database":true,"queue":true,"storage":{"driver":"disk","ok":true},"workersOnline":1}
Terminal window
docker compose up -d --scale worker=3

Admin > System lists each worker. Each one renders RENDER_CONCURRENCY jobs at a time.

MinIO no longer publishes container images, so the minio profile uses Chainguard’s build from MinIO’s source. In .env, switch the storage block to the S3 lines (they’re in .env.example), then:

Terminal window
docker compose --profile minio up -d

A minio-bucket one-shot creates the bucket. Outputs rendered before the switch stay on the disk volume and can’t be downloaded afterwards, so switch before you rely on the install (see Storage).

The app container speaks plain HTTP. Put your TLS proxy (Caddy, Traefik, a load balancer) in front of it, forward everything to app:8080, and set BETTER_AUTH_URL to the https:// URL. Allow request bodies of 25 MB and upstream reads of RENDER_WAIT_MS plus a margin, 120 seconds with the default (see Configuration). Set TRUST_PROXY=2: your proxy and the app container’s nginx are both in front of the API.

Terminal window
git pull # or set new image tags in .env
docker compose up -d --build

migrate runs again before api and worker restart. See Upgrades.

docker compose down stops the stack and keeps the volumes. docker compose down -v also deletes the database and stored PDFs.