Track HiveGrid Cloud planning reference

This commit is contained in:
david committed 2026-06-26 20:48:01 +02:00
1 parent b3d5ea6764
commit e341c5938a
5784 files changed
+1104929 -3

No files matched your search

@@ -0,0 +1,41 @@
# mCaptcha self-host env — copy to `.env` on node1 (/opt/mcaptcha/.env), chmod 600.
# Secrets (COOKIE_SECRET, SALT, PG password) MUST be random, MIN 32 chars: openssl rand -hex 32
# Env var names are verbatim from mCaptcha (note the single/double underscores — do NOT normalise).
# --- general -----------------------------------------------------------------
MCAPTCHA_debug=false
MCAPTCHA_commercial=false
MCAPTCHA_source_code=https://github.com/mCaptcha/mCaptcha
# Keep registration OFF in production (we provision the ops account + sitekeys once).
MCAPTCHA_allow_registration=false
MCAPTCHA_allow_demo=false
# --- database (password must equal MCAPTCHA_PG_PASSWORD) ----------------------
DATABASE_URL=postgres://postgres:CHANGE_ME_PG_PASSWORD@mcaptcha_postgres:5432/postgres
MCAPTCHA_database_POOL=4
MCAPTCHA_PG_PASSWORD=CHANGE_ME_PG_PASSWORD
# --- cache (mcaptcha/cache service) ------------------------------------------
MCAPTCHA_redis_URL=redis://mcaptcha_redis
MCAPTCHA_redis_POOL=4
# --- server (TLS terminated by host Caddy in front) --------------------------
PORT=7000
MCAPTCHA__server_IP=0.0.0.0
MCAPTCHA_server_DOMAIN=captcha.saas-ctrl.com
MCAPTCHA__server_PROXY_HAS_TLS=true
MCAPTCHA__server_COOKIE_SECRET=CHANGE_ME_RANDOM_MIN_32_CHARS
# --- captcha PoW -------------------------------------------------------------
MCAPTCHA_captcha_SALT=CHANGE_ME_RANDOM_MIN_32_CHARS
MCAPTCHA_captcha_GC=30
MCAPTCHA_captcha_RUNNERS=4
MCAPTCHA_captcha_QUEUE_LENGTH=2000
MCAPTCHA_captcha_ENABLE_STATS=true
MCAPTCHA_captcha_DEFAULT_DIFFICULTY_STRATEGY_avg_traffic_difficulty=50000
MCAPTCHA_captcha_DEFAULT_DIFFICULTY_STRATEGY_peak_sustainable_traffic_difficulty=3000000
MCAPTCHA_captcha_DEFAULT_DIFFICULTY_STRATEGY_broke_my_site_traffic_difficulty=5000000
MCAPTCHA_captcha_DEFAULT_DIFFICULTY_STRATEGY_duration=30
MCAPTCHA_captcha_DEFAULT_DIFFICULTY_STRATEGY_avg_traffic_time=1
MCAPTCHA_captcha_DEFAULT_DIFFICULTY_STRATEGY_peak_sustainable_traffic_time=3
MCAPTCHA_captcha_DEFAULT_DIFFICULTY_STRATEGY_broke_my_site_traffic_time=5
@@ -0,0 +1,7 @@
# Append to /etc/caddy/Caddyfile on node1, then `systemctl reload caddy`.
# Caddy auto-issues + renews the Let's Encrypt cert for the host.
# (DNS A record captcha.saas-ctrl.com -> 176.9.111.179 must exist, DNS-only.)
captcha.saas-ctrl.com {
reverse_proxy localhost:7000
}
+69
View File
@@ -0,0 +1,69 @@
# 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 `@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.
@@ -0,0 +1,58 @@
# Self-hosted mCaptcha (proof-of-work CAPTCHA) — node1 deployment.
#
# node1 runs services as plain docker-compose stacks behind host-level Caddy
# (NOT Coolify, NOT Traefik) — same pattern as /opt/sentry. Caddy terminates
# TLS and reverse-proxies captcha.saas-ctrl.com -> 127.0.0.1:7000.
#
# Deployed at /opt/mcaptcha on node1 (176.9.111.179). See README.md.
#
# IMPORTANT:
# - The cache is `mcaptcha/cache` (Redis + mCaptcha's PoW module), NOT vanilla redis.
# - mCaptcha terminates NO TLS (PROXY_HAS_TLS=true in .env; Caddy does TLS).
# - Port is published on 127.0.0.1 only — Caddy reaches it locally, never public.
# - Password inside DATABASE_URL (.env) MUST equal MCAPTCHA_PG_PASSWORD.
name: mcaptcha
networks:
mcaptcha-net:
name: mcaptcha-net
volumes:
mcaptcha-pg-data:
name: mcaptcha-pg-data
services:
mcaptcha:
image: mcaptcha/mcaptcha:latest
restart: unless-stopped
networks: [mcaptcha-net]
env_file: [.env]
ports:
- "127.0.0.1:7000:7000"
depends_on:
mcaptcha_postgres:
condition: service_healthy
mcaptcha_redis:
condition: service_started
mcaptcha_postgres:
image: postgres:16-alpine
restart: unless-stopped
networks: [mcaptcha-net]
environment:
POSTGRES_USER: postgres
POSTGRES_DB: postgres
POSTGRES_PASSWORD: ${MCAPTCHA_PG_PASSWORD}
volumes:
- mcaptcha-pg-data:/var/lib/postgresql/data
healthcheck:
test: ["CMD-SHELL", "pg_isready -U postgres"]
interval: 10s
timeout: 5s
retries: 10
mcaptcha_redis:
image: mcaptcha/cache:latest
restart: unless-stopped
networks: [mcaptcha-net]