# Self-hosted mCaptcha Proof-of-work CAPTCHA for the whole boilerplate (login, public forms, booking). One instance serves **all** services via per-surface sitekeys. EU-self-hosted, no third-party processor — replaces Cloudflare Turnstile / reCAPTCHA / hCaptcha. > Architecture decision: HiveGrid `docs/ARCHITECTURE-DECISIONS.md` AD-7. > Stack: `mcaptcha/mcaptcha` (server, :7000) + `postgres:16-alpine` + `mcaptcha/cache` > (Redis with mCaptcha's PoW module — **not** vanilla redis). ## Status: DEPLOYED ✅ (2026-06-05) Live at **https://captcha.saas-ctrl.com** on **node1** (`176.9.111.179`), running as a plain docker-compose stack at `/opt/mcaptcha` behind host-Caddy (same pattern as `/opt/sentry`). Valid Let's Encrypt cert. Registration is closed. - Ops account + account secret + the 3 sitekeys: `~/.cli-tokens/mcaptcha` (and `/opt/mcaptcha/CREDENTIALS` on node1, chmod 600). - Sitekeys (public): `login`, `forms`, `booking`. ## Deploy / re-deploy on node1 (the actual setup) node1 is **not** Coolify-managed; services are direct docker-compose stacks behind host-level Caddy (`/etc/caddy/Caddyfile`, systemd) which terminates TLS. 1. **DNS:** A record `captcha.saas-ctrl.com` → `176.9.111.179` (Cloudflare, **DNS-only** so Caddy can issue the LE cert). 2. **Stack:** copy `docker-compose.yml` to `/opt/mcaptcha/`, `cp .env.example .env`, set the three secrets (`openssl rand -hex 32` for COOKIE_SECRET, SALT, and the PG password — also paste the PG password into `DATABASE_URL`). `chmod 600 .env`. Then `docker compose up -d`. 3. **Caddy:** append `Caddyfile.snippet` to `/etc/caddy/Caddyfile`, `caddy validate`, `systemctl reload caddy`. 4. **Account + sitekeys** (one-time): with `MCAPTCHA_allow_registration=true`, register the ops account via `POST /api/v1/signup` (username must be alphanumeric — PRECIS UsernameCaseMapped), sign in (`/api/v1/signin`, cookie auth over **https** — the session cookie is Secure + host-bound, so it won't work over http://localhost), read the account secret (`GET /api/v1/account/secret/get`), and create sitekeys (`POST /api/v1/mcaptcha/create` with `{levels, duration, description, publish_benchmarks:false}`). Then set `MCAPTCHA_allow_registration=false` and `docker compose up -d`. ## How the app consumes it Set in the **app's** env (not this `.env`): ``` MCAPTCHA_INSTANCE_URL=https://captcha.saas-ctrl.com MCAPTCHA_ACCOUNT_SECRET= MCAPTCHA_SITEKEY_LOGIN= MCAPTCHA_SITEKEY_FORMS= MCAPTCHA_SITEKEY_BOOKING= CAPTCHA_FAIL_OPEN=true ``` Verify flow: client solves the PoW widget → token → app server calls `POST {MCAPTCHA_INSTANCE_URL}/api/v1/pow/siteverify` with `{ secret, token, key }` (handled by `@toolctrl/captcha`). ## Fail policy If the instance is unreachable, the app **fails open** (lets the submission through) and logs a warning — login brute-force is still covered by `auth-rate-limit` + `shared-store`. Flip to fail-closed via `CAPTCHA_FAIL_OPEN=false`. ## Ops notes - Only `mcaptcha-pg-data` holds state (account + sitekeys + stats); the cache is ephemeral. - mCaptcha terminates no TLS; Caddy must sit in front. - Images are `:latest` — pin to a released tag before relying on it long-term.