cms.c2sgmbh/docs/DEPLOYMENT_STRATEGY.md

Deployment-Strategie: Dev → Production

Erstellt: 27. Dezember 2025 | Aktualisiert: 29. Dezember 2025

Siehe auch: STAGING-DEPLOYMENT.md für detaillierte Staging-Workflow-Dokumentation

Zusammenfassung

Diese Strategie gewährleistet fehlerfreie Deployments von der Development-Umgebung (sv-payload) zur Production-Umgebung (Hetzner 3) durch:

1. Automatisierte CI/CD Pipeline mit obligatorischen Tests
2. Staging-first-Ansatz - Änderungen müssen auf Staging erfolgreich sein
3. Pre-deployment Backup - Automatische Datenbank-Sicherung
4. Health Checks - Automatische Verifizierung nach Deployment
5. Rollback-Mechanismus - Schnelle Wiederherstellung bei Fehlern

---

Deployment-Workflow

┌─────────────────────────────────────────────────────────────────────────────┐
│                          DEPLOYMENT PIPELINE                                │
├─────────────────────────────────────────────────────────────────────────────┤
│                                                                             │
│   DEVELOPMENT          STAGING              PRODUCTION                      │
│   ─────────────       ─────────            ──────────                       │
│                                                                             │
│   ┌─────────┐    Push   ┌─────────────┐    Merge    ┌─────────────────┐    │
│   │  Code   │ ────────▶ │ CI Pipeline │ ──────────▶ │ Production CI   │    │
│   │ Changes │           │ (Automatic) │             │ (Manual Trigger)│    │
│   └─────────┘           └──────┬──────┘             └────────┬────────┘    │
│                                │                              │             │
│                                ▼                              ▼             │
│                         ┌─────────────┐              ┌───────────────┐     │
│                         │   Tests     │              │ Pre-flight    │     │
│                         │   Lint      │              │ Checks        │     │
│                         │   Build     │              └───────┬───────┘     │
│                         └──────┬──────┘                      │             │
│                                │                              ▼             │
│                                ▼                       ┌─────────────┐     │
│                         ┌─────────────┐                │ DB Backup   │     │
│                         │  Deploy to  │                └──────┬──────┘     │
│                         │  Staging    │                       │             │
│                         └──────┬──────┘                       ▼             │
│                                │                        ┌─────────────┐    │
│                                ▼                        │   Deploy    │    │
│                         ┌─────────────┐                 └──────┬──────┘    │
│                         │  Verify     │                        │            │
│                         │  Staging    │                        ▼            │
│                         └─────────────┘                 ┌─────────────┐    │
│                                                         │ Health Check│    │
│                                                         └──────┬──────┘    │
│                                                                │            │
│                                                         ┌──────┴──────┐    │
│                                                         │  Pass?      │    │
│                                                         └──────┬──────┘    │
│                                                           /         \       │
│                                                          /           \      │
│                                                    ┌────▼───┐   ┌────▼───┐ │
│                                                    │ SUCCESS│   │ROLLBACK│ │
│                                                    └────────┘   └────────┘ │
│                                                                             │
└─────────────────────────────────────────────────────────────────────────────┘

---

Umgebungen

Umgebung	Server	URL	Branch	Zweck
Development	sv-payload (LXC 700)	https://pl.porwoll.tech	develop	Entwicklung & Testing
Production	Hetzner 3	https://cms.c2sgmbh.de	main	Live-System

---

Schritt-für-Schritt Anleitung

Phase 1: Development & Testing (develop Branch)

1. Code-Änderungen auf develop pushen

   git checkout develop
   git add .
   git commit -m "feat: your feature"
   git push origin develop
   

2. Automatische CI Pipeline (optimiert für GitHub Actions Kostenkontrolle)

   • Bei Push auf develop:
     • ESLint & Prettier Check
     • TypeScript Compiler Check (optional)
     • Build Test
   • Bei Pull Request (volle Test-Suite):
     • Alle obigen Checks
     • Unit Tests
     • Integration Tests
     • E2E Tests

3. Automatisches Staging-Deployment

   • Bei erfolgreichem CI wird automatisch auf pl.porwoll.tech deployed
   • Health Check verifiziert erfolgreiche Deployment

4. Manuelle Verifizierung auf Staging

   • Admin Panel testen: https://pl.porwoll.tech/admin
   • Neue Features manuell prüfen
   • API-Endpoints testen

Phase 2: Production Deployment (main Branch)

Option A: Via GitHub Actions (Empfohlen)

1. develop in main mergen

   git checkout main
   git pull origin main
   git merge develop
   git push origin main
   

2. GitHub Actions Workflow starten

   • Gehe zu: Actions → "Deploy to Production" → "Run workflow"
   • Oder via CLI:

     gh workflow run deploy-production.yml
     

