docker

Docker Compose conventions

Apply these conventions when creating or modifying docker-compose.yml.

Principles

1. .env (git-ignored) + .env.example (checked in, with doc comments).
   All secrets and environment-specific values live in .env. The example file documents each variable.

2. No root.
   Every service that doesn't need root gets user: "${UID:-1000}:${GID:-1000}".

   • Dockerfiles must make the working directory group-writable (RUN chmod g+w .).
   • Postgres is exempt — its official image handles user switching.

3. No port forwarding in the base compose file.
   ports: only appear in override files. The base file exposes nothing to the host.

4. Override file (example only).
   Write docker-compose.override-example.yml with documented, commented-out options.
   Users copy it to docker-compose.override.yml (git-ignored) for their local customisations.
   Never write docker-compose.override.yml into the project — only the example.

5. Lightweight images.
   Prefer -alpine or -slim variants.

6. Named project.
   Set name: at the top so volumes and containers are predictable. Or use COMPOSE_PROJECT_NAME env var.

7. Mandatory env vars.
   Use ${VAR:?required} so compose errors immediately when a required variable is missing.

8. Short service names.
   pg, bun, ml, py, sk (SvelteKit), pb (PocketBase), etc. If there's a "primary" app, their service should be named app.

9. Restart policy.
   restart: unless-stopped for long-lived services, on-failure:N for batch jobs. Never use always (it reanimates after intentional docker compose stop).

10. Read-only root.
    read_only: true on every service that doesn't need to write to its own filesystem. Mount tmpfs for paths that must be writable (/tmp, /run). Combine with tmpfs for the writable paths the app actually needs.

11. Log rotation.
    Every service gets logging.driver: json-file with max-size: 10m and max-file: 3. Prevents disk fills.