mirror of
https://github.com/complexcaresolutions/cms.c2sgmbh.git
synced 2026-03-17 16:14:12 +00:00
Martin Porwoll
9e433315e5
- Add drizzle.production.config.ts for schema synchronization - Add scripts/sync-schema.sh for manual schema sync - Update deploy-production.sh to run drizzle-kit push after migrations - Document schema sync workflow in DEPLOYMENT_STRATEGY.md - Update CLAUDE.md with schema sync commands This prevents schema drift between DEV and PROD by automatically syncing the database schema (especially payload_locked_documents_rels) during deployment. 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
491 lines
16 KiB
Markdown
491 lines
16 KiB
Markdown
# 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
|
||
```
|
||
|
||
---
|
||
|
||
## 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:
|
||
|
||
```bash
|
||
# Im deploy-production.sh:
|
||
pnpm payload migrate # Payload-Migrationen
|
||
pnpm exec drizzle-kit push --force # Schema-Sync
|
||
```
|
||
|
||
### Manuelle Schema-Synchronisation
|
||
|
||
```bash
|
||
# 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
|
||
|
||
```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*
|