fail2ban-webui/docs/installation.md

# Installation – Weboberfläche

Diese Anleitung richtet die Weboberfläche Schritt für Schritt auf einem Docker-Host ein.
Die Agenten auf den fail2ban-Hosts sind in [agent.md](agent.md) beschrieben; du brauchst beides.

- Quelle: <https://git.retronerd.at/schiwagoa/fail2ban-webui>
- Image: `git.retronerd.at/schiwagoa/fail2ban-webui` (`amd64`, `arm64`)
- Tags: `1.0.0` (genau diese Version), `1` (neueste 1.x), `latest`

## 1. Voraussetzungen

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

Prüfen, ob das Subnetz aus dem Beispiel (`172.23.51.0/24`) frei ist:

```bash
docker network inspect $(docker network ls -q) --format '{{.Name}} {{range .IPAM.Config}}{{.Subnet}}{{end}}' | grep 172.23.51 \
  || echo "172.23.51.0/24 is free"
```

Ist es belegt, ein anderes `/24` wählen und in Schritt 3 anpassen.

## 2. Verzeichnisse

```bash
mkdir -p /opt/fail2ban-webui/config /opt/fail2ban-webui/data
cd /opt/fail2ban-webui
# der Container läuft als UID 10050 und muss in data/ schreiben
chown -R 10050:10050 data
chmod 700 data
```

| Pfad | Inhalt |
|---|---|
| `docker-compose.yaml` | der Dienst |
| `.env` | Einstellungen und Geheimnisse (Passwort-Hash, OIDC-Secret) |
| `config/hosts.yaml` | die fail2ban-Hosts (schreibgeschützt eingebunden) |
| `data/` | SSH-Schlüssel, `known_hosts`, Sitzungsschlüssel, Protokoll, GeoIP-Datenbank |

## 3. docker-compose.yaml

```bash
nano docker-compose.yaml
```

```yaml
# =====================================================================
# fail2ban-webui – example docker-compose.yaml
#
#   mkdir -p fail2ban-webui/{config,data} && cd fail2ban-webui
#   (copy this file, .env.example as .env and hosts.yaml.example as config/hosts.yaml)
#   chown -R 10050:10050 data
#
# The UI listens on 127.0.0.1:8080 only – put a reverse proxy with TLS in front of it.
# The network uses its own /24 subnet; change it if it collides with an existing one
# (docker network inspect $(docker network ls -q) | grep Subnet).
# =====================================================================
name: fail2ban-webui

services:
  fail2ban-webui:
    image: git.retronerd.at/schiwagoa/fail2ban-webui:latest
    # build: { context: .., dockerfile: docker/Dockerfile }   # build from the repository instead
    container_name: fail2ban-webui
    restart: unless-stopped
    env_file: .env
    environment:
      TZ: ${TZ:-Europe/Vienna}
    read_only: true
    tmpfs:
      - /tmp
    cap_drop:
      - ALL
    security_opt:
      - no-new-privileges:true
    volumes:
      - ./config:/config:ro
      - ./data:/data
    ports:
      - "127.0.0.1:8080:8080"
    extra_hosts:
      # lets the container reach an agent on the Docker host itself (address: host.docker.internal)
      - "host.docker.internal:host-gateway"
    deploy:
      resources:
        limits:
          memory: 256M
    networks:
      fail2ban-webui.dockernetwork.local:
        ipv4_address: 172.23.51.10

networks:
  fail2ban-webui.dockernetwork.local:
    name: fail2ban-webui.dockernetwork.local
    driver: bridge
    ipam:
      config:
        - subnet: 172.23.51.0/24
          gateway: 172.23.51.1
          ip_range: 172.23.51.128/25
```

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

## 4. .env

Mit dieser minimalen Datei beginnen; alle Optionen stehen in
[configuration.md](configuration.md) und in [`examples/.env.example`](../examples/.env.example).

```bash
nano .env
chmod 600 .env
```

```ini
PUBLIC_URL=https://fail2ban.example.org
DEFAULT_LANG=en
TRUSTED_PROXY_HOPS=1

AUTH_MODE=local
AUTH_USER=admin
AUTH_PASSWORD_HASH='set in the next step'

SSH_USER=f2bweb
MANUAL_JAIL=manual-block
GEOIP_AUTO_DOWNLOAD=1
```

