Ops: add Proxmox migration tooling and runbook

Add end-to-end migration scripts for inventory, precopy, cutover, smoke tests, rollback, and post-migration checks. Include an operational runbook and Proxmox env template to move Hördle behind Nginx Proxy Manager while preserving persistent volumes safely.
2026-04-25 09:46:52 +00:00
parent e58e9156d6
commit 1c7bfdf421
10 changed files with 607 additions and 0 deletions
@@ -0,0 +1,121 @@
+# Hördle Migration Runbook (Proxmox-LXC + Nginx Proxy Manager)
+
+Dieses Runbook setzt den Migrationsplan operativ um und priorisiert Datensicherheit
+fuer `data/prod.db` und `public/uploads`.
+
+## 0) Voraussetzungen
+
+- Quelle (alt): VPS mit laufendem Hördle-Compose-Stack.
+- Ziel (neu): Proxmox-LXC unter `root@10.0.0.19`.
+- DNS ist bereits vorbereitet.
+- Ziel-LXC ist im internen Netz vom NPM-LXC erreichbar.
+
+## 1) Inventur auf der Quelle
+
+```bash
+cd /home/docker/hoerdle
+./scripts/migration-inventory.sh
+```
+
+Erwartung:
+- Persistenzpfade vorhanden: `data`, `data/prod.db`, `public/uploads`
+- Runtime-Variablen in `docker-compose.yml` referenzieren `.env`
+
+## 2) Ziel-LXC vorbereiten
+
+Auf dem Ziel-LXC (`root@10.0.0.19`):
+
+```bash
+mkdir -p /opt/hoerdle
+# Repo nach /opt/hoerdle bringen (git clone oder rsync)
+cd /opt/hoerdle
+./scripts/migration-prepare-target.sh
+```
+
+Danach:
+- `.env` in `/opt/hoerdle/.env` produktiv ausfuellen
+- `ADMIN_PASSWORD` als bcrypt hash setzen
+- Caddy-Stack nicht verwenden (nur `docker-compose.yml`)
+
+## 3) Vorabkopie der Daten (Quelle -> Ziel)
+
+Auf der Quelle:
+
+```bash
+cd /home/docker/hoerdle
+TARGET_HOST=root@10.0.0.19 TARGET_APP_DIR=/opt/hoerdle ./scripts/migration-precopy.sh
+```
+
+Das Skript synchronisiert:
+- `data/`
+- `public/uploads/`
+
+und zeigt Dateizaehlung/Groessen als Plausibilitaetscheck.
+
+## 4) Cutover im Wartungsfenster
+
+Auf der Quelle:
+
+```bash
+cd /home/docker/hoerdle
+TARGET_HOST=root@10.0.0.19 TARGET_APP_DIR=/opt/hoerdle ./scripts/migration-cutover.sh
+```
+
+Das Skript:
+1. stoppt die Quell-App,
+2. fuehrt Final-Sync aus,
+3. verifiziert `prod.db` per SHA256,
+4. startet die Ziel-App mit `docker compose up -d --build`.
+
+## 5) NPM umschalten + Smoke-Test
+
+Im Nginx Proxy Manager:
+- Proxy Host auf `10.0.0.19:3010` setzen
+- Scheme `http`, Websocket Support aktiv
+- SSL aktivieren (Let's Encrypt), Force SSL einschalten
+- Header-Weiterleitung aktiv lassen (`X-Forwarded-*`)
+
+Smoke-Test:
+
+```bash
+./scripts/migration-smoke-test.sh https://hoerdle.de
+```
+
+Zusatzpruefungen manuell:
+- Admin-Login
+- Upload eines Testfiles
+- Abruf des Uploads im Frontend
+
+## 6) Post-Migration (24h)
+
+- `docker compose logs --since=24h` auf Ziel auswerten
+- NPM Access/Error Logs pruefen
+- taegliches Backup sicherstellen:
+  - `data/prod.db`
+  - `public/uploads/`
+- Alte Instanz erst nach stabiler Beobachtungszeit stilllegen
+
+Automatisierter Postcheck:
+
+```bash
+cd /opt/hoerdle
+DOMAIN_URL=https://hoerdle.de ./scripts/migration-postcheck.sh
+```
+
+Beispiel fuer taegliches Backup (cron auf Ziel-LXC):
+
+```bash
+crontab -e
+# taeglich 03:30
+30 3 * * * cd /opt/hoerdle && ./scripts/backup-persistence.sh >> /opt/hoerdle/logs/backup-persistence.log 2>&1
+```
+
+## 7) Rollback
+
+Wenn Tests fehlschlagen:
+
+```bash
+TARGET_HOST=root@10.0.0.19 TARGET_APP_DIR=/opt/hoerdle ./scripts/migration-rollback.sh
+```
+
+Danach sofort im NPM auf alte Instanz zurueckschalten.