3. Optionen beim Start:

   • skip_tests: Tests überspringen (nicht empfohlen)
   • skip_backup: Backup überspringen (nicht empfohlen)
   • skip_migrations: Migrationen überspringen
   • deploy_tag: Spezifischer Git-Tag oder Commit

4. Workflow führt automatisch aus:

   • Pre-flight Checks
   • Pre-deployment Tests
   • Datenbank-Backup
   • Deployment
   • Health Check
   • Bei Fehler: Automatischer Rollback

Option B: Manuelles Deployment auf Server

1. SSH zum Production-Server

   ssh payload@162.55.85.18
   

2. Deploy-Script ausführen

   cd ~/payload-cms
   ./scripts/deploy-production.sh
   

3. Optionen:

   # Normales Deployment
   ./scripts/deploy-production.sh
   
   # Ohne Bestätigung (CI/Scripting)
   ./scripts/deploy-production.sh -y
   
   # Ohne Backup (nicht empfohlen)
   ./scripts/deploy-production.sh --skip-backup
   
   # Nur Service-Neustart
   ./scripts/deploy-production.sh --skip-build
   
   # Rollback zur vorherigen Version
   ./scripts/deploy-production.sh --rollback
   
   # Dry-Run (zeigt was passieren würde)
   ./scripts/deploy-production.sh --dry-run
   

---

Schema-Synchronisation

Problem: Schema-Drift

Wenn neue Collections oder Globals auf DEV hinzugefügt werden, muss die PROD-Datenbank entsprechend aktualisiert werden. Besonders die payload_locked_documents_rels Tabelle benötigt für jede Collection eine eigene *_id Spalte.

Automatische Synchronisation (im Deploy-Script)

Das Deploy-Script führt automatisch drizzle-kit push aus:

# Im deploy-production.sh:
pnpm payload migrate                    # Payload-Migrationen
pnpm exec drizzle-kit push --force     # Schema-Sync

Manuelle Schema-Synchronisation

# Auf dem Server:
cd ~/payload-cms

# Dry-Run (zeigt was sich ändern würde)
./scripts/sync-schema.sh --dry-run

# Schema synchronisieren
./scripts/sync-schema.sh

# Oder mit --force für CI/Automation
./scripts/sync-schema.sh --force

Best Practices

1. Nach Collection-Änderungen: pnpm payload migrate:create auf DEV ausführen
2. Migrations committen: git add src/migrations/
3. Schema-Datei prüfen: src/payload-generated-schema.ts sollte aktuell sein
4. Vor Deployment testen: ./scripts/sync-schema.sh --dry-run auf PROD

---

Rollback-Strategie

Automatischer Rollback (GitHub Actions)

• Bei fehlgeschlagenem Health Check nach Deployment
• Workflow rollt automatisch auf vorherige Version zurück

Manueller Rollback

# Auf dem Production-Server
ssh payload@162.55.85.18
cd ~/payload-cms

# Rollback zur vorherigen Version
./scripts/deploy-production.sh --rollback

Rollback zu spezifischem Commit

git log --oneline -10  # Zeige letzte Commits
git checkout main
git reset --hard <commit-sha>
pnpm install --frozen-lockfile
pnpm build
pm2 restart payload

Datenbank-Rollback

# Backup-Dateien anzeigen
ls -la ~/backups/pre-deploy/

# Backup wiederherstellen
gunzip -c ~/backups/pre-deploy/payload_db_YYYY-MM-DD_HH-MM-SS.sql.gz | \
  psql -h localhost -U payload -d payload_db

---

Pre-Deployment Checkliste

Vor jedem Production-Deployment

• Alle CI-Tests auf develop erfolgreich
• Staging-Deployment erfolgreich (pl.porwoll.tech)
• Neue Features auf Staging manuell getestet
• Keine offenen kritischen Bugs
• develop in main gemergt
• Bei DB-Änderungen: Migration auf Staging getestet

Kritische Änderungen (Extra Vorsicht)

• Schema-Migrationen
• Breaking API Changes
• Sicherheits-Updates
• Umgebungsvariablen-Änderungen

---

Post-Deployment Verifizierung

Automatische Checks

1. Health Check - HTTP-Status von /admin
2. PM2 Status - Prozesse laufen

Manuelle Checks

# PM2 Status
pm2 status

# Logs auf Fehler prüfen
pm2 logs payload --lines 50

# Admin Panel erreichbar?
curl -I https://cms.c2sgmbh.de/admin

# API funktioniert?
curl -I https://cms.c2sgmbh.de/api

# Redis verbunden?
redis-cli ping

---

Fehlerbehandlung

Build schlägt fehl

# Cache löschen
rm -rf .next
NODE_OPTIONS="--max-old-space-size=2048" pnpm build

# Bei Memory-Problemen: PM2 stoppen
pm2 stop all
NODE_OPTIONS="--max-old-space-size=3072" pnpm build
pm2 start ecosystem.config.cjs

Migration schlägt fehl

