Zum Inhalt

Deployment

Es gibt drei Umgebungen; die vollständigen Befehle stehen in RUNBOOK.md im Repository-Root. Diese Seite fasst die Grundzüge zusammen.

Dev Test Prod
Wo dieser Server dieser Server (separates Compose-Projekt) eigener Server
Domain hocx.tweber.ch test.hocx.tweber.ch hocx.ch
Code-Quelle lokal, build: aus Source Docker-Image von GHCR Docker-Image von GHCR

Ablauf für ein Release

  1. Änderungen werden auf main gemerged.
  2. Auf GitHub ein Release mit Semver-Tag erstellen (z. B. v1.2.0).
  3. .github/workflows/release.yml baut automatisch die Images (hocx-backend, hocx-frontend, hocx-abgabebox-backend, hocx-abgabebox-frontend) und pusht sie nach GHCR.
  4. In hocX-test/.env HOCX_VERSION setzen, ./scripts/deploy.sh test ausführen. Das Skript macht automatisch: DB-Backup → Images pullen → Neustart (Alembic migriert automatisch) → Health-Check.
  5. Nach erfolgreicher Verifikation auf Test dieselben Schritte auf dem Prod-Server wiederholen.

Wichtige Betriebsregeln

DNS vor Stack-Start setzen

Traefik holt beim ersten Start sofort ein Let's-Encrypt-Zertifikat. Zeigt die Domain noch nicht auf den Server, zählt ein Fehlversuch gegen Let's Encrypts Rate-Limit (5 Fehlversuche/Domain/Stunde). Bei einer neuen Domain daher immer erst den DNS-Eintrag setzen, dann den Stack starten.

Riskante Schema-Änderungen über zwei Releases

Spalten umbenennen/löschen oder Typen ändern immer in zwei Schritten ausrollen (Release A: neue Spalte hinzufügen + befüllen, Release B: alte Spalte entfernen). So bleibt jeder Schritt rückwärtskompatibel und ein Rollback ohne Backup-Restore möglich.

Dev-Container laden Code nicht automatisch nach

Backend läuft mit --workers 2 (kein --reload), Frontend mit npm run build && npm start (kein Dev-Server) – nach Code-Änderungen im Dev-Betrieb muss der jeweilige Container neu gestartet werden (docker compose restart backend/frontend).

Rollback

HOCX_VERSION in .env auf die vorherige Version setzen und erneut deployen. Bei destruktiven Schema-Änderungen (Spalte gelöscht/Typ geändert) reicht ein Code-Rollback nicht – zusätzlich muss das vor dem Update gezogene Backup eingespielt werden.