Docker Compose
deploy/compose/docker-compose.yml runs the whole stack on one host:
postgres: Postgres 18, data in thepgdatavolume.migrate: applies database migrations, then exits.apiandworkerwait for it to succeed.api(ROLE=api) andworker(ROLE=worker), sharing thefilesvolume for disk storage.app: the web app onAPP_PORT(default 8080), proxying/apitoapi.- Profiles:
minio(S3-compatible storage),monitoring(Prometheus and Jaeger, see Observability) andsite(the marketing site).
From deploy/compose:
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 --buildBETTER_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:
curl http://localhost:8080/api/health/ready# {"ready":true,"role":"api","database":true,"queue":true,"storage":{"driver":"disk","ok":true},"workersOnline":1}Scale workers
Section titled “Scale workers”docker compose up -d --scale worker=3Admin > System lists each worker. Each one renders RENDER_CONCURRENCY jobs at a time.
S3 storage on MinIO
Section titled “S3 storage on MinIO”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:
docker compose --profile minio up -dA 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.
Upgrade
Section titled “Upgrade”git pull # or set new image tags in .envdocker compose up -d --buildmigrate runs again before api and worker restart. See Upgrades.
Stop and remove
Section titled “Stop and remove”docker compose down stops the stack and keeps the volumes. docker compose down -v also deletes the database and stored PDFs.