Skip to main content

Docker Compose

Docker Compose is the fastest way to run auth-server locally exactly the way it runs in production, together with its Redis and MongoDB/PostgreSQL dependencies, without installing any of them on your host. It's also reasonable for a small, real, single-host deployment. Kubernetes (Helm) is the better choice once you need more than one replica or don't want to babysit the host yourself.

A pre-built image is published to GitHub for every tagged release, as both ghcr.io/rapidrest/auth-server:latest and the release's own version tag. As of this writing the project is pre-1.0 (0.1.0 in package.json) with no tagged release published yet, check the packages page above for the current version before pulling a specific tag. Either way, this doesn't matter for the Compose setup below: it builds the image from your own checked-out Dockerfile rather than pulling either of these.

Architecture​

Compose builds the image from the repository's Dockerfile and starts three containers on one network: server (the auth-server API), redis (cache, events, and log streaming), and either mongo or postgres (the primary datastore, depending on the compose file chosen).

      -----------------------------------------------------
     |                  compose network                     |
     |                                                       |
     |   ------------      ------------      --------------- |
     |  |   server   |<-->|   redis    |    | mongo/postgres| |
     |  | (built from|    |  (cache,   |    |  (primary     | |
     |  | Dockerfile)|    |  events,   |    |   datastore)  | |
     |   ------------      |  logs)    |     --------------- |
     |        |             ------------                     |
      -----------------------------------------------------
              |
     host:3000 (API)        host:9229 (Node inspector)

The Dockerfile builds in two stages: a builder stage installs dependencies and compiles the project, and a runner stage copies over just the compiled output, running as a non-root node user with a healthcheck against /.

Prerequisites​

  • Docker Engine with the Compose plugin

Running the Stack​

  1. Clone the repository. 
    git clone https://github.com/rapidrest/auth-server.git
    cd auth-server
  2. Run docker compose up using the database specific yaml (docker-compose.mongo.yml for Mongo, docker-compose.sql.yml for SQL). 
    # MongoDB
    docker compose -f docker-compose.mongo.yml up

    # PostgreSQL
    docker compose -f docker-compose.sql.yml up
  3. Open a browser to http://localhost:3000.

Configuration and installation details​

Debug and override overlays​

Two optional yaml files layer on top of either datastore variant to aid during debugging.

FileAdds
docker-compose.override.ymlPublishes the datastore ports (5432 for Postgres, 6379 for Redis) to the host.
docker-compose.debug.ymlRuns yarn debug instead of the built server and bind-mounts ./src and ./apps, so edits on the host take effect without rebuilding the image. Exposes port 9229 for remote debugging.

For example, a live-reloading SQL setup with datastore ports exposed:

docker compose -f docker-compose.sql.yml -f docker-compose.override.yml -f docker-compose.debug.yml up

Environment variable overrides​

The server configuration can be overridden in docker by modifying the environment section of the yaml file. Nested config variables can be referenced by replacing : with double underscore __ (e.g. datastores:mongo:url becomes datastores__mongo__url).

For example, overriding the mongo and cache datastores is done as follows:

services:
  server:
    environment:
      datastores__mongo__url=mongodb://mongo
      datastores__cache__url=redis://redis

Production secrets​

auth-server ships with fixed development defaults for cookie_secret, auth:secret, and session:secret. It refuses to start in production if any of the three are still at their default value, so set COOKIE_SECRET, AUTH__SECRET, and SESSION__SECRET to unique values before deploying for real. It also warns, without refusing to start, if the placeholder OIDC clientID/clientSecret are still active and OIDC sign-in is enabled.

See also​