feat(security): opt-in local CrowdSec LAPI bouncer on the Docker engine

README.md

@@ -775,6 +775,88 @@ Open **DevOps → Anti-DDoS protection**
 
 ---
 
+## Local CrowdSec Engine (opt-in)
+
+The repository ships a self-contained CrowdSec engine that runs on the same
+Docker host. It reads the host Nginx access log, runs
+`crowdsecurity/crowdsec:1.8.1` in its own Compose project and exposes LAPI only
+on `127.0.0.1:18080`. When enabled, the app-layer anti-DDoS gate
+(`src/lib/crowdsec-local.ts`) asks the local LAPI per client IP (short-cached)
+and blocks `ban` / `captcha` decisions before its own rate buckets run.
+No reverse-proxy, Traefik, Cloudflare or firewall configuration is changed.
+
+### Step 1 — Enable the engine and register the bouncer
+
+```bash
+bash cms security
+```
+
+This generates `CROWDSEC_LAPI_API_KEY` (random 64 hex chars), writes the
+CrowdSec flags into `.env`, starts the engine and registers the `cms` bouncer
+against the local LAPI. The engine does **not** enroll into the CrowdSec
+Central API (`DISABLE_ONLINE_API=true`): detection stays local.
+
+### Step 2 — Restart the CMS so it loads the bouncer credentials
+
+A CI-managed `epicnext-cms-app` picks the new `.env` values up on its next
+deployment. For a clone running via the updater:
+
+```bash
+bash cms update --skip-pull
+```
+
+or restart the container directly (`docker compose restart cms`). Without the
+restart the gate has not loaded the LAPI URL/key yet.
+
+### Step 3 — Verify
+
+```bash
+bash cms security status
+```
+
+Expect `CROWDSEC_LOCAL_ENABLED=yes` and `LAPI health: OK (127.0.0.1:18080)`.
+In the admin panel, **DevOps → Anti-DDoS protection** shows live block
+statistics split per origin (`community` vs `local`).
+
+### Step 4 — Stop the engine again (optional)
+
+```bash
+bash cms security disable
+```
+
+Stops the container and sets `CROWDSEC_LOCAL_ENABLED=false`. Volumes and the
+`.env` key are kept.
+
+### Environment variables
+
+| Variable                     | Default                       | Purpose                              |
+| ---------------------------- | ----------------------------- | ------------------------------------ |
+| `CROWDSEC_LOCAL_ENABLED`     | `false`                       | Master switch for the local stack    |
+| `CROWDSEC_LAPI_URL`          | `http://127.0.0.1:18080`      | LAPI endpoint (loopback only)        |
+| `CROWDSEC_LAPI_PORT`         | `18080`                       | Host port the engine maps to LAPI    |
+| `CROWDSEC_LAPI_API_KEY`      | —                             | Bouncer key; required when enabled   |
+| `CROWDSEC_LAPI_TIMEOUT_MS`   | `500`                         | Per-decision request timeout         |
+| `CROWDSEC_LAPI_RETRY_MS`     | `500`                         | Backoff before retrying LAPI         |
+| `CROWDSEC_NGINX_LOG_DIR`     | `/var/log/nginx`              | Access-log directory for the engine  |
+
+### Notes and limitations
+
+- Changing the port means updating `CROWDSEC_LAPI_PORT` **and**
+  `CROWDSEC_LAPI_URL` together, then re-running `bash cms security`.
+- Rotate the key by editing `CROWDSEC_LAPI_API_KEY` in `.env`, running
+  `bash cms security` again (re-registers the bouncer) and restarting the CMS.
+- The gate is **fail-closed at startup** when the feature is enabled without a
+  key (startup aborts with a clear message). At runtime a LAPI network error
+  **fails open** (traffic is allowed, decisions paused); a 403 from LAPI
+  pauses local decisions for 5 minutes.
+- This bouncer is **application-layer**: it sheds known-bad IPs at the CMS
+  process only. It does not drop traffic before the origin, does not protect
+  other host ports/services, and depends on the client IP being trustworthy at
+  the ingress. Keep the upstream protections (Cloudflare IP rules, proxy rate
+  limits) for defense before the origin.
+
+---
+
 ## Production Deployment (PM2)
 
 ```bash