Skip to main content
ALTCHA®

Production checklist

Work through this checklist before Sentinel serves production traffic. Each item says what to check, why it matters, and where the details are.

License

  • An active license is set in [license]. Without one, GET /v2/challenge, POST /v2/verify, and the detection endpoints answer 403 LICENSE_NOT_ACTIVE. See Licensing.
  • Staging uses a non-production license. Its responses carry X-Sentinel-License: non-production, so test traffic is easy to tell apart. See Non-production licenses.
  • License expiry is alerted on. Alert on altcha_sentinel_license_expiry_timestamp_seconds - time() and watch the license_expired and license_refresh_failing alerts. See Alerts and metrics.

Configuration & secrets

  • jwt_secret, altcha_hmac_secret, and encryption_key are set explicitly with ${file:…} or ${VAR}. Sentinel generates them only on embedded SQLite and refuses to start without them on any other database. See Server secrets.
  • Every replica uses the same secret values. A mismatch causes 401 sessions and undecryptable API keys behind a load balancer. See Share them across replicas.
  • Secrets are backed up with the database. A database restored without its encryption_key has unreadable API key and TOTP secrets. See Generated secrets on embedded SQLite.
  • altcha-sentinel doctor passes on every replica. It validates the configuration and checks connectivity and security warnings. See doctor.

Exposure

  • The admin UI isn't public. Keep [server.admin_ui] behind a VPN or restrict it with allowed_ips. See Choose what to expose.
  • The widget is served from the public listener. [server.public_api] exposes only the widget endpoints, so the main API can stay on your private network. See Public widget API.
  • allowed_hosts is set on every exposed listener. Requests for other hosts get 421, which blocks DNS rebinding. See Allowed hosts.
  • /.health and the Prometheus listener are private. Keep health_allowed_ips to private networks and probers, and protect metrics with allowed_ips or bearer_token. See Health endpoint and [prometheus].
  • Every exposed listener uses HTTPS. Set listener tls or terminate TLS at a proxy; the admin session cookie needs HTTPS outside localhost. See HTTPS.

Reverse proxy

  • trusted_proxies lists your proxies. Otherwise client_ip_header and forwarded hosts are accepted from any peer, and clients can choose their own IP. See Client IP.
  • client_ip_header matches your CDN, if you use one. For example CF-Connecting-IP; rate limits, penalties, and IP rules depend on the right client IP. See Client IP.
  • base_url is the public URL of each widget listener. It prefixes the URLs handed to the widget and is the OAuth and passkey URL. See Public URL.
  • [server] idle_timeout is above the proxy's keep-alive timeout. Otherwise reused connections can return 502. See Connection timeouts.

Credentials

  • Widget keys are public. Only public keys work on the widget endpoints, and their id is visible in the page. See Credential matrix.
  • Backend keys are restricted. They call the detection endpoints with Basic id:secret and can't manage Sentinel. See Restricted vs full.
  • full keys are used only by automation that manages Sentinel. Their security group's role sets what they can change. See Restricted vs full.
  • Key secrets are rotated by replacing the key, and the old key gets an expiry. Secrets can't be regenerated in place; an expiresAt on the old key stops it even if nobody deletes it. See Rotate a secret.
  • Your backend verifies every submission. Check the widget's payload with POST /v2/verify/signature or a server library before trusting the form. See Verify with Sentinel and The verificationData fields.

Rules

  • Widget security groups start from the Recommended preset. See Recommended.
  • New rules and presets run in monitor mode first. Monitored rules are evaluated and logged but have no effect. See Monitor mode.
  • Rules are checked with a GET /v2/inspect rule trace, then the trace is turned off. [inspect] security_rules shows callers which conditions they trip, so use it for debugging only. See Inspect with a rule trace.

Availability

  • Multiple replicas share Redis or Valkey. The built-in KV store works for a single instance only. See Redis and Clustering.
  • Redis runs with maxmemory-policy noeviction. Evicting a replay claim lets a solution be accepted again. See Redis or Valkey.
  • Each replica has a unique HOSTNAME. Sentinel uses it to claim license instance slots. See Before you go live.
  • Database TLS verifies the server. PostgreSQL, MySQL, and MariaDB don't verify certificates by default; set sslmode=verify-full or ssl-mode=VERIFY_IDENTITY. See Database TLS.
  • pool_max × replicas stays below the database's connection limit. Leave room for rolling deploys. See Connection pool.

Data & backups

  • Snapshots are scheduled to storage. Set [snapshots] identity, schedule, and a [storage] provider, and add an offline age key to recipients. See Snapshots and [snapshots].
  • A restore has been tested. Restore a snapshot into a staging deployment before you need it. See Snapshots.

Monitoring

  • Prometheus scrapes every replica. See Monitoring.
  • Alerts have a delivery channel. Configure webhooks, email, or push so alerts reach someone. See Alerts and [alerts].
  • High-volume request logs go to ClickHouse. With [clickhouse] url set, request logs leave the main database. See ClickHouse.

Admin access

  • The bootstrap root password has been changed. A generated password stays in your logs. See The bootstrap root password.
  • Root and admin users use two-factor authentication or passkeys. doctor warns about root users without it. See Sign-in.
  • SSO is configured if you use one, and [auth] password_login = false if you require it. See Sign-in and [auth].

Privacy

  • [privacy] anonymize_ip matches your privacy policy. It truncates client IPs in request logs, audit logs, alerts, and log lines. See Privacy.
  • Each API key's requestLogging is no higher than you need. none, verification, or all decides which requests are stored. See Request logging and Request logs.

Start typing to search...

↑ ↓ Navigate ↵ Select