Docs: translate README and guides to German
README and all guides under docs/ are now in German, with German anchors for the cross references. Code and configuration blocks are unchanged. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
This commit is contained in:
schiwagoaandClaude Opus 5.5 committed
1 parent
2e3f79236c
commit
019c74a418
8 files changed
+469
-463
No files matched your search
+46
-45
@@ -1,24 +1,24 @@
|
||||
# Development
|
||||
# Entwicklung
|
||||
|
||||
## Layout
|
||||
## Aufbau
|
||||
|
||||
```
|
||||
app/webui/ Flask application (package "webui")
|
||||
app.py routes, security headers, audit log
|
||||
auth.py local / OIDC / proxy authentication, login lockout
|
||||
backend.py SSH to the agents, GeoIP, Loki
|
||||
app/webui/ Flask-Anwendung (Paket "webui")
|
||||
app.py Routen, Sicherheits-Header, Protokoll
|
||||
auth.py Anmeldung lokal / OIDC / Proxy, Login-Sperre
|
||||
backend.py SSH zu den Agenten, GeoIP, Loki
|
||||
cli.py serve, hash-password, keygen, keyscan, check
|
||||
config.py settings from the environment, hosts.yaml
|
||||
i18n.py, locales/ translations (one JSON file per language)
|
||||
templates/, static/
|
||||
config.py Einstellungen aus der Umgebung, hosts.yaml
|
||||
i18n.py, locales/ Übersetzungen (eine JSON-Datei pro Sprache)
|
||||
templates/, static/ (static/world.svg: Weltkarte, Natural Earth)
|
||||
agent/ f2b-webctl, install.sh, uninstall.sh
|
||||
docker/Dockerfile production image
|
||||
docker/Dockerfile Produktions-Image
|
||||
examples/ docker-compose.yaml, .env.example, hosts.yaml.example
|
||||
dev/testbed/ web UI + two fail2ban hosts in Docker
|
||||
tests/smoke_test.py web UI tests without Docker/SSH
|
||||
dev/testbed/ Weboberfläche + zwei fail2ban-Hosts in Docker
|
||||
tests/smoke_test.py Tests der Weboberfläche ohne Docker/SSH
|
||||
```
|
||||
|
||||
## Smoke test (no Docker needed)
|
||||
## Smoke-Test (ohne Docker)
|
||||
|
||||
```bash
|
||||
python3 -m venv .venv
|
||||
@@ -26,20 +26,20 @@ python3 -m venv .venv
|
||||
.venv/bin/python tests/smoke_test.py
|
||||
```
|
||||
|
||||
The agents are simulated. Covered: login, lockout, CSRF/Origin checks, translations,
|
||||
ban/unban validation, audit log, proxy mode, config validation, SSH command line, log
|
||||
injection.
|
||||
Die Agenten werden simuliert. Abgedeckt: Anmeldung, Login-Sperre, CSRF-/Origin-Prüfung,
|
||||
Übersetzungen, Prüfung beim Sperren/Entsperren, Protokoll, Proxy-Modus, Prüfung der
|
||||
Konfiguration, SSH-Befehlszeile, Log-Injection.
|
||||
|
||||
## Testbed (Docker)
|
||||
|
||||
`dev/testbed` starts the web UI and two Debian hosts with sshd and fail2ban (dummy ban
|
||||
actions – nothing is blocked). The agents are installed with `agent/install.sh` at
|
||||
container start:
|
||||
`dev/testbed` startet die Weboberfläche und zwei Debian-Hosts mit sshd und fail2ban
|
||||
(Dummy-Banactions – es wird nichts gesperrt). Die Agenten werden beim Containerstart mit
|
||||
`agent/install.sh` installiert:
|
||||
|
||||
| Host | Agent setup |
|
||||
| Host | Agent-Einrichtung |
|
||||
|---|---|
|
||||
| `agent1` | user `f2bweb` + sudo, `--from` the testbed network, extra protected IP |
|
||||
| `agent2` | user `root`, key in `authorized_keys2`, manual jail named `blocklist` |
|
||||
| `agent1` | Benutzer `f2bweb` + sudo, `--from` auf das Testbed-Netz, zusätzliche geschützte IP |
|
||||
| `agent2` | Benutzer `root`, Schlüssel in `authorized_keys2`, manuelles Jail namens `blocklist` |
|
||||
|
||||
```bash
|
||||
cd dev/testbed
|
||||
@@ -52,42 +52,43 @@ docker compose up -d agent1 agent2
|
||||
docker compose run --rm webui keyscan --yes
|
||||
docker compose run --rm webui check
|
||||
docker compose up -d webui # http://127.0.0.1:18080
|
||||
docker compose down -v # remove everything
|
||||
docker compose down -v # alles entfernen
|
||||
```
|
||||
|
||||
`hosts.yaml` is written into the data volume because Docker Desktop cannot bind-mount
|
||||
network drives. After recreating an agent its host key changes – run `keyscan` again.
|
||||
`hosts.yaml` wird ins Daten-Volume geschrieben, weil Docker Desktop Netzlaufwerke nicht
|
||||
einbinden kann. Nach dem Neuanlegen eines Agenten ändert sich sein Host-Schlüssel –
|
||||
`keyscan` erneut ausführen.
|
||||
|
||||
On Windows with Git Bash, prefix `docker compose exec … /path` with `MSYS_NO_PATHCONV=1`,
|
||||
otherwise the path is rewritten to a Windows path.
|
||||
Unter Windows mit Git Bash `docker compose exec … /pfad` mit `MSYS_NO_PATHCONV=1`
|
||||
voranstellen, sonst wird der Pfad in einen Windows-Pfad umgeschrieben.
|
||||
|
||||
## Adding a language
|
||||
## Neue Sprache hinzufügen
|
||||
|
||||
1. Copy `app/webui/locales/en.json` to `app/webui/locales/<code>.json` (e.g. `fr.json`).
|
||||
2. Set `"_name"` to the language's own name (`"Français"`) – it appears in the dropdown.
|
||||
3. Translate the values; keep `{placeholders}` unchanged. Missing keys fall back to English.
|
||||
4. Run the smoke test and check the UI.
|
||||
1. `app/webui/locales/en.json` nach `app/webui/locales/<code>.json` kopieren (z. B. `fr.json`).
|
||||
2. `"_name"` auf den Eigennamen der Sprache setzen (`"Français"`) – so erscheint sie im Dropdown.
|
||||
3. Die Werte übersetzen; `{Platzhalter}` unverändert lassen. Fehlende Schlüssel fallen auf Englisch zurück.
|
||||
4. Smoke-Test ausführen und die Oberfläche prüfen.
|
||||
|
||||
## Building the image
|
||||
## Image bauen
|
||||
|
||||
```bash
|
||||
docker build -f docker/Dockerfile --build-arg VERSION=1.0.0 -t fail2ban-webui:1.0.0 .
|
||||
# multi-arch, as in CI
|
||||
# Multi-Arch, wie in der CI
|
||||
docker buildx build -f docker/Dockerfile --platform linux/amd64,linux/arm64 \
|
||||
--build-arg VERSION=1.0.0 -t git.retronerd.at/schiwagoa/fail2ban-webui:1.0.0 --push .
|
||||
```
|
||||
|
||||
Scan before publishing:
|
||||
Vor dem Veröffentlichen scannen:
|
||||
|
||||
```bash
|
||||
docker run --rm -v /var/run/docker.sock:/var/run/docker.sock aquasec/trivy:0.58.1 \
|
||||
image --scanners vuln --ignore-unfixed --severity HIGH,CRITICAL fail2ban-webui:1.0.0
|
||||
```
|
||||
|
||||
## Agent protocol
|
||||
## Agent-Protokoll
|
||||
|
||||
The web UI runs `ssh … <user>@<host> "<command>"`; the agent reads the command from
|
||||
`SSH_ORIGINAL_COMMAND` and prints exactly one JSON line:
|
||||
Die Weboberfläche führt `ssh … <benutzer>@<host> "<befehl>"` aus; der Agent liest den Befehl
|
||||
aus `SSH_ORIGINAL_COMMAND` und gibt genau eine JSON-Zeile aus:
|
||||
|
||||
```json
|
||||
{"ok": true, "host": "web01", "agent_version": "1.0.0", "manual_jail": "manual-block",
|
||||
@@ -95,12 +96,12 @@ The web UI runs `ssh … <user>@<host> "<command>"`; the agent reads the command
|
||||
"bantime": 600, "end": "2026-10-25 10:10:00"}], "total": 42}}}
|
||||
```
|
||||
|
||||
Errors: `{"ok": false, "error_key": "agent_protected", "error_args": {"ip": "…"}, "error": "English text"}`.
|
||||
The web UI translates `error_key` with `locales/*.json` (keys starting with `agent_`);
|
||||
unknown keys show the English `error`.
|
||||
Fehler: `{"ok": false, "error_key": "agent_protected", "error_args": {"ip": "…"}, "error": "English text"}`.
|
||||
Die Weboberfläche übersetzt `error_key` mit `locales/*.json` (Schlüssel mit Präfix `agent_`);
|
||||
unbekannte Schlüssel zeigen den englischen `error`-Text.
|
||||
|
||||
## Versioning
|
||||
## Versionierung
|
||||
|
||||
- Version numbers follow SemVer and are set at build time (`VERSION` build arg →
|
||||
`APP_VERSION`); the agent has its own `VERSION` in `agent/f2b-webctl`.
|
||||
- Every change goes into `CHANGELOG.md` under *Unreleased*.
|
||||
- Versionsnummern folgen SemVer und werden beim Bauen gesetzt (Build-Argument `VERSION` →
|
||||
`APP_VERSION`); der Agent hat eine eigene `VERSION` in `agent/f2b-webctl`.
|
||||
- Jede Änderung kommt in `CHANGELOG.md` unter *Unreleased*.
|
||||
Reference in new issue
Block a user