docs: massive restructuring of documentation, development guides and agent playbooks
This commit is contained in:
@@ -0,0 +1,94 @@
|
||||
---
|
||||
type: How-to
|
||||
status: ACTIVE
|
||||
owner: DevOps Engineer
|
||||
---
|
||||
|
||||
# Runbook: Caddy & Pangolin Deployment (Plan-B Setup)
|
||||
|
||||
Dieses Dokument sichert das Wissen über die Konfiguration von Caddy als Webserver/Reverse-Proxy in Kombination mit Pangolin-Tunneln, welches während der "Plan-B" Online-Nennung erarbeitet wurde.
|
||||
|
||||
## 1. Architektur-Übersicht
|
||||
|
||||
* **Pangolin:** Stellt den sicheren Tunnel vom lokalen Netzwerk (Zora) ins Internet her (ersetzt Cloudflare). Leitet Traffic auf spezifische lokale Ports weiter.
|
||||
* **Caddy:** Agiert als Reverse-Proxy und TLS-Terminierungspunkt. Nimmt Traffic von Pangolin (und lokalem Netz) an und routet ihn zu den internen Docker-Services (z.B. Frontend-Web, API-Gateway).
|
||||
|
||||
## 2. Caddy Konfiguration (`Caddyfile`)
|
||||
|
||||
Die Konfiguration befindet sich in `config/docker/caddy/web-app/Caddyfile`.
|
||||
|
||||
### Wichtige Erkenntnisse / Fallstricke:
|
||||
* **TLS/SSL:** Caddy wurde mit `auto_https off` konfiguriert, da die SSL-Terminierung extern (Pangolin/Edge) erfolgt. Caddy läuft intern auf Port 80.
|
||||
* **Same-Origin Strategy:** Um CORS-Probleme im Browser zu vermeiden, werden alle API-Anfragen (`/api/*`) über Caddy an den `mail-service:8085` geproxt. Dies macht die App robuster gegen Browser-Security-Policies.
|
||||
* **MIME-Types:** Explizite Setzung von `application/wasm` für `.wasm` Dateien ist für KMP-Web-Apps kritisch (siehe Snippet).
|
||||
* **COOP/COEP Header:** Für WASM/KMP-Web-Apps sind `Cross-Origin-Embedder-Policy "require-corp"` und `Cross-Origin-Opener-Policy "same-origin"` essentiell, damit SharedArrayBuffer etc. funktionieren.
|
||||
* **Caching:**
|
||||
* Assets mit Hashes im Namen sind `immutable` (max-age 1 Jahr).
|
||||
* `.wasm` und `.js` Dateien wurden während Plan-B auf `no-store, no-cache, must-revalidate` gesetzt, um sicherzustellen, dass Teilnehmer immer die aktuellste Logik erhalten.
|
||||
* **Header-Weiterleitung:** Wichtige Header für das Backend: `X-Real-IP`, `X-Forwarded-For`, `X-Forwarded-Proto`.
|
||||
|
||||
### Aktuelles Plan-B Snippet:
|
||||
```caddyfile
|
||||
{
|
||||
auto_https off
|
||||
}
|
||||
|
||||
:80 {
|
||||
root * /usr/share/caddy
|
||||
|
||||
header {
|
||||
Cross-Origin-Embedder-Policy "require-corp"
|
||||
Cross-Origin-Opener-Policy "same-origin"
|
||||
}
|
||||
|
||||
# API Proxy (Same-Origin Strategy)
|
||||
handle /api/* {
|
||||
reverse_proxy mail-service:8085 {
|
||||
header_up Host {upstream_hostport}
|
||||
header_up X-Real-IP {remote_host}
|
||||
header_up X-Forwarded-For {remote_host}
|
||||
header_up X-Forwarded-Proto {scheme}
|
||||
}
|
||||
}
|
||||
|
||||
# Wasm MIME & Caching
|
||||
@wasm path *.wasm
|
||||
header @wasm Content-Type "application/wasm"
|
||||
|
||||
@wasm_js path *.wasm *.js
|
||||
header @wasm_js Cache-Control "no-store, no-cache, must-revalidate"
|
||||
|
||||
# SPA Fallback
|
||||
handle {
|
||||
try_files {path} /index.html
|
||||
file_server
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
## 3. Pangolin Konfiguration
|
||||
|
||||
### Erkenntnisse aus Plan-B:
|
||||
* **Tunnel-Endpunkt:** Pangolin leitet den Traffic von der öffentlichen Domain (z.B. `meldestelle.mo-code.at`) auf den lokalen Port der Zora-Instanz weiter (standardmäßig Port 80, gemappt auf Host-Port via Docker).
|
||||
* **Stabilität:** Der Pangolin-Client läuft als persistenter Dienst auf der Zora-Node. Er ist extrem stabil gegenüber IP-Wechseln des ISP (DSL-Reconnect).
|
||||
* **Konfiguration:** Erfolgt primär über das Pangolin-Dashboard (Web-UI). Wichtig ist das Mapping der Resource auf die interne IP von Zora.
|
||||
|
||||
## 4. Deployment-Workflow (Erkenntnisse)
|
||||
|
||||
### SMTP-Härtung (Plan-B Mail-Service)
|
||||
In `dc-planb.yaml` wurden folgende Einstellungen für World4You (SMTP) als stabil verifiziert:
|
||||
```yaml
|
||||
SPRING_MAIL_HOST: "smtp.world4you.com"
|
||||
SPRING_MAIL_PORT: "587"
|
||||
SPRING_MAIL_PROPERTIES_MAIL_SMTP_STARTTLS_ENABLE: "true"
|
||||
SPRING_MAIL_PROPERTIES_MAIL_SMTP_STARTTLS_REQUIRED: "true"
|
||||
```
|
||||
Wichtig: `STARTTLS_REQUIRED` verhindert den Versand, falls keine verschlüsselte Verbindung aufgebaut werden kann.
|
||||
|
||||
### Infrastruktur-Optimierung
|
||||
* **Zero-Downtime:** `docker compose exec web-app caddy reload --config /etc/caddy/Caddyfile` ermöglicht Konfigurationsänderungen ohne Container-Neustart.
|
||||
* **Health-Check:** Der `/health` Endpunkt in Caddy wurde genutzt, um die Erreichbarkeit des Containers zu prüfen.
|
||||
* **In-Memory DB:** Für Plan-B wurde die H2-Datenbank (In-Memory) genutzt, da keine Persistenz über den Turnier-Zeitraum hinaus (außer E-Mail-Kopien) nötig war. Dies vereinfachte das Deployment massiv.
|
||||
|
||||
---
|
||||
*Hinweis: Dieses Dokument basiert auf den erfolgreichen Feld-Tests vom April 2026.*
|
||||
@@ -0,0 +1,103 @@
|
||||
---
|
||||
type: Guide
|
||||
status: ACTIVE
|
||||
owner: DevOps Engineer
|
||||
last_update: 2026-03-05
|
||||
tags: [backup, postgres, zora, cron]
|
||||
---
|
||||
|
||||
# 🛡️ Guide: Automatisierte Backups auf Zora
|
||||
|
||||
Dieser Guide beschreibt, wie du regelmäßige Backups der Meldestelle-Datenbank und Konfigurationen auf Zora einrichtest.
|
||||
|
||||
## 📋 Voraussetzungen
|
||||
|
||||
* SSH-Zugriff auf Zora (`ssh user@10.0.0.xx`).
|
||||
* Docker-Container `meldestelle-postgres` läuft.
|
||||
* Das Skript `config/scripts/backup.sh` liegt im Repo.
|
||||
|
||||
---
|
||||
|
||||
## 🛠️ Schritt-für-Schritt Anleitung
|
||||
|
||||
### 1. Backup-Skript vorbereiten
|
||||
|
||||
Das Skript liegt bereits im Repo unter `config/scripts/backup.sh`.
|
||||
Du musst es auf Zora ausführbar machen und ggf. anpassen.
|
||||
|
||||
1. Verbinde dich mit Zora:
|
||||
```bash
|
||||
ssh user@zora-ip
|
||||
cd ~/meldestelle
|
||||
```
|
||||
|
||||
2. Mache das Skript ausführbar:
|
||||
```bash
|
||||
chmod +x config/scripts/backup.sh
|
||||
```
|
||||
|
||||
3. **WICHTIG:** Prüfe die Variablen im Skript (`nano config/scripts/backup.sh`):
|
||||
* `BACKUP_DIR`: Wohin sollen die Backups? (Standard: `/home/grandmo/backups/meldestelle`)
|
||||
* `DB_CONTAINER`: Name des Postgres-Containers (Standard: `meldestelle-postgres`).
|
||||
* `DB_USER`: Datenbank-User (Standard: `meldestelle`).
|
||||
|
||||
### 2. Cronjob einrichten (Automatische Ausführung)
|
||||
|
||||
Wir wollen das Backup jede Nacht um 03:00 Uhr laufen lassen.
|
||||
|
||||
1. Öffne die Crontab des Users:
|
||||
```bash
|
||||
crontab -e
|
||||
```
|
||||
|
||||
2. Füge folgende Zeile am Ende hinzu:
|
||||
```cron
|
||||
# Meldestelle Backup: Täglich um 03:00 Uhr
|
||||
0 3 * * * /home/grandmo/meldestelle/config/scripts/backup.sh >> /home/grandmo/meldestelle/logs/backup.log 2>&1
|
||||
```
|
||||
|
||||
3. Speichern und schließen (`Ctrl+O`, `Enter`, `Ctrl+X`).
|
||||
|
||||
### 3. Testen
|
||||
|
||||
Führe das Skript einmal manuell aus, um sicherzustellen, dass alles klappt:
|
||||
|
||||
```bash
|
||||
./config/scripts/backup.sh
|
||||
```
|
||||
|
||||
* Prüfe den Output: "✅ Backup abgeschlossen".
|
||||
* Prüfe das Backup-Verzeichnis: `ls -lh /home/grandmo/backups/meldestelle`.
|
||||
|
||||
---
|
||||
|
||||
## 🔄 Wiederherstellung (Restore)
|
||||
|
||||
Falls der Ernstfall eintritt (Datenbank korrupt oder gelöscht):
|
||||
|
||||
1. Stoppe die App-Container (aber lasse die DB laufen):
|
||||
```bash
|
||||
docker compose stop api-gateway ping-service keycloak
|
||||
```
|
||||
|
||||
2. Entpacke das Backup:
|
||||
```bash
|
||||
gunzip /home/grandmo/backups/meldestelle/db_dump_YYYY-MM-DD.sql.gz
|
||||
```
|
||||
|
||||
3. Spiele den Dump ein:
|
||||
```bash
|
||||
cat db_dump_YYYY-MM-DD.sql | docker exec -i meldestelle-postgres psql -U meldestelle
|
||||
```
|
||||
|
||||
4. Starte die App wieder:
|
||||
```bash
|
||||
docker compose up -d
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 💡 Tipps
|
||||
|
||||
* **Offsite-Backup:** Kopiere die Backups regelmäßig auf einen externen Speicher (z.B. NAS oder Cloud), falls die Festplatte von Zora ausfällt. `rsync` ist dein Freund!
|
||||
* **Monitoring:** Prüfe regelmäßig die Log-Datei `logs/backup.log`, ob Fehler auftreten.
|
||||
@@ -0,0 +1,129 @@
|
||||
---
|
||||
type: Guide
|
||||
status: ACTIVE
|
||||
owner: DevOps Engineer
|
||||
last_update: 2026-03-05
|
||||
tags: [deployment, git, zora, docker]
|
||||
---
|
||||
|
||||
# 🚀 Guide: Git-basiertes Deployment auf Zora einrichten
|
||||
|
||||
Dieser Guide beschreibt, wie du den Produktions-Server "Zora" so konfigurierst, dass er Updates direkt aus dem Gitea-Repository zieht. Dies stellt sicher, dass nicht nur die Docker-Images, sondern auch die `docker-compose.yaml` Konfigurationen immer synchron sind.
|
||||
|
||||
## 📋 Voraussetzungen
|
||||
|
||||
* SSH-Zugriff auf Zora (`ssh user@10.0.0.xx`).
|
||||
* `git` und `docker` sind auf Zora installiert.
|
||||
* Ein Gitea-Account mit Zugriff auf das `meldestelle` Repository.
|
||||
|
||||
---
|
||||
|
||||
## 🛠️ Schritt-für-Schritt Anleitung
|
||||
|
||||
### 1. Projektverzeichnis vorbereiten
|
||||
|
||||
Verbinde dich mit Zora und gehe in das Zielverzeichnis:
|
||||
|
||||
```bash
|
||||
ssh user@zora-ip
|
||||
cd ~/meldestelle
|
||||
```
|
||||
|
||||
**WICHTIG:** Falls dort bereits Konfigurationsdateien liegen, erstelle ein Backup:
|
||||
|
||||
```bash
|
||||
mkdir -p ../backup_meldestelle_$(date +%F)
|
||||
cp * ../backup_meldestelle_$(date +%F)/
|
||||
```
|
||||
|
||||
### 2. Git-Repository initialisieren
|
||||
|
||||
Wir verwandeln den Ordner in ein Git-Repo, das mit Gitea verknüpft ist.
|
||||
|
||||
```bash
|
||||
# Git initialisieren
|
||||
git init
|
||||
|
||||
# Remote Origin hinzufügen (HTTPS)
|
||||
git remote add origin https://git.mo-code.at/mocode-software/meldestelle.git
|
||||
|
||||
# Neueste Änderungen holen
|
||||
git fetch origin
|
||||
|
||||
# Hard Reset auf den main-Branch (ACHTUNG: Überschreibt lokale Änderungen!)
|
||||
git reset --hard origin/main
|
||||
```
|
||||
|
||||
*Jetzt sollten alle `dc-*.yaml` Dateien und Skripte im Ordner liegen.*
|
||||
|
||||
### 3. Environment-Variablen (.env) konfigurieren
|
||||
|
||||
Die `.env` Datei enthält Geheimnisse und wird **nicht** in Git gespeichert.
|
||||
|
||||
1. Kopiere die Vorlage:
|
||||
```bash
|
||||
cp .env.example .env
|
||||
```
|
||||
|
||||
2. Bearbeite die Datei:
|
||||
```bash
|
||||
nano .env
|
||||
```
|
||||
|
||||
3. **Wichtige Anpassungen für Production:**
|
||||
* `KC_HOSTNAME=auth.mo-code.at`
|
||||
* `KC_ISSUER_URI=https://auth.mo-code.at/realms/meldestelle`
|
||||
* `KC_JWK_SET_URI=http://keycloak:8080/realms/meldestelle/protocol/openid-connect/certs`
|
||||
* Setze starke Passwörter für Datenbank, Keycloak und Grafana!
|
||||
|
||||
### 4. Deployment-Skript einrichten
|
||||
|
||||
Das Skript `config/scripts/deploy.sh` liegt nun im Repo bereit (sobald wir es gepusht haben).
|
||||
Du kannst es direkt nutzen oder manuell anlegen:
|
||||
|
||||
**Inhalt von `deploy.sh`:**
|
||||
|
||||
```bash
|
||||
#!/bin/bash
|
||||
# deploy.sh - Update & Restart Meldestelle Stack
|
||||
|
||||
echo "🚀 Starte Deployment..."
|
||||
|
||||
# 1. Neueste Konfiguration holen
|
||||
echo " -> Git Pull..."
|
||||
git pull origin main
|
||||
|
||||
# 2. Neue Images laden
|
||||
echo " -> Docker Pull..."
|
||||
docker compose pull
|
||||
|
||||
# 3. Container neu starten (nur geänderte)
|
||||
echo " -> Docker Up..."
|
||||
docker compose up -d --remove-orphans
|
||||
|
||||
# 4. Aufräumen
|
||||
echo " -> Pruning old images..."
|
||||
docker image prune -f
|
||||
|
||||
echo "✅ Deployment erfolgreich!"
|
||||
```
|
||||
|
||||
Mache das Skript ausführbar:
|
||||
|
||||
```bash
|
||||
chmod +x config/scripts/deploy.sh
|
||||
# Optional: Symlink ins Root
|
||||
ln -s config/scripts/deploy.sh deploy.sh
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 🔄 Workflow für Updates
|
||||
|
||||
Wenn du Code oder Konfiguration gepusht hast und die CI-Pipeline durchgelaufen ist:
|
||||
|
||||
1. SSH auf Zora.
|
||||
2. `cd ~/meldestelle`
|
||||
3. `./deploy.sh`
|
||||
|
||||
Das System ist nun auf dem neuesten Stand!
|
||||
Reference in New Issue
Block a user