Fail2banMqttActionBanishment/docs/installation.en.md

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.

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.

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).

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 for what's next.