Skip to main content
ALTCHA®

Install Sentinel

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.

Requirements at a glance

RequirementSingle instanceSeveral replicas
Container runtimeDocker or any OCI runtimeKubernetes, ECS, App Service, or Compose
LicenseRequired to serve challenges, verification, and feature endpointsRequired; its instances limit caps the replica count
ConfigurationOne sentinel.tomlThe same sentinel.toml on every replica
DatabaseEmbedded SQLite in the data volume (default)A shared external database
RedisNot neededRequired
SecretsGenerated into the data volume, or set explicitlySet explicitly, identical on every replica
Persistent volumeRequired for /home/nonroot/dataRecommended (remote files and caches)
HTTPStls on the exposed listeners, or a TLS-terminating proxy in frontA 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.

DeploymentCPUMemory
Evaluation, low traffic1 vCPU512 MB
Production, per replica2 vCPU or more, compute-optimized1 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:

EndpointRequests per secondp99 latency
GET /v2/challenge (default PBKDF2 cost)about 1,50011 ms
POST /v2/verifyabout 4,4005.1 ms
POST /v2/verify with fields classifiedabout 1,00026 ms
POST /v2/verify/signatureabout 6,9003.3 ms
POST /v2/classifierabout 90026 ms

Measure your own traffic mix before you size a cluster. Each replica reports its CPU and memory use; see Monitoring and 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:

DataWritten whenKept forSpace per row, SQLite / PostgreSQL
Request logsEvery request of an API key whose requestLogging is verification or all (default none); not with ClickHouse[request_logs] retention, default 72habout 370 B / 400 B
Hourly request statisticsOne row per API key and UTC hour with logged requestsIndefinitelyabout 1 KB, more with many countries, referrers, and rules
Built-in KV storeWithout [redis] nodes, the same entries as in the Redis tableAs in Redisabout 180 B / 300 B
Audit logs and alertsSign-ins, management changes, raised alerts[audit_logs] retention and [alerts] retention, default 90dsmall

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 secondRetention 72h (default)Retention 7d
1about 100 MBabout 250 MB
10about 1 GBabout 2.4 GB
100about 10 GBabout 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, 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 to move that load off the database; see 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.

DataWritten byKept forMemory per entry
Replay protection: one claim per verified challenge, and one per payload checked by POST /v2/verify/signaturePOST /v2/verify, POST /v2/verify/signatureUntil the challenge expires: pow.expires, default 20m, at most 24habout 130 B
Rate-limit countersEvery /v2 request ([rate_limit] global), security-group rateLimit.limits, classifier and audio limitsOne window of the limitabout 150 B per client and limit
PenaltiesFailed verifications, rate-limit pressure, penalty.add rules, header entropy[penalty] ttl after the last increase, default 30mabout 150 B per account and client IP
Header entropyGET /v2/challenge and GET /v2/inspect, when headerEntropy.limit is setThe headerEntropy.limit windowup to about 2 KB per client IP
HIS replay detectionPOST /v2/challenge, when his.mode isn't off10 minutes for human-like interaction, up to his.hashTtl (default 12h) for bot-like interactionabout 3 KB per challenge
Campaign detectionEach classified text of at least [similarity.campaign] min_chars (default 30) characters[similarity.campaign] window, default 1habout 1 KB per text
Sign-in and alert stateLogins, OTP, passkeys, step-up, alert evaluation, threat signalsMinutes to hoursnegligible

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 secondWithout HISWith HIS (about 15 minutes kept)
10about 3 MB; give it 256 MBabout 30 MB; give it 256 MB
100about 30 MB; give it 256 MBabout 300 MB; give it 1 GB
1,000about 310 MB; give it 1 GBabout 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), 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.

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

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:

PathPurpose
/usr/local/bin/altcha-sentinelThe binary, and the image's entrypoint. Arguments you pass to the container go to it (e.g. doctor).
/home/nonroot/sentinel.tomlThe configuration file read by default. Mount yours here, read-only, or pass --config <path>.
/home/nonroot/datadata_dir: the embedded database, generated secrets, and downloaded remote files. Owned by 65532; mount a persistent volume here.
/home/nonroot/assets/ttsVoices for code-challenge audio ([code_challenge] tts_dir), shipped in the image.
/opt/oracle/instantclientOracle 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.

ListenerConfig sectionDefault portDefault hostEnabled by default
Main API (every /v2 route)[server]30000.0.0.0Yes
Prometheus metrics[prometheus]3001127.0.0.1No
Admin UI (web app plus /v2)[server.admin_ui]3002127.0.0.1No
Public widget API[server.public_api]30030.0.0.0No

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

[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 and create a Sentinel V2 trial license in the Licenses section. See Licensing for activation, offline files, and instance slots, and Plans & Licensing 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.

[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}.

See Server secrets and [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.

BackendSupported versions[database] url schemeImage
SQLite (embedded, default)Bundled (SQLite 3.54.1)sqlite:All
PostgreSQL16 or laterpostgres://All
MySQL8.0.13 or latermysql://All
MariaDB11.4 LTS or latermariadb://All
Microsoft SQL Server2022 or latermssql://All
Oracle21c or lateroracle://-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] 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. TLS options for the database go in the URL; see 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.

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

See 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 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.
[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]; Sentinel follows failovers to the new master:

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

See Clustering and [redis].

Before you go live

  • Serve every exposed listener over HTTPS. Either set tls on the listener (see 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.
  • 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.
  • 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.
  • Work through the Production checklist.

In this section

  • Install with Docker: Run Sentinel v2 as a single Docker container with a mounted configuration file, a data volume, and secrets.
  • Install with Docker Compose: Run Sentinel v2 with Docker Compose: one instance on embedded SQLite, or two replicas with PostgreSQL and Valkey.
  • Install on 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: 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: 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.

Start typing to search...

↑ ↓ Navigate ↵ Select