Captcha tuning
When to enable, when to throttle, how to verify
Olympus uses Cloudflare Turnstile for captcha on registration, login, and recovery flows. Tuning is mostly "is it on", Turnstile's own adaptive heuristics handle most of the decisioning.
Enable / disable
Set in container env:
# Enable: configure these
TURNSTILE_SITE_KEY=0x4AAAAAAA…
TURNSTILE_SECRET_KEY=0x4AAAAAAA…
# Disable: unset both, or:
TURNSTILE_DISABLED=trueIn Olympus's default config, Turnstile is disabled in dev, enabled in prod if keys are configured.
Choose which flows
By default Turnstile applies to:
- Registration
- Login (after first failed attempt, see below)
- Recovery (email submission)
Configurable per-flow via env:
TURNSTILE_ON_REGISTRATION=true
TURNSTILE_ON_LOGIN=true
TURNSTILE_ON_LOGIN_AFTER_FAIL=true # only show after 1+ failed attempts
TURNSTILE_ON_RECOVERY=trueAdaptive challenge
Turnstile auto-tunes its visibility:
- Managed (default), Turnstile decides if a visible challenge is needed; no UI for trusted users.
- Non-interactive, runs invisibly; no user action.
- Invisible, never visible.
Configure in Cloudflare Turnstile dashboard, per widget.
Switching providers
If Turnstile is down or you want hCaptcha / Google reCAPTCHA instead, you'll need a Hera fork that replaces the widget. See hera/src/components/captcha-widget.tsx. Olympus's first-party support is Turnstile.
Monitoring
Turnstile dashboard shows challenge counts, success rate, suspected-bot rate. Watch:
- Success rate < 95%, many users failing → consider lowering challenge difficulty or whitelisting traffic patterns.
- Suspected-bot rate spike, you're being attacked. Captcha is doing its job.
Disable temporarily during incident
If Turnstile itself has an outage (check status.cloudflare.com):
# Hot-disable without redeploy
podman exec olympus-ciam-hera env TURNSTILE_DISABLED=true # not portable; better:
# Set in compose env via .env.prod, redeployRedeploying restores normal config when Turnstile recovers.