# Deployment-Strategie: Dev → Production

*Erstellt: 27. Dezember 2025*

## 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**
   ```bash
   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**
   ```bash
   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:
     ```bash
     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**
   ```bash
   ssh payload@162.55.85.18
   ```

2. **Deploy-Script ausführen**
   ```bash
   cd ~/payload-cms
   ./scripts/deploy-production.sh
   ```

3. **Optionen:**
   ```bash
   # 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
   ```

---

## Rollback-Strategie

### Automatischer Rollback (GitHub Actions)

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

### Manueller Rollback

```bash
# 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

```bash
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

```bash
# 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

```bash
# 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

```bash
# 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

```bash
# 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

```bash
# 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

```bash
# 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:**
   ```bash
   # 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*