# Install Sentinel

> **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).

Sentinel runs as a container image for amd64 and arm64. This page lists what every production install needs; the platform guides link back here instead of repeating it.

To try Sentinel on your machine first, follow [Get started](/docs/sentinel/v2/get-started/).

## Requirements at a glance

| Requirement | Single instance | Several replicas |
| --- | --- | --- |
| Container runtime | Docker or any OCI runtime | Kubernetes, ECS, App Service, or Compose |
| License | Required to serve challenges, verification, and feature endpoints | Required; its `instances` limit caps the replica count |
| Configuration | One `sentinel.toml` | The same `sentinel.toml` on every replica |
| Database | Embedded SQLite in the data volume (default) | A shared external database |
| Redis | Not needed | Required |
| Secrets | Generated into the data volume, or set explicitly | Set explicitly, identical on every replica |
| Persistent volume | Required for `/home/nonroot/data` | Recommended (remote files and caches) |
| HTTPS | `tls` on the exposed listeners, or a TLS-terminating proxy in front | A TLS-terminating load balancer, or `tls` on every replica |

## Sizing

CPU is mostly spent deriving proof-of-work challenges and classifying text; memory depends on the features you enable.

| Deployment | CPU | Memory |
| --- | --- | --- |
| Evaluation, low traffic | 1 vCPU | 512 MB |
| Production, per replica | 2 vCPU or more, compute-optimized | 1 GB or more |

Use compute-optimized instances in production, such as AWS C-family (`c7a`, `c7i`, `c7g`), Google Cloud C-series (`c3`, `c3d`, `c4`), or Azure F-series. Avoid burstable instances such as AWS `t3`: their CPUs are slower, and they're throttled to a baseline once their CPU credits run out.

Up to `[pow] cpus` challenges are derived at once, and the default is half the available CPUs. If challenges make up most of your traffic, set it to the vCPU count. 

Add memory for these features:

- **Local similarity model** (`[similarity] provider = "local"`): the model and tokenizer are about 135 MB to download, and each ONNX session (`[similarity.local] sessions`, default `1`) holds its own copy of the model in memory.
- **Memory-hard proof of work** (`pow.algorithm` set to `ARGON2ID` or `SCRYPT` in a security group): every challenge derivation allocates its memory cost (default `65536` KiB for `ARGON2ID`, capped by `[pow] max_memory_cost`). Up to `[pow] cpus` derivations run at once (default: half the available CPUs).

For a sense of throughput, a benchmark on an AWS `c7a.medium` (1 vCPU, 2 GiB) with an external Redis, with the load generator on a separate machine sending 16 concurrent requests, measured:

| Endpoint | Requests per second | p99 latency |
| --- | --: | --: |
| `GET /v2/challenge` (default PBKDF2 cost) | about 1,500 | 11 ms |
| `POST /v2/verify` | about 4,400 | 5.1 ms |
| `POST /v2/verify` with fields classified | about 1,000 | 26 ms |
| `POST /v2/verify/signature` | about 6,900 | 3.3 ms |
| `POST /v2/classifier` | about 900 | 26 ms |

Measure your own traffic mix before you size a cluster. Each replica reports its CPU and memory use; see [Monitoring](/docs/sentinel/v2/operations/monitoring/) and [Performance](/docs/sentinel/v2/operations/performance/).

### Database size

Accounts, users, API keys, security groups, and threat sources take a few megabytes at most. The database grows with request logs, their hourly statistics, and, without Redis, the built-in KV store:

