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) and3002(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 onlyEvery 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.xtag; during the beta,lateststill points to Sentinel v1. hostnamesets theHOSTNAMEvariable, 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-datais 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:65532it 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-onlyaltcha-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 msA 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 sentinelThe 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 doctordoctor 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.
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_keycan't read the API key and TOTP secrets stored in it. See Server secrets.Point
sentinel.tomlat 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}"Replace
compose.yaml. Thex-sentinelblock 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
noevictionand AOF persistence (--appendonly yes), so replay claims and rate-limit counters survive a restart of Valkey. Size--maxmemoryfor your traffic with Redis or Valkey; don't go below256mb. - Each replica opens up to
[database] pool_maxconnections (default20), well below PostgreSQL's default limit of100.
- Each replica has its own
Validate and start the stack:
docker compose run --rm --no-deps sentinel-1 doctor --config-only docker compose up -dCompose 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 logsapplied=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_proxiesso 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:roundervolumes) and addtlsto 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, thensentinel-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-1doctor 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 -dSentinel 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-2The 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
- Create a security group and an API key, then embed the widget.
- Licensing: offline license files and instance slots.
- Databases & KV store: other database backends, TLS, and Redis Sentinel.
- Snapshots & backups: back up the database before you go live.
- Install Sentinel: production requirements, and the Production checklist.