# Status prüfen
pnpm payload migrate:status

# Logs prüfen
pm2 logs payload --lines 100

# Bei Bedarf: Rollback
./scripts/deploy-production.sh --rollback

Service startet nicht

# Logs prüfen
pm2 logs payload --lines 100

# Prozess komplett neu starten
pm2 delete payload
pm2 start ecosystem.config.cjs --only payload

---

GitHub Secrets

Folgende Secrets müssen in GitHub konfiguriert sein:

Secret	Beschreibung	Verwendet in
STAGING_SSH_KEY	SSH Private Key für sv-payload	deploy-staging.yml
PRODUCTION_SSH_KEY	SSH Private Key für Hetzner 3	deploy-production.yml

SSH Key generieren

# Neuen Key generieren
ssh-keygen -t ed25519 -C "github-actions@deploy" -f deploy_key

# Public Key auf Server kopieren
ssh-copy-id -i deploy_key.pub payload@162.55.85.18

# Private Key in GitHub Secrets speichern
cat deploy_key | pbcopy  # (macOS) oder xclip

---

Monitoring nach Deployment

Erste 15 Minuten

1. PM2 Logs auf Fehler überwachen
2. Admin Panel regelmäßig aufrufen
3. API-Requests prüfen

Erste 24 Stunden

1. Umami Analytics prüfen
2. Error-Logs reviewen
3. User-Feedback sammeln

---

Best Practices

Do's

• Immer erst auf Staging testen
• Backups vor kritischen Änderungen
• Kleine, inkrementelle Deployments
• Dokumentation aktualisieren
• Rollback-Plan vorbereiten

Don'ts

• Nie direkt auf main entwickeln
• Nie ohne Tests deployen
• Nie große Schema-Änderungen ohne Backup
• Nie am Freitag Nachmittag deployen
• Nie mehrere kritische Änderungen gleichzeitig

---

Dateien

Datei	Beschreibung
.github/workflows/ci.yml	CI Pipeline (Tests, Build)
.github/workflows/security.yml	Security Scanning (Dependency Audit, ESLint)
.github/workflows/deploy-staging.yml	Automatisches Staging-Deployment
.github/workflows/deploy-production.yml	Production-Deployment (manuell)
scripts/deploy-staging.sh	Manuelles Staging-Deployment
scripts/deploy-production.sh	Manuelles Production-Deployment
ecosystem.config.cjs	PM2 Konfiguration

---

GitHub Actions Optimierung

Kostenmodell für Private Repos

Feature	Kostenlos	Kostenpflichtig
GitHub Actions	2.000 Min/Monat	darüber hinaus
CodeQL	Öffentliche Repos	Private Repos (GHAS ~$49/Monat)
Secret Scanning	Repo-Settings (Free)	GHAS für erweiterte Features
Dependabot	Ja	-

Optimierungen (27.12.2025)

CI-Workflow:

• Push auf develop: Nur Lint + Build (spart ~80% Actions-Minuten)
• Pull Requests: Volle Test-Suite inkl. E2E
• Push auf main: Keine CI (wird durch deploy-production getriggert)
• Markdown-Änderungen: Überspringen CI komplett

Security-Workflow:

• CodeQL entfernt (kostenpflichtig für private Repos)
• Ersetzt durch: ESLint + pnpm audit
• Nur bei PRs auf main und wöchentlich (nicht bei jedem Push)
• Secret Scanning: Native GitHub-Feature in Repo-Settings (kostenlos)

GitHub Actions Minutenverbrauch

Workflow	Trigger	Geschätzte Dauer	Häufigkeit
CI (Push)	Push develop	~3 Min	Pro Push
CI (PR)	Pull Request	~15 Min	Pro PR
Security	PR + Wöchentlich	~5 Min	1x/Woche + PRs
Deploy Staging	Push develop	~5 Min	Pro Push
Deploy Production	Manual	~8 Min	Bei Release

Geschätzte monatliche Nutzung:

• ~20 Pushes × 3 Min = 60 Min
• ~5 PRs × 15 Min = 75 Min
• ~4 Security Scans × 5 Min = 20 Min
• ~20 Staging Deploys × 5 Min = 100 Min
• Gesamt: ~255 Min/Monat (von 2.000 kostenlos)

Bei Billing-Problemen

1. Spending Limit prüfen: GitHub → Settings → Billing → Spending limits

2. Zahlungsmethode aktualisieren: GitHub → Settings → Billing → Payment method

3. Actions deaktivieren (temporär): Repository → Settings → Actions → Disable Actions

4. Manuelles Deployment:

   # Staging
   ssh payload@10.10.181.100
   cd ~/payload-cms && ./scripts/deploy-staging.sh
   
   # Production
   ssh payload@162.55.85.18
   cd ~/payload-cms && ./scripts/deploy-production.sh
   

---

Dokumentation: Complex Care Solutions GmbH | 27.12.2025