Run with Docker

Docker Compose

1. In an empty directory, save this file as docker-compose.yml. It starts Mongo and turns it into a replica set of one, starts Redis, prepares a volume for uploaded files, runs the migration, and only then starts the CMS. A comment above each line says what that line does. The migration mounts the files volume too, because it checks the files directory on start. The CMS restarts after a crash and gets fifteen seconds to stop, which is longer than its own ten-second drain.

# Quillet 1.1 on one machine: the CMS, Mongo, Redis, a volume for files.
# The two secrets come from the .env file beside this one, which Compose reads by itself.

# The CMS's settings, shared by `migrate` and `cms` below.
x-cms-env: &cms-env
  # Mongo, as a replica set: the CMS needs transactions.
  MONGO_URI: mongodb://mongo:27017/quillet?replicaSet=rs0
  # Sessions, rate-limit counters and the delivery cache.
  REDIS_URL: redis://redis:6379
  # Signs the session cookie: 32 characters or more, from .env.
  SESSION_SECRET: ${SESSION_SECRET:?set it in .env}
  # Seals webhook secrets: 32 bytes, base64, from .env. Required.
  WEBHOOK_SECRET_KEY: ${WEBHOOK_SECRET_KEY:?set it in .env}
  # The address the browser uses, port included.
  BASE_URL: http://localhost:3000
  # Lets the first account sign up. Set it to closed once your team is in.
  AUTH_REGISTRATION: open
  # Uploaded files go to a directory rather than a bucket...
  ASSET_BACKEND: disk
  # ...this one, inside the container: the `assets` volume.
  ASSET_DISK_ROOT: /data/assets

# Six containers. Three run once and exit: mongo-init, assets-init, migrate.
services:
  # The database.
  mongo:
    # Mongo 7; any later version works too.
    image: mongo:7
    # Start as a member of the replica set rs0.
    command: ["--replSet", "rs0", "--bind_ip_all"]
    # Healthy once it answers a ping,
    healthcheck:
      # which is this command,
      test: ["CMD", "mongosh", "--quiet", "--eval", "db.adminCommand('ping').ok ? 0 : quit(1)"]
      # tried every five seconds,
      interval: 5s
      # each try failing if it takes longer than five,
      timeout: 5s
      # unhealthy after twenty failures in a row,
      retries: 20
      # not counting any in the first ten seconds.
      start_period: 10s
    # Keep the data when the container is replaced:
    volumes:
      # Mongo's data directory, on the named volume `mongo-data`.
      - mongo-data:/data/db

  # Runs once: makes the lone Mongo a one-node replica set.
  mongo-init:
    # The same image, for its shell.
    image: mongo:7
    # Wait for the database
    depends_on:
      mongo:
        # to answer its ping.
        condition: service_healthy
    # Try again if Mongo was not ready yet.
    restart: on-failure
    # Run one line of Mongo shell...
    entrypoint: ["mongosh", "--host", "mongo:27017", "--quiet", "--eval"]
    # ...which initiates the replica set unless that is already done.
    command: ["try { rs.status() } catch (e) { rs.initiate({ _id: 'rs0', members: [{ _id: 0, host: 'mongo:27017' }] }) }"]

  # The cache and the session store.
  redis:
    # Redis 7. Nothing in it needs to survive a restart: losing it signs everyone out, nothing more.
    image: redis:7

  # Runs once: a new volume belongs to root, and the CMS runs as `node`.
  assets-init:
    # The CMS image, which has the `node` user.
    image: iegork/quillet:1.1
    # As root, for this one command:
    user: "0"
    # give the files directory to `node`.
    entrypoint: ["chown", "node:node", "/data/assets"]
    # The volume the CMS writes files to,
    volumes:
      # mounted where ASSET_DISK_ROOT points.
      - assets:/data/assets

  # Runs once: builds Mongo's indexes before the CMS takes traffic.
  migrate:
    # The CMS image.
    image: iegork/quillet:1.1
    # The index migration. Safe to run again on every start.
    command: ["node", "apps/api/dist/.scripts/scripts/migrate.js"]
    # The same settings as the server.
    environment: *cms-env
    # It checks the files directory on start, as the server does,
    volumes:
      # so it mounts the same volume.
      - assets:/data/assets
    # Only after
    depends_on:
      # the replica set exists
      mongo-init:
        condition: service_completed_successfully
      # and the files directory is writable.
      assets-init:
        condition: service_completed_successfully

  # The CMS: the dashboard, the management API and the delivery API.
  cms:
    # Quillet CMS 1.1 from Docker Hub. Move to a new tag deliberately.
    image: iegork/quillet:1.1
    # Come back after a crash or a reboot.
    restart: unless-stopped
    # A stop waits up to fifteen seconds, longer than the CMS's own ten-second drain.
    stop_grace_period: 15s
    # Published on the host
    ports:
      # at http://localhost:3000.
      - "3000:3000"
    # The settings at the top.
    environment: *cms-env
    # Uploaded files
    volumes:
      # live on the `assets` volume.
      - assets:/data/assets
    # Start only once
    depends_on:
      # the indexes are built
      migrate:
        condition: service_completed_successfully
      # and Redis is running.
      redis:
        condition: service_started

# Named volumes, kept until `docker compose down -v`.
volumes:
  # Mongo's data.
  mongo-data:
  # Uploaded files.
  assets:

2. Write the two secrets into a .env file beside it. Compose reads that file by itself and refuses to start while either value is missing.

printf 'SESSION_SECRET=%s\nWEBHOOK_SECRET_KEY=%s\n' "$(openssl rand -base64 48)" "$(openssl rand -base64 32)" > .env

3. Start the CMS and everything it depends on. The command returns once the CMS reports itself healthy, which takes under a minute when the images are already pulled.

docker compose up -d --wait cms

docker run

1. Write the settings into a file called quillet.env, one NAME=value per line. Replace each value in angle brackets with your own: generate SESSION_SECRET with openssl rand -base64 48 and WEBHOOK_SECRET_KEY with openssl rand -base64 32. The Mongo and Redis addresses must be reachable from inside the container: localhost there is the container itself, not your machine.

MONGO_URI=<mongodb://mongo.example.internal:27017/quillet?replicaSet=rs0>
REDIS_URL=<redis://redis.example.internal:6379>
SESSION_SECRET=<at least 32 random characters>
WEBHOOK_SECRET_KEY=<32 bytes in base64>
BASE_URL=http://localhost:3000
AUTH_REGISTRATION=open
ASSET_BACKEND=disk
ASSET_DISK_ROOT=/data/assets

2. Create a volume for uploaded files and hand it to the image's node account. A new volume belongs to root, so without this step node cannot write to it.

docker volume create quillet-assets
docker run --rm -u 0 -v quillet-assets:/data/assets --entrypoint chown iegork/quillet:1.1 node:node /data/assets

3. Run the migration. It prints one JSON line per collection and ends with {"event":"migrate.complete"}.

docker run --rm --env-file quillet.env -v quillet-assets:/data/assets iegork/quillet:1.1 node apps/api/dist/.scripts/scripts/migrate.js

4. Start the CMS.

docker run -d --name quillet --restart unless-stopped --stop-timeout 15 --env-file quillet.env -v quillet-assets:/data/assets -p 3000:3000 iegork/quillet:1.1