Skip to main content
ALTCHA®

Install with Docker

Run Sentinel as a single Docker container. This is the quickest way to run one Sentinel instance.

This guide runs one instance on the embedded SQLite database. For the license, secrets, database, and Redis requirements of a production install, see Install Sentinel.

Prerequisites

  • Docker 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

docker run has no secrets store of its own, so keep each secret in a file and bind-mount the folder at /run/secrets in the container. Sentinel reads them with ${file:/run/secrets/…} references 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/*

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 ./data (/home/nonroot/data in the container), and the signing and encryption secrets are generated into the data volume on first start. To set those secrets yourself, see Secrets. All keys are listed in the Configuration reference.

Validate the file before you start the server. The image's entrypoint is the altcha-sentinel binary, so the arguments after the image name are passed to it:

docker run --rm \
  -v "$PWD/sentinel.toml:/home/nonroot/sentinel.toml:ro" \
  -v "$PWD/secrets:/run/secrets:ro" \
  ghcr.io/altcha-org/sentinel:2.0.0-beta.1 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 6 ms

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

Step 3 — Start the container

docker run -d --name sentinel \
  -p 3000:3000 \
  -p 127.0.0.1:3002:3002 \
  -v "$PWD/sentinel.toml:/home/nonroot/sentinel.toml:ro" \
  -v "$PWD/secrets:/run/secrets:ro" \
  -v sentinel-data:/home/nonroot/data \
  ghcr.io/altcha-org/sentinel:2.0.0-beta.1
  • -p 3000:3000 publishes the main API, which your widgets and backends call.
  • -p 127.0.0.1:3002:3002 publishes the admin UI on the host's loopback interface only. Before you expose it further, serve it over HTTPS, with tls on the listener (see Serve HTTPS from the container) or a proxy in front: 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.

Use an exact 2.0.0-beta.x tag; during the beta, latest still points to Sentinel v1.

Check the startup log:

docker logs sentinel

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

Step 4 — Check the container health

The image has a built-in health check that runs altcha-sentinel healthcheck every 10 seconds. The command sends GET / to the port in [server] port (over HTTPS when [server] tls is set) and exits with 0 when the server answers, or 1 otherwise. After the 30-second start period, the container reports healthy:

docker inspect --format '{{.State.Health.Status}}' sentinel
healthy

The built-in check reads /home/nonroot/sentinel.toml. If you mount the configuration elsewhere and start Sentinel with --config, pass the same flag to the health check:

docker run -d --name sentinel \
  -p 3000:3000 \
  -p 127.0.0.1:3002:3002 \
  -v "$PWD/sentinel.toml:/etc/sentinel/sentinel.toml:ro" \
  -v "$PWD/secrets:/run/secrets:ro" \
  -v sentinel-data:/home/nonroot/data \
  --health-cmd '/usr/local/bin/altcha-sentinel --config /etc/sentinel/sentinel.toml healthcheck' \
  ghcr.io/altcha-org/sentinel:2.0.0-beta.1 --config /etc/sentinel/sentinel.toml

Without the flag, the health check finds no ./sentinel.toml and probes the default port 3000, which fails when [server] port is different. The failure message on stderr then says so:

no --config and no ./sentinel.toml: probed the default port 3000; pass the server's --config

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 of the container, run doctor inside it:

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

doctor prints one line per check and exits with 1 if any check fails. See the CLI reference for its options.

Serve HTTPS from the container

Without a proxy in front, Sentinel can terminate TLS itself. Each listener has its own tls setting with a PEM certificate chain and key.

  1. Put the certificate chain and key in a folder, for example tls/fullchain.pem and tls/privkey.pem. The container runs as uid 65532, so make the key readable for it:

    sudo chown 65532:65532 tls/privkey.pem
    chmod 600 tls/privkey.pem
  2. Add tls to each listener you publish in sentinel.toml:

    [server]
    tls = { cert = "/etc/sentinel/tls/fullchain.pem", key = "/etc/sentinel/tls/privkey.pem" }
    
    [server.admin_ui]
    enabled = true
    tls = { cert = "/etc/sentinel/tls/fullchain.pem", key = "/etc/sentinel/tls/privkey.pem" }
  3. Mount the folder read-only and recreate the container:

    docker run -d --name sentinel \
      -p 3000:3000 \
      -p 127.0.0.1:3002:3002 \
      -v "$PWD/sentinel.toml:/home/nonroot/sentinel.toml:ro" \
      -v "$PWD/secrets:/run/secrets:ro" \
      -v "$PWD/tls:/etc/sentinel/tls:ro" \
      -v sentinel-data:/home/nonroot/data \
      ghcr.io/altcha-org/sentinel:2.0.0-beta.1

The log now shows listening addr=0.0.0.0:3000 tls=true, and the main API answers over HTTPS with HTTP/2 or HTTP/1.1:

curl -s https://sentinel.example.com:3000/
{"ok":true}

An unreadable file or a key that doesn't match the certificate stops startup, and the log names the setting (for example server.tls: certificate and key). To catch this before you start the container, add the tls mount to the doctor --config-only run from Step 2; it loads the certificates the same way. The built-in health check switches to HTTPS on its own and doesn't check the certificate. Sentinel reads the files only at startup, so run docker restart sentinel after each renewal. See Listener TLS.

Next steps

Start typing to search...

↑ ↓ Navigate ↵ Select