Initial Docker deployment setup

README.md

@@ -0,0 +1,115 @@
+# Docker-Deployment
+
+Dieses Compose-Rezept baut sowohl das Backend als auch den Banner-Generator mit
+Nuitka direkt aus dem aktuellen Checkout. Es wird kein vorcompiliertes
+Drivers-Hub-Binary heruntergeladen. Das fertige Runtime-Image enthält weder den
+Compiler noch eine Python-Laufzeitumgebung.
+
+Der Stack umfasst Drivers Hub, Banner-Generator, MariaDB 10.11 und Valkey 8. Die
+Datenbank wird vor dem ersten Backend-Start durch den einmaligen Dienst `db-init`
+initialisiert.
+
+## Konfiguration
+
+Zuerst werden die Deployment- und Anwendungskonfiguration angelegt:
+
+```bash
+cp .env.example .env
+cp upstream/HubBackend/config_sample.json config/config.json
+```
+
+In `.env` müssen sichere Passwörter für MariaDB eingetragen werden. Anschließend
+wird `config/config.json` mindestens wie folgt angepasst:
+
+```json
+{
+    "abbr": "drivershub",
+    "name": "Drivers Hub",
+    "domain": "localhost",
+    "prefix": "/api",
+    "server_host": "0.0.0.0",
+    "server_port": 7777,
+    "db_host": "mariadb",
+    "db_user": "drivershub",
+    "db_password": "dasselbe Passwort wie DB_PASSWORD in .env",
+    "db_name": "drivershub",
+    "db_data_directory": "/var/lib/mysqlext/",
+    "redis_host": "valkey",
+    "redis_port": 6379
+}
+```
+
+Die gezeigten Schlüssel sind nur die zu ändernden Werte. Alle übrigen Schlüssel
+aus `config_sample.json` müssen erhalten bleiben. `config/config.json` ist die
+echte, persistente Anwendungskonfiguration und kann im laufenden Betrieb weiter
+bearbeitet werden. Ein Image-Neubau ist für Konfigurationsänderungen nicht nötig;
+anschließend genügt ein Neustart des Backends.
+
+Das Datenbankpasswort muss in `.env` und `config/config.json` übereinstimmen, da
+sowohl der MariaDB-Container als auch Drivers Hub es unabhängig voneinander beim
+Start benötigen. Alle rein fachlichen Einstellungen werden ausschließlich in
+`config/config.json` gepflegt.
+
+## Start
+
+```bash
+docker compose build
+docker compose up -d
+docker compose ps
+```
+
+Standardmäßig ist die API unter `http://localhost:7777/api` und Swagger UI unter
+`http://localhost:7777/api/doc` erreichbar.
+
+## Persistente Daten
+
+Alle persistenten Daten liegen im Projektverzeichnis:
+
+```text
+data/
+├── mariadb/
+├── mariadb-external/
+└── valkey/
+```
+
+Die Verzeichnisse entstehen beim ersten Start automatisch. Alternativ können die
+drei Host-Pfade in `compose.yaml` beispielsweise nach `../drivershub-data/`
+geändert werden. MariaDB und Valkey veröffentlichen keine Ports am Host.
+
+`docker compose down` entfernt Container und Netzwerk, lässt `config/` und
+`data/` aber unangetastet. Diese Verzeichnisse müssen bewusst separat gesichert
+oder gelöscht werden.
+
+## Upstream aktualisieren
+
+`upstream/HubBackend` ist ein normaler, eigenständiger Git-Clone und bleibt
+inhaltlich unverändert. Ein Update und anschließender Neubau erfolgen mit:
+
+```bash
+git -C upstream/HubBackend pull --ff-only
+docker compose build
+docker compose up -d
+```
+
+## Betrieb
+
+```bash
+# Logs anzeigen
+docker compose logs -f backend
+
+# Nach Änderungen an config/config.json
+docker compose restart backend
+
+# Benutzer mit dem compilierten Programm anlegen
+docker compose run --rm backend \
+  drivershub --config /app/config/config.json setup create-user user@example.com
+
+# Nach Änderungen am Quellcode neu bauen
+docker compose build
+docker compose up -d
+```
+
+MariaDB erhält für den festen Benutzer `drivershub` das globale `FILE`-Recht,
+weil das Projekt Tabellen mit `DATA DIRECTORY` anlegt. Eine Änderung dieses
+Benutzernamens muss sowohl in `compose.yaml`, `config/config.json` als auch in
+`docker/mariadb-init.sql` nachvollzogen werden.