Skip to main content
ALTCHA®

Install with Docker Compose

Run Sentinel with Docker Compose when you want the configuration, secrets, and supporting services in one file. This page starts with a single instance on embedded SQLite, then extends it to two replicas with PostgreSQL and Valkey on the same host.

For the license, secrets, database, and Redis requirements of a production install, see Install Sentinel.

Prerequisites

  • Docker Engine with the Compose plugin (docker compose), on an amd64 or arm64 host.
  • A Sentinel license key. To get a trial, register at cloud.altcha.org and create a Sentinel V2 trial license in the Licenses section.
  • Ports 3000 (main API) and 3002 (admin UI) free on the host.

Step 1 — Create the secret files

Compose mounts each declared secret file at /run/secrets/<name> in the container, and Sentinel reads it with a ${file:/run/secrets/…} reference in the configuration.

mkdir -p sentinel/secrets && cd sentinel
printf '%s' 'SENT-…' > secrets/sentinel_license_key   # your license key
openssl rand -base64 24 > secrets/root_password        # first root password
chmod 644 secrets/*

Without Docker Swarm, Compose bind-mounts the files as they are, with their host owner and mode. The container runs as user 65532, so the files must be readable by that user: chmod 644 is the simplest option; alternatively, chown 65532:65532 the files and keep them at 600.

Step 2 — Write sentinel.toml

Create sentinel.toml next to the secrets folder:

[server.admin_ui]
enabled = true
host    = "0.0.0.0"   # listen on all container interfaces so the published port works

[license]
key = "${file:/run/secrets/sentinel_license_key}"

[bootstrap]
root_password = "${file:/run/secrets/root_password}"   # applied on first boot only

Every other key keeps its default: the main API listens on port 3000, data goes to /home/nonroot/data in the container, and the signing and encryption secrets are generated into the data volume on first start. All keys are listed in the Configuration reference.

Keep the configuration in its own file. Compose expands ${…} only in compose.yaml, so the references in a mounted sentinel.toml reach Sentinel unchanged.

Step 3 — Write compose.yaml

Create compose.yaml in the same folder:

services:
  sentinel:
    image: ghcr.io/altcha-org/sentinel:2.0.0-beta.1
    hostname: sentinel-1   # node ID for the license instance slot
    restart: unless-stopped
    ports:
      - "3000:3000"             # main API, for widgets and backends
      - "127.0.0.1:3002:3002"   # admin UI, host loopback only
    volumes:
      - ./sentinel.toml:/home/nonroot/sentinel.toml:ro
      - sentinel-data:/home/nonroot/data
    secrets:
      - sentinel_license_key
      - root_password

volumes:
  sentinel-data:

secrets:
  sentinel_license_key:
    file: ./secrets/sentinel_license_key
  root_password:
    file: ./secrets/root_password
  • Use an exact 2.0.0-beta.x tag; during the beta, latest still points to Sentinel v1.
  • hostname sets the HOSTNAME variable, which Sentinel uses as the node ID of its license instance slot. Without it, Docker uses the container ID, which changes each time Compose recreates the container. With a fixed value, a container that crashed or was killed takes its previous slot back at once instead of waiting up to 30 seconds for the old lease to expire.
  • The admin UI is published on the host's loopback interface only. Before you expose it further, serve it over HTTPS (see HTTPS): outside localhost, the session cookie requires HTTPS.
  • sentinel-data is a named volume. Docker initializes it with the correct owner, so Sentinel can write to it. If you bind-mount a host folder instead, chown 65532:65532 it first.

The image's built-in health check runs altcha-sentinel healthcheck against /home/nonroot/sentinel.toml, so the service needs no healthcheck block. If you mount the configuration elsewhere, pass --config to both the server and the health check:

services:
  sentinel:
    command: ["--config", "/etc/sentinel/sentinel.toml"]
    healthcheck:
      test: ["CMD", "/usr/local/bin/altcha-sentinel", "--config", "/etc/sentinel/sentinel.toml", "healthcheck"]

Validate the configuration with the service's mounts and secrets before you start it. The image's entrypoint is the altcha-sentinel binary, so the arguments after the service name go to it:

docker compose run --rm sentinel doctor --config-only
altcha-sentinel 2.0.0-beta.1 doctor, config: sentinel.toml

config
  ok    config.file   Loaded sentinel.toml.
  ok    config.valid  The configuration passes the startup checks.

2 ok, 0 warn, 0 fail, 0 skipped in 20 ms

A FAIL line names the key and the reason, and the command exits with code 1.

Step 4 — Start the stack

docker compose up -d
docker compose logs sentinel

The log shows the license status (for example licensed to "…"), created root user from bootstrap.root_password, and a listening addr=0.0.0.0:3000 line. If you didn't set [bootstrap] root_password, the log contains the generated root password instead.

Once the image's health check passes, the service reports healthy:

docker compose ps --format '{{.Service}}: {{.Status}}'
sentinel: Up 40 seconds (healthy)

Step 5 — Sign in

Open http://localhost:3002 and sign in with the username root and the password from secrets/root_password.

Verify it works

Call the main API's status endpoint from the host:

curl -s http://localhost:3000/
{"ok":true}

To check the configuration, storage, and network access from inside the running container, run doctor in it:

docker compose exec sentinel /usr/local/bin/altcha-sentinel doctor

doctor prints one line per check and exits with 1 if any check fails. With this setup, security.admin_ui warns that the admin UI listens beyond loopback: inside the container it listens on all interfaces, while the host publishes it on loopback only. security.root_mfa warns until you enable TOTP or a passkey for root. See the CLI reference for the options.

Run two replicas with PostgreSQL and Valkey

A second replica keeps Sentinel available while you restart or update the other one. Every replica must share an external database, a Redis-compatible KV store, and the same secrets; see Clustering & high availability. This stack runs everything on one host: PostgreSQL as the database, Valkey as the KV store, and two Sentinel services.

  1. Add the secrets. With an external database, Sentinel no longer generates its signing and encryption keys, and every replica must use the same values. Generate them, and a password for PostgreSQL, next to the existing files:

    openssl rand -hex 32 > secrets/jwt_secret
    openssl rand -hex 32 > secrets/altcha_hmac_secret
    openssl rand -hex 32 > secrets/encryption_key
    openssl rand -hex 24 > secrets/db_password   # hex: no escaping in the URL
    chmod 644 secrets/*

    Back up these files with the database: a different encryption_key can't read the API key and TOTP secrets stored in it. See Server secrets.

  2. Point sentinel.toml at the database and Valkey, using the Compose service names as host names:

    [server.admin_ui]
    enabled = true
    host    = "0.0.0.0"
    
    [database]
    url = "postgres://sentinel:${file:/run/secrets/db_password}@postgres:5432/sentinel"
    
    [redis]
    nodes = ["redis://valkey:6379"]
    
    [secrets]
    jwt_secret         = "${file:/run/secrets/jwt_secret}"
    altcha_hmac_secret = "${file:/run/secrets/altcha_hmac_secret}"
    encryption_key     = "${file:/run/secrets/encryption_key}"
    
    [license]
    key = "${file:/run/secrets/sentinel_license_key}"
    
    [bootstrap]
    root_password = "${file:/run/secrets/root_password}"
  3. Replace compose.yaml. The x-sentinel block holds the settings both replicas share; each service adds its own hostname, ports, and data volume:

    x-sentinel: &sentinel
      image: ghcr.io/altcha-org/sentinel:2.0.0-beta.1
      restart: unless-stopped
      secrets:
        - sentinel_license_key
        - root_password
        - jwt_secret
        - altcha_hmac_secret
        - encryption_key
        - db_password
      depends_on:
        postgres:
          condition: service_healthy
        valkey:
          condition: service_healthy
    
    services:
      sentinel-1:
        <<: *sentinel
        hostname: sentinel-1
        ports:
          - "3000:3000"
          - "127.0.0.1:3002:3002"
        volumes:
          - ./sentinel.toml:/home/nonroot/sentinel.toml:ro
          - sentinel-1-data:/home/nonroot/data
    
      sentinel-2:
        <<: *sentinel
        hostname: sentinel-2
        ports:
          - "3010:3000"
          - "127.0.0.1:3012:3002"
        volumes:
          - ./sentinel.toml:/home/nonroot/sentinel.toml:ro
          - sentinel-2-data:/home/nonroot/data
    
      postgres:
        image: postgres:18-alpine
        restart: unless-stopped
        environment:
          POSTGRES_USER: sentinel
          POSTGRES_DB: sentinel
          POSTGRES_PASSWORD_FILE: /run/secrets/db_password
        secrets:
          - db_password
        volumes:
          - postgres-data:/var/lib/postgresql
        healthcheck:
          test: ["CMD", "pg_isready", "-U", "sentinel", "-d", "sentinel"]
          interval: 5s
          timeout: 5s
          retries: 10
    
      valkey:
        image: valkey/valkey:8.1-alpine
        restart: unless-stopped
        command: ["valkey-server", "--maxmemory", "256mb", "--maxmemory-policy", "noeviction", "--appendonly", "yes"]
        volumes:
          - valkey-data:/data
        healthcheck:
          test: ["CMD", "valkey-cli", "ping"]
          interval: 5s
          timeout: 5s
          retries: 10
    
    volumes:
      sentinel-1-data:
      sentinel-2-data:
      postgres-data:
      valkey-data:
    
    secrets:
      sentinel_license_key:
        file: ./secrets/sentinel_license_key
      root_password:
        file: ./secrets/root_password
      jwt_secret:
        file: ./secrets/jwt_secret
      altcha_hmac_secret:
        file: ./secrets/altcha_hmac_secret
      encryption_key:
        file: ./secrets/encryption_key
      db_password:
        file: ./secrets/db_password
    • Each replica has its own hostname, so each holds its own instance slot, and its own data volume for downloaded remote files. Don't share one data volume between replicas.
    • PostgreSQL and Valkey publish no ports; only the Sentinel services reach them, over the stack's network. Valkey runs without a password for that reason. If anything outside the stack can reach it, add authentication and put the password in the redis:// URL.
    • Valkey uses noeviction and AOF persistence (--appendonly yes), so replay claims and rate-limit counters survive a restart of Valkey. Size --maxmemory for your traffic with Redis or Valkey; don't go below 256mb.
    • Each replica opens up to [database] pool_max connections (default 20), well below PostgreSQL's default limit of 100.
  4. Validate and start the stack:

    docker compose run --rm --no-deps sentinel-1 doctor --config-only
    docker compose up -d

    Compose starts PostgreSQL and Valkey, waits for them to be healthy, then starts both replicas. They migrate one at a time under a database lock: one logs schema migrations complete applied=…, and the other finds the schema current and logs applied=0. See Schema migrations.

If you're replacing the single-instance stack, stop it with docker compose down before you replace compose.yaml; otherwise its container keeps port 3000. The new stack starts with an empty PostgreSQL database, and the old sentinel-data volume stays untouched. To carry over accounts, keys, and security groups, follow Restore into a fresh deployment: the restored API keys work only with the old encryption_key, which the single instance generated into secrets.json in its data volume.

Send traffic to both replicas through a load balancer or reverse proxy, here on host ports 3000 and 3010, and check that it removes a replica that stops answering GET /. To see both replicas, open Cluster in the admin UI, or see List the replicas.

HTTPS

Serve every published listener over HTTPS before you expose it beyond the host. Either:

  • put a TLS-terminating reverse proxy in front of the published ports, and set [server] trusted_proxies so Sentinel sees the real client IPs; see Behind a reverse proxy or CDN; or
  • let Sentinel terminate TLS: mount the certificate folder read-only (for example ./tls:/etc/sentinel/tls:ro under volumes) and add tls to each published listener, as in Serve HTTPS from the container. Sentinel reads the files only at startup, so restart the Sentinel services after each renewal, one at a time with two replicas (docker compose restart sentinel-1, then sentinel-2).

Update Sentinel

Before an update, read the release notes and take a snapshot, as described in Before you update. Then change the image tag in compose.yaml and pull the new image:

docker compose pull
docker compose run --rm sentinel doctor   # in the two-replica stack: sentinel-1

doctor checks the configuration against the new version, and storage.schema reports how many schema changes it will apply at startup.

Single instance: recreate the container:

docker compose up -d

Sentinel is unavailable for a few seconds while the container restarts and migrates the schema.

Two replicas: docker compose up -d would stop both replicas at the same time. Recreate them one at a time instead; --wait returns once the new container is healthy:

docker compose up -d --no-deps --wait sentinel-1
docker compose up -d --no-deps --wait sentinel-2

The first new replica migrates the schema, and the old replica keeps working against it meanwhile. Rolling updates, burst slots, and rollback are covered in Updating Sentinel.

Next steps

Start typing to search...

↑ ↓ Navigate ↵ Select