First commit

docs/installation.en.md

@@ -0,0 +1,73 @@
+# Installation
+
+## Prerequisites
+
+- **Debian 13** VPS, root access (or an account with `sudo`).
+- The repository cloned into the `$HOME` of a **non-root** user dedicated
+  to this project (e.g. `banisher`) — `install.sh`/`make install`
+  determine this user from the repository's actual owner
+  (`stat -c '%U' <repo>`), never hardcoded. Trade-off accepted: the user
+  gets full `sudo` access (`NOPASSWD:ALL`), to be reserved for an account
+  strictly dedicated to this project.
+
+```sh
+git clone <repo-url> ~/Fail2banMqttActionBanisher
+cd ~/Fail2banMqttActionBanisher
+```
+
+## Development (without real fail2ban/iptables)
+
+Requires a reachable Redis (Django Channels channel layer), e.g.
+`docker run -p 6379:6379 redis`.
+
+```sh
+make run       # dashboard + map, http://127.0.0.1:8000/
+make mqtt      # in a second terminal: MQTT ingestion
+make worker    # in a third terminal: async geolocation
+```
+
+These targets automatically create the Python venv (`emitter/.venv`) and
+install dependencies on first run.
+
+Environment variables (`MQTT_BROKER_HOST`, `MQTT_BROKER_USERNAME`,
+`MQTT_BROKER_PASSWORD`, `REDIS_HOST`, `REDIS_PORT`, ...): copy
+`.env.example` to `.env` at the repo root and edit it — loaded
+automatically by Django (`python-dotenv`), nothing to export by hand.
+
+## First production node
+
+!!! warning "Must be adapted before `make install`"
+    `generic/firewall/firewall-filters.conf` and the files under
+    `generic/fail2ban/jail.d/` come from the reference server
+    (`miraceti-vps1`, a master) and contain rules specific to it
+    (OpenVPN, Coturn, WireGuard, Portainer, a hardcoded public IP,
+    `DOCKER-USER`...). On a plain node, keep only what's actually
+    exposed (typically SSH + 80/443) — the unneeded sections reference
+    interfaces (`$VPN_IF`, `$WG_IF`) that don't exist on a node, which
+    produces silent `iptables` errors (the script keeps going, but the
+    intended rule is never applied). Also check `ETH_IF` in
+    `generic/firewall/firewall-launcher.sh` (real interface name:
+    `ip -o link show`), and disable `ufw` if present (having both
+    `iptables` rulesets active at once breaks one of them in
+    unpredictable ways).
+
+```sh
+sudo make install
+sudo make status
+```
+
+Deploys and enables: system packages (fail2ban, iptables, mosquitto,
+Redis), firewall, custom fail2ban jails, local Mosquitto broker, and the
+Django emitter's four services (web, MQTT ingestion, Celery worker,
+master relay). Idempotent: re-running `sudo make install` after a
+`git pull` reapplies dependencies/migrations and restarts the affected
+services.
+
+Edit `/etc/fail2ban/mqtt.conf` (real MQTT credentials, copied from
+`generic/fail2ban/mqtt.conf.example` if it doesn't exist yet) before the
+first deployment.
+
+A freshly installed node already works standalone (local detection and
+banning) ; the relay to a master (`fail2ban-emitter-master-client`) will
+keep retrying in a loop until a node certificate has been obtained — see
+[Production deployment](deployment.en.md) for what's next.