Skip to main content
ALTCHA®

Clustering

Running more than one Sentinel replica means every instance needs to see the same state. Three components can be shared:

  1. Main database — required. PostgreSQL, MySQL, Oracle, etc. Holds API keys, Security Groups, account settings, and other persistent state. The embedded default database does not support this — see Databases.
  2. KV store (Redis/Valkey) — required. Shares rate-limiter state and cluster coordination across instances. See Databases.
  3. ClickHouse — optional, for shared request-log analytics. See ClickHouse.

Minimum production configuration

Set these four variables identically on every node:

SECRET_SEED=<a long random string, identical on every node>
LICENSE_KEY=<license key>
POSTGRES_URL=postgresql://user:password@your-db-host:5432/altcha_sentinel
REDIS_URL=redis://default@your-redis-host:6379
  • SECRET_SEED — deterministically derives JWT_SECRET, ALTCHA_HMAC_SECRET, and the other required secrets, so sessions and signatures stay valid across every node. See ENV Variables.
  • LICENSE_KEY — a Professional or Enterprise license is required for more than one replica (Trial licenses support up to 3, for testing). See License.
  • Database URL — swap POSTGRES_URL for the variable matching your engine: MYSQL_URL, MARIADB_URL, MSSQL_URL, ORACLE_URL, LIBSQL_URL, or TURBOLITE_URL. See Databases.
  • REDIS_URL — or REDIS_CLUSTER_URL for Redis Cluster, or EXOTDB_REDIS_STORAGE=turbolite with TURBOLITE_REDIS_URL to avoid running a separate Redis instance. See Databases.

See Setting these on any deployment target for how to pass env vars on Docker, Kubernetes, ECS, Azure, or Bunny.

Core principles

All nodes connect directly to the supported databases — there's no proxy or coordinator node in front of them, so deploying a highly-available setup for the databases themselves is recommended (a single database instance becomes the cluster's single point of failure otherwise). Sentinel instances themselves don't require persistent storage to run, though persistence still helps for caching external data sources locally. Kubernetes is the recommended environment for multi-instance deployments — see Install on Kubernetes.

Node identity

Each instance needs a unique NODE_ID. It's randomly generated on startup and persisted to the data volume if you don't set one — or you can set your own, any short string such as node_1. See ENV Variables.

Shared secrets

Rather than configuring each instance's secrets (JWT_SECRET, ALTCHA_HMAC_SECRET, etc.) individually, set the same SECRET_SEED on every instance to derive them all deterministically — this is what keeps sessions and signatures valid across the whole cluster. See ENV Variables.

Database unavailability

Losing a shared database doesn't necessarily take the whole cluster down — but what keeps working depends on which one it is.

Main database

Data needed for basic operation — API keys, Security Group configuration — is loaded into memory on startup and kept in sync as changes happen, so core verification keeps working through a brief outage. Features that need an active database connection for each request — Forms, Redirects, Training Data — are unavailable until the connection is restored.

KV store (Redis)

If Redis becomes unreachable, Sentinel automatically falls back to in-memory rate limiting on each node and retries the connection periodically — degraded, but still functioning per-instance. Features that depend on Redis pub/sub specifically — cluster node discovery, in-memory data sync between nodes — are unavailable until Redis is reachable again.

ClickHouse

If ClickHouse is unreachable, or a write fails, that batch of request logs is simply lost. This doesn't affect core functionality — verification and enforcement are unaffected — but your historical analytics will have a gap for the affected period.

Multi-regional deployments

For a geographically distributed setup, run separate Sentinel instances or clusters per region, each with its own Redis instance, all sharing the same main database across every region. This gives you:

  • Low latency, since each region serves requests locally.
  • Consistent configuration everywhere, since Security Groups/API Keys/accounts live in the one shared database.

Redis is not replicated between regions, so cluster-communication features that rely on it (node discovery, in-memory sync) stay scoped to each region's own Redis — this doesn't affect normal API operations or verification, since those don't depend on cross-region Redis state.

Kubernetes

The Helm chart is the most direct path to running a cluster — set persistence.enabled/persistence.size alongside your database and Redis configuration, and let Kubernetes handle autoscaling and pod lifecycle.

Dashboard

The admin dashboard lists every instance in the cluster with metrics from the last 60 minutes:

  • CPU — average CPU usage, percent.
  • Mem — average memory usage (RSS).
  • Req — requests per minute.
  • 4xx / 5xx — HTTP error responses per minute.

The cluster dashboard is visible only to users with Root privilege — see Users & Accounts. For more comprehensive monitoring, see Monitoring & Logging.

Limitations

  • Environment variables can't be set from within the admin app — the license key specifically must be set via the LICENSE_KEY environment variable, not entered through the UI, in a clustered deployment.
  • Built-in database snapshots aren't available when using PostgreSQL as the main database — use PostgreSQL's own backup tooling instead. See Backups & Recovery.

Licensing

Start typing to search...

↑ ↓ Navigate ↵ Select