# Install with Docker

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

## Prerequisites

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

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

```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/*
```

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 `./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](/docs/sentinel/v2/install/#secrets). All keys are listed in the [Configuration reference](/docs/sentinel/v2/reference/configuration/).

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:

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

```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 6 ms
```

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

## Step 3 — Start the container

```bash
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](#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:

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

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

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

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

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

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

```bash
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](/docs/sentinel/v2/reference/cli/) 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:

```bash
sudo chown 65532:65532 tls/privkey.pem
chmod 600 tls/privkey.pem
```

2. Add `tls` to each listener you publish in `sentinel.toml`:

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

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

```bash
curl -s https://sentinel.example.com:3000/
```

```json
{"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](/docs/sentinel/v2/reference/configuration/#listener-tls).

## 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.
- [The configuration file](/docs/sentinel/v2/configure/): variable expansion and the full layout of `sentinel.toml`.
- [Install with Docker Compose](/docs/sentinel/v2/install/docker-compose/): run Sentinel with Redis and a database.
- [Install Sentinel](/docs/sentinel/v2/install/): production requirements before you go live.
