From 97b0c14dac3346fc68d9eecf355802af6fc9bf59 Mon Sep 17 00:00:00 2001 From: SchiWaGoA Date: Sun, 25 Oct 2026 17:05:58 +0100 Subject: [PATCH] Docs: prerequisites, docker installer and first-run errors MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit - README: prerequisites before the quick start – base packages (curl, git, mc optional), Docker via public-docker-installer-26.04-v1 with compose plugin check, LXC features, packages for fail2ban hosts - Local image build as long as the image is not in the registry yet - Troubleshooting: missing curl/git, missing compose plugin, image pull Co-Authored-By: Claude Opus 5.5 --- README.md | 75 ++++++++++++++++++++++++++++++++++++++++---- docs/installation.md | 16 +++++++++- docs/operations.md | 3 ++ 3 files changed, 87 insertions(+), 7 deletions(-) diff --git a/README.md b/README.md index 238a029..4149844 100644 --- a/README.md +++ b/README.md @@ -28,15 +28,84 @@ private Netze, die eigenen Adressen des Hosts oder Einträge seiner Schutzliste protokolliert jede Aktion im Syslog. Zugriff auf den fail2ban-Socket wäre gleichbedeutend mit root – die Sicherheitsgrenze ist der Agent, nicht die Weboberfläche. +## Voraussetzungen + +Getestet auf Ubuntu 24.04/26.04 und Debian 12/13 – Bare Metal, VM oder LXC. +Alle Befehle als root. + +### Grundpakete (alle Hosts) + +```bash +apt update +apt install -y curl git +apt install -y mc # optional: Midnight Commander als Dateimanager +``` + +### Docker-Host (Weboberfläche) + +Gebraucht wird eine vollständige Docker-Umgebung – Docker Engine **und** das Compose-Plugin +(Befehl `docker compose` mit Leerzeichen), `amd64` oder `arm64`. + +Auf Ubuntu 24.04/26.04 z. B. mit dem +[Docker-Installer](https://git.retronerd.at/schiwagoa/public-docker-installer-26.04-v1): + +```bash +git clone https://git.retronerd.at/schiwagoa/public-docker-installer-26.04-v1.git +cd public-docker-installer-26.04-v1 +chmod +x *.sh +./docker-installer-2604-v1.sh +``` + +Diese Anleitung verwendet `docker compose` (Plugin). Der Installer richtet zusätzlich das +eigenständige `docker-compose` ein; das Plugin kommt normalerweise mit `docker-ce` mit. +Prüfen – beide Befehle müssen eine Version ausgeben: + +```bash +docker version --format '{{.Server.Version}}' +docker compose version +``` + +Meldet `docker compose version` den Fehler `'compose' is not a docker command`, das Plugin +nachinstallieren: `apt install -y docker-compose-plugin`. + +In einem **LXC-Container** braucht Docker auf dem Proxmox-Host die Features +`nesting=1,keyctl=1` (unprivilegierter Container: `pct set --features nesting=1,keyctl=1`, +danach den Container neu starten). + +### fail2ban-Hosts (Agent) + +```bash +apt install -y fail2ban python3 sudo openssh-server +systemctl enable --now fail2ban +fail2ban-client ping # Server replied: pong +``` + +- fail2ban ≥ 0.11 (Start-/Endzeiten der Sperren brauchen `--with-time`) +- `sudo` nur für den Standardbenutzer `f2bweb`; mit einem root-Schlüssel nicht nötig +- `bash`, `ssh-keygen` (Teil von OpenSSH) für den Installer + ## Schnellstart +Voraussetzungen siehe oben (Grundpakete, Docker, Agent auf den fail2ban-Hosts). + ```bash mkdir -p /opt/fail2ban-webui/{config,data} && cd /opt/fail2ban-webui curl -fsSLo docker-compose.yaml https://git.retronerd.at/schiwagoa/fail2ban-webui/raw/branch/main/examples/docker-compose.yaml curl -fsSLo .env https://git.retronerd.at/schiwagoa/fail2ban-webui/raw/branch/main/examples/.env.example curl -fsSLo config/hosts.yaml https://git.retronerd.at/schiwagoa/fail2ban-webui/raw/branch/main/examples/hosts.yaml.example chown -R 10050:10050 data +``` +> **Noch kein fertiges Image:** Solange `git.retronerd.at/schiwagoa/fail2ban-webui` in der +> Registry noch nicht veröffentlicht ist, das Image einmalig lokal unter demselben Namen +> bauen – Docker Compose verwendet dann das lokale Image und versucht keinen Download: +> +> ```bash +> git clone https://git.retronerd.at/schiwagoa/fail2ban-webui.git /opt/fail2ban-webui-src +> docker build -f /opt/fail2ban-webui-src/docker/Dockerfile --build-arg VERSION=dev > -t git.retronerd.at/schiwagoa/fail2ban-webui:latest /opt/fail2ban-webui-src +> ``` + +```bash docker compose run --rm -it fail2ban-webui hash-password # Zeile in die .env übernehmen docker compose run --rm fail2ban-webui keygen # öffentlicher Schlüssel für die Agenten # auf jedem fail2ban-Host den Agenten installieren (docs/agent.md), danach: @@ -60,12 +129,6 @@ Die Oberfläche lauscht auf `127.0.0.1:8080` – davor gehört ein Reverse Proxy | [Entwicklung](docs/development.md) | lokales Testbed, Tests, neue Sprache hinzufügen | | [Sicherheit](SECURITY.md) | Sicherheitsmodell und Melden von Schwachstellen | -## Voraussetzungen - -- Weboberfläche: Docker mit Compose v2, `amd64` oder `arm64` -- Jeder fail2ban-Host: fail2ban ≥ 0.11 (Start-/Endzeiten brauchen `--with-time`), `python3`, - `sshd`, `sudo` (oder ein root-Schlüssel), `bash` - ## Lizenz [MIT](LICENSE). IP-Geolokalisierung durch [DB-IP Lite](https://db-ip.com) (CC BY 4.0), wird diff --git a/docs/installation.md b/docs/installation.md index 3dc2efd..b14d61f 100644 --- a/docs/installation.md +++ b/docs/installation.md @@ -9,7 +9,11 @@ Die Agenten auf den fail2ban-Hosts sind in [agent.md](agent.md) beschrieben; du ## 1. Voraussetzungen -- Docker Engine mit Compose v2 (`docker compose version`) +- Grundpakete `curl` und `git` (`apt install -y curl git`; `mc` optional) – in frischen + LXC-Templates fehlt `curl` +- Docker Engine mit Compose-Plugin (`docker compose version`), z. B. über den + [Docker-Installer](https://git.retronerd.at/schiwagoa/public-docker-installer-26.04-v1) – + Details in den [Voraussetzungen im README](../README.md#voraussetzungen) - Ausgehendes SSH (TCP 22 oder dein Port) vom Docker-Host zu jedem fail2ban-Host - Ein DNS-Name und ein Reverse Proxy mit TLS für die Oberfläche (siehe [reverse-proxy.md](reverse-proxy.md)) @@ -105,6 +109,16 @@ networks: Läuft der Reverse Proxy auf einer anderen Maschine, den Port stattdessen an die LAN-Adresse binden, z. B. `"192.168.1.10:8080:8080"` – niemals ohne Firewall davor an `0.0.0.0`. +Solange das Image in der Registry noch nicht veröffentlicht ist, schlägt der Download fehl +(`manifest unknown` bzw. `pull access denied`). Dann das Image einmalig lokal unter demselben +Namen bauen: + +```bash +git clone https://git.retronerd.at/schiwagoa/fail2ban-webui.git /opt/fail2ban-webui-src +docker build -f /opt/fail2ban-webui-src/docker/Dockerfile --build-arg VERSION=dev \ + -t git.retronerd.at/schiwagoa/fail2ban-webui:latest /opt/fail2ban-webui-src +``` + ## 4. .env Mit dieser minimalen Datei beginnen; alle Optionen stehen in diff --git a/docs/operations.md b/docs/operations.md index 739d563..56d0af0 100644 --- a/docs/operations.md +++ b/docs/operations.md @@ -133,6 +133,9 @@ ein präparierter Benutzername kann also keine zweite Logzeile einschleusen. | Symptom | Ursache / Lösung | |---|---| +| `curl: command not found` / `git: command not found` | frisches Minimal-System (z. B. LXC-Template) → `apt install -y curl git` | +| `docker: 'compose' is not a docker command` | nur das eigenständige `docker-compose` vorhanden → `apt install -y docker-compose-plugin` | +| `manifest unknown` / `pull access denied` beim Start | Image noch nicht in der Registry → lokal bauen, siehe [Installation, Schritt 3](installation.md#3-docker-composeyaml) | | Container beendet sich: `… is not writable for UID 10050` | `chown -R 10050:10050 data` | | Container beendet sich: `AUTH_MODE=local needs AUTH_PASSWORD_HASH` | `hash-password` ausführen, Zeile mit einfachen Anführungszeichen einfügen | | Container beendet sich: `No hosts configured` | `config/hosts.yaml` fehlt oder ist leer; unter Windows/Docker Desktop: das Laufwerk lässt sich nicht einbinden |