| Data | Written when | Kept for | Space per row, SQLite / PostgreSQL |
| --- | --- | --- | --: |
| Request logs | Every request of an API key whose `requestLogging` is `verification` or `all` (default `none`); not with [ClickHouse](/docs/sentinel/v2/operations/clickhouse/) | `[request_logs] retention`, default `72h` | about 370 B / 400 B |
| Hourly request statistics | One row per API key and UTC hour with logged requests | Indefinitely | about 1 KB, more with many countries, referrers, and rules |
| Built-in KV store | Without `[redis] nodes`, the same entries as in the [Redis table](#redis-or-valkey) | As in Redis | about 180 B / 300 B |
| Audit logs and alerts | Sign-ins, management changes, raised alerts | `[audit_logs] retention` and `[alerts] retention`, default `90d` | small |

Sizes include indexes. They were measured on SQLite and PostgreSQL 18 with logs of `GET /v2/challenge`, `POST /v2/verify` with two classified fields, and `POST /v2/verify/signature`.

Request logs usually dominate. Estimate them as average logged requests per second × retention in seconds × 400 B. With `requestLogging` set to `all`, one form submission logs a challenge and a verification on the widget key, plus a signature check if your backend's key logs too.

| Average logged requests per second | Retention `72h` (default) | Retention `7d` |
| --: | --- | --- |
| 1 | about 100 MB | about 250 MB |
| 10 | about 1 GB | about 2.4 GB |
| 100 | about 10 GB | about 24 GB |

Hourly statistics add about 10 MB per API key per year of continuous traffic. For high volumes or long retention, store request logs in [ClickHouse](/docs/sentinel/v2/operations/clickhouse/), which keeps both the raw logs and the statistics out of the main database.

Without Redis, every `/v2` request also writes rate-limit counters to the database, and every verification and signature check writes a replay claim, so the database takes writes on every request. Use [Redis or Valkey](#redis-or-valkey) to move that load off the database; see [Built-in KV store](/docs/sentinel/v2/configure/databases/#built-in-kv-store).

Deleted rows free space for new rows, but embedded SQLite doesn't shrink its file. Whatever the backend, the data volume also holds the threat-list indexes and downloaded remote files, about 230 MB with the default sources. Give it at least 1 GB, plus your database estimate with embedded SQLite.

### Redis or Valkey

An external KV store (`[redis] nodes` or `[redis.sentinel]`) holds the short-lived state that every replica must share, and carries messages between replicas. Every key Sentinel writes has an expiry, so memory depends on your request rate and how long each entry lives, not on the size of your database.

| Data | Written by | Kept for | Memory per entry |
| --- | --- | --- | --: |
| Replay protection: one claim per verified challenge, and one per payload checked by `POST /v2/verify/signature` | `POST /v2/verify`, `POST /v2/verify/signature` | Until the challenge expires: `pow.expires`, default `20m`, at most `24h` | about 130 B |
| Rate-limit counters | Every `/v2` request (`[rate_limit] global`), security-group `rateLimit.limits`, classifier and audio limits | One window of the limit | about 150 B per client and limit |
| Penalties | Failed verifications, rate-limit pressure, `penalty.add` rules, header entropy | `[penalty] ttl` after the last increase, default `30m` | about 150 B per account and client IP |
| Header entropy | `GET /v2/challenge` and `GET /v2/inspect`, when `headerEntropy.limit` is set | The `headerEntropy.limit` window | up to about 2 KB per client IP |
| HIS replay detection | `POST /v2/challenge`, when `his.mode` isn't `off` | 10 minutes for human-like interaction, up to `his.hashTtl` (default `12h`) for bot-like interaction | about 3 KB per challenge |
| Campaign detection | Each classified text of at least `[similarity.campaign] min_chars` (default `30`) characters | `[similarity.campaign] window`, default `1h` | about 1 KB per text |
| Sign-in and alert state | Logins, OTP, passkeys, step-up, alert evaluation, threat signals | Minutes to hours | negligible |

Pub/sub carries replica status, API-key and security-group change notices, and threat-list updates between replicas; it stores nothing. The sizes above were measured on Redis 7.4 and Valkey 8.1 with the default `key_prefix`; Valkey needs the same or up to about 20% less.

Replay claims usually dominate. Estimate them as peak verifications per second × `pow.expires` in seconds × 130 B, doubled when your backend calls `POST /v2/verify/signature` for every submission. Add HIS at about 3 KB per scored challenge for as long as it is kept. Rate-limit counters are small in comparison: 60,000 distinct client IPs per minute under the default `100/1m` global limit take about 9 MB.

| Peak verifications per second | Without HIS | With HIS (about 15 minutes kept) |
| --: | --- | --- |
| 10 | about 3 MB; give it 256 MB | about 30 MB; give it 256 MB |
| 100 | about 30 MB; give it 256 MB | about 300 MB; give it 1 GB |
| 1,000 | about 310 MB; give it 1 GB | about 3 GB; give it 8 GB |

The table assumes the default `pow.expires` of `20m` and a `POST /v2/verify/signature` call per submission. The suggested sizes are about twice the estimate, rounded up, which leaves room for allocator fragmentation, replication buffers, and the copy-on-write memory of RDB snapshots and AOF rewrites. Don't go below 256 MB.

These settings raise memory use:

- **A long `pow.expires`.** Claims live as long as the challenge: at 100 verifications per second, a `24h` expiry keeps about 2.2 GB of claims.
- **HIS under a sustained attack.** The more bot-like a payload scores, the longer it is kept, up to `his.hashTtl`. Set a lower `his.hashTtl` in the security group's rules to cap it.
- **Sliding-window limits.** A limit with `(sliding)` stores every request in the window: about 30 B per request, rising to about 100 B per request above 128 requests in one window. A `1000/1h(sliding)` limit can take about 100 KB per client. Prefer fixed-window limits for large counts.

Set `maxmemory` to the size you provision and `maxmemory-policy` to `noeviction`. Evicting a replay claim would let its solution be accepted again, and evicting a counter resets a rate limit. With `noeviction`, a full store rejects writes instead: the widget endpoints keep working with per-replica fallbacks (see [Clustering](/docs/sentinel/v2/operations/clustering/)), but sign-in, OTP, and passkeys fail until memory frees up. Alert on `used_memory` well before the limit.

Persistence is optional. Without it, a restart of Redis forgets replay claims, rate-limit counters, and penalties, so a solution verified before the restart can be replayed until its challenge expires. Enable AOF (`appendonly yes`) if that window matters to you.

## Container image

The image is published to the GitHub Container Registry as `ghcr.io/altcha-org/sentinel`. It is a multi-arch image for `linux/amd64` and `linux/arm64`; your runtime pulls the right one automatically.

| Tag | Contents |
| --- | --- |
| `2.0.0-beta.x` (e.g. `2.0.0-beta.1`) | A v2 beta release, with every database backend except Oracle. Pin an exact version. |
| `2.0.0-beta.x-oracle` (e.g. `2.0.0-beta.1-oracle`) | The same release plus the Oracle Instant Client, which the Oracle backend needs. |

Both images contain the same binary. Use the `-oracle` image only with an Oracle database; it is larger.

> **Warning:**
>
> During the beta, `latest` still points to Sentinel v1. Always use an explicit `2.0.0-beta.x` tag for v2.

The container runs as the non-root user `65532:65532` with working directory `/home/nonroot`. Relative paths in the configuration resolve against the working directory, so these are the paths inside the image:

| Path | Purpose |
| --- | --- |
| `/usr/local/bin/altcha-sentinel` | The binary, and the image's entrypoint. Arguments you pass to the container go to it (e.g. `doctor`). |
| `/home/nonroot/sentinel.toml` | The configuration file read by default. Mount yours here, read-only, or pass `--config <path>`. |
| `/home/nonroot/data` | `data_dir`: the embedded database, generated secrets, and downloaded remote files. Owned by `65532`; mount a persistent volume here. |
| `/home/nonroot/assets/tts` | Voices for code-challenge audio (`[code_challenge] tts_dir`), shipped in the image. |
| `/opt/oracle/instantclient` | Oracle Instant Client, in the `-oracle` image only. |

The admin UI is compiled into the binary, so the image has no static files to serve and `[server.admin_ui] dir` stays unset. The image contains no shell tools such as `curl` or `wget`; use the built-in `altcha-sentinel healthcheck` for health checks. Its `HEALTHCHECK` runs it every 10 s against `./sentinel.toml`.

## Ports

Each listener has its own port. Only the main API listener is on by default.

| Listener | Config section | Default port | Default host | Enabled by default |
| --- | --- | --- | --- | --- |
| Main API (every `/v2` route) | `[server]` | `3000` | `0.0.0.0` | Yes |
| Prometheus metrics | `[prometheus]` | `3001` | `127.0.0.1` | No |
| Admin UI (web app plus `/v2`) | `[server.admin_ui]` | `3002` | `127.0.0.1` | No |
| Public widget API | `[server.public_api]` | `3003` | `0.0.0.0` | No |

Listeners that default to `127.0.0.1` are unreachable from outside a container. Set their `host` to `"0.0.0.0"` to publish them, and restrict access with a firewall, `allowed_ips`, or your proxy. See [Listeners & reverse proxy](/docs/sentinel/v2/configure/listeners/) for when to split traffic across listeners.

## Production essentials

Every production install needs the four items below. Set them in `sentinel.toml`; the platform guides show where the file and secrets come from on each platform.

### License

Without an active license, Sentinel starts and you can sign in, but `GET /v2/challenge`, `POST /v2/verify`, and the feature endpoints answer `403 LICENSE_NOT_ACTIVE`. Without a usable license, Sentinel also runs on the baseline: embedded SQLite only, 3 instances, 1 account, 1 user, 1 API key, and 1 security group.

Install the license in the configuration file, either as an activation key or as a signed license file. The license can't be set in the admin UI.

```toml
[license]
key = "${file:/run/secrets/sentinel_license_key}"   # SENT-… activation key; or file = "<path>" for an offline license file
```

To get a trial license, register at [cloud.altcha.org](https://cloud.altcha.org) and create a Sentinel V2 trial license in the **Licenses** section. See [Licensing](/docs/sentinel/v2/configure/licensing/) for activation, offline files, and instance slots, and [Plans & Licensing](/docs/sentinel/v2/plans/) for what each plan includes.

### Secrets

Sentinel signs admin sessions and the admin sign-in challenge, and encrypts stored API key and TOTP secrets, with three keys in `[secrets]`. With embedded SQLite and no keys set, it generates them into `<data_dir>/secrets.json`. With any other database, or with more than one replica, set all three yourself; Sentinel refuses to start when one is missing. Every replica must use the same values.

```toml
[secrets]
jwt_secret         = "${file:/run/secrets/jwt_secret}"          # at least 24 characters
altcha_hmac_secret = "${file:/run/secrets/altcha_hmac_secret}"  # at least 24 characters
encryption_key     = "${file:/run/secrets/encryption_key}"      # 64 hex characters
```

Generate the values with, for example, `openssl rand -hex 32`. Keep secrets out of the TOML file: reference a mounted file with `${file:…}` or an environment variable with `${VAR}`.

> **Danger:**
>
> Back up the secrets with the database. Changing `encryption_key` makes the secrets stored in the database (API key secrets, TOTP secrets) unreadable, and changing `jwt_secret` signs out every user.

See [Server secrets](/docs/sentinel/v2/configure/secrets/) and [`[secrets]`](/docs/sentinel/v2/reference/configuration/#secrets).

### Database

The database is the source of truth for accounts, users, API keys, security groups, and logs. By default Sentinel uses embedded SQLite at `<data_dir>/sentinel.db`, which suits a single instance with a persistent volume. If that volume is network storage, such as AWS EFS, NFS, or Azure Files, set `[database] sqlite_journal_mode = "delete"`; see [SQLite on network storage](/docs/sentinel/v2/configure/databases/#sqlite-on-network-storage).

| Backend | Supported versions | `[database] url` scheme | Image |
| --- | --- | --- | --- |
| SQLite (embedded, default) | Bundled (SQLite 3.54.1) | `sqlite:` | All |
| PostgreSQL | 16 or later | `postgres://` | All |
| MySQL | 8.0.13 or later | `mysql://` | All |
| MariaDB | 11.4 LTS or later | `mariadb://` | All |
| Microsoft SQL Server | 2022 or later | `mssql://` | All |
| Oracle | 21c or later | `oracle://` | `-oracle` image |
| ExotDB server | — | `http(s)://` | All |

SQLite is compiled into Sentinel, so the host's SQLite version doesn't matter. MariaDB is the only backend whose version is checked: Sentinel refuses to start on MariaDB older than 11.4, on a MariaDB server behind a `mysql://` URL, and on a MySQL server behind a `mariadb://` URL. Older versions of the other backends (PostgreSQL before 16, SQL Server 2016–2019, Oracle 19c) aren't tested and aren't supported.

Backends other than SQLite need the matching `exotdb.backend.<kind>` license feature. Use an external database when you run more than one replica. Each replica opens up to `[database] pool_max` connections (default `20`), so keep `pool_max` × replicas below your database's connection limit; see [`[database]`](/docs/sentinel/v2/reference/configuration/#database) for the pool settings. Sentinel creates and upgrades its tables at startup, so its database account needs the right to create tables, unless a database administrator applies the migrations with `[database] auto_migrate = false`; see [Schema migrations](/docs/sentinel/v2/operations/schema-migrations/). TLS options for the database go in the URL; see [Database TLS](/docs/sentinel/v2/reference/configuration/#database-tls). If your database, Redis, or other services use certificates from a private CA, add it to the top-level [`tls_extra_ca_certs`](/docs/sentinel/v2/reference/configuration/#top-level).

```toml
[database]
url = "postgres://sentinel:${DB_PASSWORD}@db.internal:5432/sentinel"
```

See [Databases](/docs/sentinel/v2/configure/databases/) for connection details per backend.

### Redis

Sentinel keeps rate-limit counters, penalties, replay protection, and replica messaging in a KV store. With `[redis] nodes` empty, it uses a built-in store on its own database, which works for a single instance only. As an external store, use Redis 7.0 or later, or Valkey; see [Redis or Valkey](#redis-or-valkey) for what it stores and how much memory to give it.

Redis is required when:

- you run more than one replica, or
- `[database] url` points to an ExotDB server.

```toml
[redis]
nodes = ["redis://:${REDIS_PASSWORD}@redis.internal:6379"]
```

Every replica must use the same `[redis] key_prefix`. For TLS, use `rediss://` URLs, with `[redis] tls_ca` for a private CA and `tls_cert`/`tls_key` for a client certificate. With several `nodes`, Sentinel treats them as Redis Cluster seed nodes. For a Redis replicated with Redis Sentinel, leave `nodes` empty and list the Sentinels in [`[redis.sentinel]`](/docs/sentinel/v2/reference/configuration/#redissentinel); Sentinel follows failovers to the new master:

```toml
[redis.sentinel]
nodes    = ["redis://:${REDIS_SENTINEL_PASSWORD}@s1:26379", "redis://:${REDIS_SENTINEL_PASSWORD}@s2:26379"]
master   = "mymaster"
password = "${REDIS_PASSWORD}"
```

See [Clustering](/docs/sentinel/v2/operations/clustering/) and [`[redis]`](/docs/sentinel/v2/reference/configuration/#redis).

### Before you go live

- Serve every exposed listener over HTTPS. Either set `tls` on the listener (see [Listener TLS](/docs/sentinel/v2/reference/configuration/#listener-tls)), or put a TLS-terminating reverse proxy in front and set `trusted_proxies` so client IPs are correct. Outside `localhost`, the admin UI's session cookie requires HTTPS. See [Listeners & reverse proxy](/docs/sentinel/v2/configure/listeners/).
- Behind a load balancer or proxy, keep `[server] idle_timeout` (default `620s`) above its keep-alive timeout, or it may return 502 errors on reused connections. See [Connection timeouts](/docs/sentinel/v2/reference/configuration/#connection-timeouts).
- Give each replica a unique `HOSTNAME`; Sentinel uses it to claim license instance slots.
- Run `altcha-sentinel doctor` in the container to validate the configuration and check connectivity. See the [CLI reference](/docs/sentinel/v2/reference/cli/).
- Work through the [Production checklist](/docs/sentinel/v2/security/production-checklist/).

## In this section

- [Install with Docker](/docs/sentinel/v2/install/docker/): Run Sentinel v2 as a single Docker container with a mounted configuration file, a data volume, and secrets.
- [Install with Docker Compose](/docs/sentinel/v2/install/docker-compose/): Run Sentinel v2 with Docker Compose: one instance on embedded SQLite, or two replicas with PostgreSQL and Valkey.
- [Install on Kubernetes](/docs/sentinel/v2/install/kubernetes/): Deploy Sentinel v2 on Kubernetes with plain manifests: a ConfigMap, a Secret, a StatefulSet with health probes, and PostgreSQL and Redis for several replicas.
- [Install on AWS ECS](/docs/sentinel/v2/install/aws/): A guide for deploying Sentinel v2 on Amazon ECS will follow; until then, run Sentinel on Docker, Docker Compose, or Kubernetes.
- [Install on Azure App Service](/docs/sentinel/v2/install/azure/): Deploy Sentinel v2 on Azure App Service with the Azure CLI: a Linux container, the configuration file on Azure Files, and Azure Database for PostgreSQL.