`DEFAULT_LANG=de` stellt die Oberfläche standardmäßig auf Deutsch; jeder Benutzer kann die
Sprache zusätzlich im Dropdown wählen.

### Passwort-Hash

```bash
docker compose run --rm -it fail2ban-webui hash-password
```

Die ausgegebene Zeile (`AUTH_PASSWORD_HASH='scrypt:…'`) in die `.env` kopieren und den
Platzhalter ersetzen. **Die einfachen Anführungszeichen beibehalten** – der Hash enthält
`$`-Zeichen, die Docker Compose sonst als Variablen auswerten würde. Für Single Sign-on
stattdessen siehe [authentication.md](authentication.md).

## 5. SSH-Schlüssel

```bash
docker compose run --rm fail2ban-webui keygen
```

Der Befehl erzeugt `data/ssh/id_ed25519` und gibt den öffentlichen Schlüssel aus
(`ssh-ed25519 AAAA… fail2ban-webui`). Kopieren – er wird für den Agent-Installer gebraucht.

## 6. Agenten

Den Agenten auf jedem fail2ban-Host installieren, wie in [agent.md](agent.md) beschrieben. Kurzfassung:

```bash
# auf jedem fail2ban-Host, als root
git clone https://git.retronerd.at/schiwagoa/fail2ban-webui.git /tmp/fail2ban-webui
echo 'ssh-ed25519 AAAA… fail2ban-webui' > /tmp/webui.pub
bash /tmp/fail2ban-webui/agent/install.sh --key-file /tmp/webui.pub --from <öffentliche IP des Webui-Hosts>
```

## 7. config/hosts.yaml

```bash
nano config/hosts.yaml
```

```yaml
hosts:
  - name: web01
    address: web01.example.org

  - name: lxc-proxy
    address: 192.168.1.20
    port: 2222

  # fail2ban on the Docker host itself
  - name: dockerhost
    address: host.docker.internal
```

`user` ist standardmäßig `SSH_USER` (`f2bweb`). Für Hosts, auf denen der Agent mit
`--user root` installiert wurde, `user: root` setzen.

## 8. Host-Schlüssel und Verbindungstest

```bash
docker compose run --rm -it fail2ban-webui keyscan
```

`keyscan` zeigt den Fingerprint jedes Hosts und fragt vor dem Schreiben von
`data/ssh/known_hosts` nach. Die Fingerprints mit den Hosts vergleichen:

```bash
# auf dem fail2ban-Host
ssh-keygen -lf /etc/ssh/ssh_host_ed25519_key.pub
```

Danach jeden Agenten testen:

```bash
docker compose run --rm fail2ban-webui check
```

```
OK    web01                agent 1.0.0, 3 jails, 12 bans
OK    lxc-proxy            agent 1.0.0, 2 jails, 0 bans
OK    dockerhost           agent 1.0.0, 4 jails, 7 bans
```

Jeder Host muss `OK` melden – sonst siehe [operations.md](operations.md#fehlersuche).

## 9. Starten

```bash
docker compose up -d
docker compose ps                      # STATUS: Up … (healthy)
docker compose logs -f fail2ban-webui  # mit Strg+C verlassen
```

Das Log zeigt eine Zusammenfassung wie
`fail2ban-webui 1.0.0 – hosts: web01, lxc-proxy, dockerhost – auth: local – loki: off – geoip: on`.

Ab jetzt läuft der Dienst. `docker compose run …` würde wegen der festen IP-Adresse mit
`Address already in use` scheitern – Hilfsbefehle deshalb im laufenden Container aufrufen:

```bash
docker compose exec fail2ban-webui python -m webui check
```

Lokaler Test ohne Proxy:

```bash
curl -s http://127.0.0.1:8080/healthz    # ok
```

## 10. Reverse Proxy

`http://127.0.0.1:8080` (oder die LAN-Adresse aus Schritt 3) unter deinem DNS-Namen mit
TLS veröffentlichen – Beispiele für Nginx Proxy Manager, Caddy, Traefik und nginx stehen in
[reverse-proxy.md](reverse-proxy.md). Dann `PUBLIC_URL` öffnen und anmelden.

## Nächste Schritte

- [Login mit fail2ban absichern](operations.md#login-mit-fail2ban-absichern)
- [Updates und Backups](operations.md)
- Optional: [Loki-Verlauf und Grafana-Links](configuration.md#loki-und-grafana)