Files
HiveGrid-Wireframes/03 Quellen und Referenzen/hivegrid-cloud/infra/mcaptcha/README.md
T
2026-07-08 16:15:37 +02:00

70 lines
3.2 KiB
Markdown

# 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=<from ~/.cli-tokens/mcaptcha>
MCAPTCHA_SITEKEY_LOGIN=<sitekey_login>
MCAPTCHA_SITEKEY_FORMS=<sitekey_forms>
MCAPTCHA_SITEKEY_BOOKING=<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 `@hivegrid/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.