Deploy with Docker Compose

The Compose file in Get started is built for a first look. Four changes make it something you can leave running.

The file

services:
  setup:
    image: ghcr.io/redfox-soft/oauth-server-ts:<version>
    command: ['sh', '-c', 'bun run db:setup && bun run db:migrate']
    env_file: .env
    restart: 'no'

  oauth:
    image: ghcr.io/redfox-soft/oauth-server-ts:<version>
    ports:
      - '127.0.0.1:3000:3000'
    env_file: .env
    depends_on:
      setup:
        condition: service_completed_successfully
    restart: unless-stopped

with a .env beside it:

ISSUER=https://auth.example.com
MONGODB_URI=mongodb+srv://user:password@cluster.example.mongodb.net
DATABASE_NAME=OAuth

What changed, and why

Pin the image tag. Images are published to ghcr.io/redfox-soft/oauth-server-ts on every release, tagged with the version and with latest. latest means a docker compose pull can move you across a release you have not read the changelog for. Name the version instead, and change it on purpose. That is also what turns the upgrade into a reviewable diff. The published tags are listed on the GitHub releases page and on the container package page.

Verify the image once per version you adopt. Every release is signed over its digest and carries an SBOM and a build provenance attestation, so you can check the tag you just pinned instead of trusting it:

cosign verify \
  --certificate-oidc-issuer https://token.actions.githubusercontent.com \
  --certificate-identity-regexp '^https://github\.com/RedFox-Soft/OAuth-server\.ts/\.github/workflows/release\.yml@refs/tags/v' \
  ghcr.io/redfox-soft/oauth-server-ts:<version>

It fits naturally into the same change that moves the pin, since that is usually the moment you are already reading the changelog. What is attached and how to read the SBOM.

Use a database you back up. The Get started file runs mongo:8 on a local named volume, which is convenient and has no backups. Either point MONGODB_URI at a managed instance such as MongoDB Atlas, or keep the local mongo service and treat the volume as the production data it is:

mongo:
  image: mongo:8
  volumes:
    - mongo-data:/data/db
  healthcheck:
    test:
      ['CMD', 'mongosh', '--quiet', '--eval', 'db.runCommand({ ping: 1 }).ok']
    interval: 5s
    timeout: 5s
    retries: 12
  restart: unless-stopped

with depends_on: { mongo: { condition: service_healthy } } on the setup service, and a scheduled mongodump against the volume. Everything a deployment cannot lose is in that database: end-user accounts, clients, the audit trail, and the signing keys.

To run PostgreSQL instead, swap the service for postgres:17, put POSTGRES_URL in the .env in place of MONGODB_URI and DATABASE_NAME, and change the setup command to ['bun', 'run', 'db:setup:pg']. Set one connection string, never both. Given both, the server refuses to start instead of picking one. PostgreSQL has the details.

restart: unless-stopped on the server, restart: 'no' on setup. The setup service is a one-shot that must exit; restarting it would loop. The server should come back after a host reboot or a crash — remember that a Machine which cannot reach the datastore exits at boot instead of serving, so a restart policy is how it recovers once the database comes back.

Bind the port to loopback and put a proxy in front. '127.0.0.1:3000:3000' keeps the plaintext port off the network. TLS terminates in the proxy, and ISSUER is the public https URL. Behind a reverse proxy has the nginx and Caddy blocks and the one setting you must get right there.

ISSUER is final before the first start

The setup service derives the console client’s redirect URI from ISSUER the first time it runs, and a later change is not repaired by re-running it. Put the final public URL in .env before the first docker compose up.

Upgrading

Change the tag and bring it up again:

docker compose pull
docker compose up -d

setup re-runs on every up, which is intended: both of its commands are safe to repeat, and together they apply a new release’s collections, indexes, seed changes and schema migrations. The server waits for it to complete successfully before starting, and would refuse to start without the migrations anyway. When the release notes name a migration that cannot be undone, take a backup before the up. The full checklist, including what a restart does and does not carry over, is in Upgrading.