Docker
Docker is never required: the app is one static binary, and the
systemd deploy is the reference production setup. But it runs just as well in
containers. The repository ships a Dockerfile and a compose.yaml, and CI builds the image and
boots the whole stack on every push, so they keep working.
One image, every role
The image holds the same binary as a native release (dashboard embedded, version stamped from
VERSION). The command picks the role, exactly like on a server:
| Command | Role | Native equivalent |
|---|---|---|
serve (default) |
HTTP API, dashboard, /docs |
ims-go-api.service |
queue:work |
River workers | ims-go-api-worker.service |
schedule |
cron scheduler | ims-go-api-scheduler.service |
migrate |
apply migrations, then exit | the release step in release.sh |
| any other command | db:seed, backup:run, config:show… |
ims <command> |
What the image contains:
- Base: Alpine. The process runs as a non-root
imsuser. - Extra packages:
ca-certificates, for S3, mail and webhooks over TLS;tzdata, forAPP_TIMEZONEand cron schedules;pg_dump, sobackup:runworks inside the container.
- Volumes:
/app/varholds uploads and the file cache;/app/backupsholds backups.
- Health check: the image probes
/up.
The whole stack with Compose
docker compose up -d --build # postgres → migrate → api, worker, schedulerdocker compose run --rm api db:seed # first run only: tenant, roles, admin + developerOpen localhost:8080/dev and sign in as superadmin@ims.com.
| Service | What it does |
|---|---|
postgres |
PostgreSQL 17 with a named volume |
migrate |
one-shot: ims migrate && ims permission:sync. The app services wait for it to succeed |
api |
ims serve on port APP_PORT (default 8080) |
worker |
ims queue:work |
scheduler |
ims schedule |
Configuration works the same as a native run: Compose reads your .env if there is one. Compose
then overrides two values so the containers find each other:
DATABASE_DSNpoints at thepostgresservice;APP_URLdefaults tohttp://localhost:8080.
POSTGRES_USER, POSTGRES_PASSWORD, POSTGRES_DB and APP_PORT change the defaults.
Everyday commands:
docker compose logs -f api workerdocker compose run --rm api config:show # effective config, secrets maskeddocker compose run --rm api backup:rundocker compose up -d --build # after pulling new code: rebuild, migrate, restartdocker compose down # stop (add -v to delete the data volumes)Hot reload stays native
For day-to-day development, make dev (air + Vite) is faster than rebuilding an image.
make db-up starts just a throwaway Postgres if that is all you want from Docker.
Production in containers
The compose file is a working base, not a hardened deployment. Before you run it for real:
- Production posture. Set
APP_ENV=productionand real secrets in.env. This turns off the dashboard and/docsby default and enables production validation (expiring tokens, masked errors). - Managed database. Use a managed PostgreSQL, or back up the
pg-datavolume. To use an external database, remove thepostgresservice and setDATABASE_DSNyourself. - TLS. Put a TLS-terminating proxy (Caddy, Traefik, nginx or a cloud load balancer) in front of
api, and setHTTP_TRUSTED_PROXIESso client IPs and rate limits stay correct. - Scaling. Run one
scheduler. Scaleworkerandapifreely, for exampledocker compose up -d --scale worker=3: River coordinates the workers through PostgreSQL. - Migrations. Keep them a separate step, as the
migrateservice already does: run them once per release, never from every API replica. - Shared files. Store files on S3 or R2 (
FILES_DISK) when you run more than oneapireplica, so every replica sees the same files.
The image works the same on Kubernetes, ECS, Fly.io or any other container platform. Run the same image three times with different commands, plus a migration job per release.