# Install with Docker Compose

> **Sentinel v2 (beta):** This page documents Sentinel v2, a beta rewrite that may change before the stable release. It does not apply to Sentinel v1, the current stable version: see the [Sentinel v1 documentation](/docs/sentinel.md).

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](/docs/sentinel/v2/install/).

## 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](https://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.

```bash
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:

```toml
[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](/docs/sentinel/v2/reference/configuration/).

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:

```yaml
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](/docs/sentinel/v2/operations/clustering/#instance-slots). 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](#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:

```yaml
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:

```bash
docker compose run --rm sentinel doctor --config-only
```

```text
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

```bash
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`:

```bash
docker compose ps --format '{{.Service}}: {{.Status}}'
```

```text
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`.

> **Warning:**
>
> `[bootstrap] root_password` is applied only when the root user is created on first boot. Changing it later has no effect; change the password in the admin UI instead.

## Verify it works

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

```bash
curl -s http://localhost:3000/
```

```json
{"ok":true}
```

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

```bash
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](/docs/sentinel/v2/reference/cli/) 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](/docs/sentinel/v2/operations/clustering/#requirements). This stack runs everything on one host: PostgreSQL as the database, Valkey as the KV store, and two Sentinel services.

<Callout type="note" title="License required">

PostgreSQL needs the <code>exotdb.backend.postgres</code> license feature. Without it, Sentinel starts but answers most `/v2` requests with `403 BACKEND_NOT_LICENSED`. See [Plans & Licensing](/docs/sentinel/v2/plans/).

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:

```bash
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](/docs/sentinel/v2/configure/secrets/).

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

```toml
[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:

```yaml
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](/docs/sentinel/v2/install/#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:**

```bash
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](/docs/sentinel/v2/operations/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](/docs/sentinel/v2/operations/snapshots/#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](/docs/sentinel/v2/operations/clustering/#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](/docs/sentinel/v2/configure/listeners/#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](/docs/sentinel/v2/install/docker/#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](/docs/sentinel/v2/operations/updating/#before-you-update). Then change the image tag in `compose.yaml` and pull the new image:

```bash
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:

```bash
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:

```bash
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](/docs/sentinel/v2/operations/updating/).

## Next steps

- [Create a security group and an API key](/docs/sentinel/v2/get-started/), then embed the widget.
- [Licensing](/docs/sentinel/v2/configure/licensing/): offline license files and instance slots.
- [Databases & KV store](/docs/sentinel/v2/configure/databases/): other database backends, TLS, and Redis Sentinel.
- [Snapshots & backups](/docs/sentinel/v2/operations/snapshots/): back up the database before you go live.
- [Install Sentinel](/docs/sentinel/v2/install/): production requirements, and the [Production checklist](/docs/sentinel/v2/security/production-checklist/).
