mirror of
https://github.com/complexcaresolutions/documentation.git
synced 2026-03-17 15:13:54 +00:00
🚀 Deployment-Dokumentation (Guide, Staging, Strategie) mit echtem Inhalt
This commit is contained in:
parent
4cfa8a2949
commit
10651cc0f0
3 changed files with 432 additions and 8 deletions
|
|
@ -1,5 +1,170 @@
|
||||||
# Deployment-Dokumentation
|
# Deployment Guide - Payload CMS Multi-Tenant
|
||||||
|
|
||||||
> Siehe Projektdatei DEPLOYMENT.md für Details
|
*Letzte Aktualisierung: 17. Januar 2026*
|
||||||
|
|
||||||
Platzhalter - wird mit Inhalt aus dem Claude Project befüllt.
|
> **Wichtig:** Für die vollständige Deployment-Strategie siehe [DEPLOYMENT_STRATEGY.md](./DEPLOYMENT_STRATEGY.md)
|
||||||
|
|
||||||
|
## Übersicht
|
||||||
|
|
||||||
|
```
|
||||||
|
┌─────────────────┐ ┌─────────────────┐ ┌─────────────────┐
|
||||||
|
│ DEVELOPMENT │ │ STAGING │ │ PRODUCTION │
|
||||||
|
│ sv-frontend │───▶│ sv-payload │───▶│ Hetzner 3 │
|
||||||
|
│ Local Dev │ │ pl.porwoll.tech│ │ cms.c2sgmbh.de │
|
||||||
|
│ develop branch │ │ develop branch │ │ main branch │
|
||||||
|
└─────────────────┘ └─────────────────┘ └─────────────────┘
|
||||||
|
```
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## 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 |
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## Git Branching Workflow
|
||||||
|
|
||||||
|
**Regel:** Immer auf `develop` entwickeln, nach Freigabe mit `main` mergen.
|
||||||
|
|
||||||
|
```bash
|
||||||
|
# 1. Auf develop entwickeln
|
||||||
|
git checkout develop
|
||||||
|
git pull origin develop
|
||||||
|
git add . && git commit -m "feat: neue Funktion"
|
||||||
|
git push origin develop
|
||||||
|
# → Automatisches Deployment auf Staging
|
||||||
|
|
||||||
|
# 2. Nach Test: Merge in main
|
||||||
|
git checkout main && git merge develop && git push origin main
|
||||||
|
# → Manuelles Deployment auf Production
|
||||||
|
```
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## Staging Deployment (develop → pl.porwoll.tech)
|
||||||
|
|
||||||
|
### Automatisch via GitHub Actions
|
||||||
|
|
||||||
|
Bei jedem Push auf `develop` wird automatisch deployed:
|
||||||
|
|
||||||
|
1. Pre-deployment Checks (Lint, Tests)
|
||||||
|
2. SSH-Verbindung zu sv-payload
|
||||||
|
3. `git pull origin develop`
|
||||||
|
4. `pnpm install`
|
||||||
|
5. `pnpm payload migrate`
|
||||||
|
6. `pnpm build`
|
||||||
|
7. `pm2 restart payload`
|
||||||
|
8. Health Check
|
||||||
|
|
||||||
|
### Manuell auf sv-payload
|
||||||
|
|
||||||
|
```bash
|
||||||
|
ssh payload@10.10.181.100
|
||||||
|
cd /home/payload/payload-cms
|
||||||
|
git pull origin develop
|
||||||
|
pnpm install
|
||||||
|
pnpm payload migrate
|
||||||
|
pnpm build
|
||||||
|
pm2 restart payload
|
||||||
|
pm2 logs payload --lines 20
|
||||||
|
```
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## Production Deployment (main → cms.c2sgmbh.de)
|
||||||
|
|
||||||
|
### Option A: Via GitHub Actions (Empfohlen)
|
||||||
|
|
||||||
|
```bash
|
||||||
|
git checkout main && git merge develop && git push origin main
|
||||||
|
gh workflow run deploy-production.yml
|
||||||
|
```
|
||||||
|
|
||||||
|
Der Workflow führt automatisch aus: Pre-flight Checks, Tests, Datenbank-Backup, Deployment, Health Check, bei Fehler automatischer Rollback.
|
||||||
|
|
||||||
|
### Option B: Via Deploy-Script auf Server
|
||||||
|
|
||||||
|
```bash
|
||||||
|
ssh payload@162.55.85.18
|
||||||
|
cd ~/payload-cms
|
||||||
|
./scripts/deploy-production.sh
|
||||||
|
|
||||||
|
# Optionen:
|
||||||
|
./scripts/deploy-production.sh -y # Ohne Bestätigung
|
||||||
|
./scripts/deploy-production.sh --skip-backup # Ohne Backup
|
||||||
|
./scripts/deploy-production.sh --rollback # Rollback
|
||||||
|
./scripts/deploy-production.sh --dry-run # Dry-Run
|
||||||
|
```
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## Rollback
|
||||||
|
|
||||||
|
```bash
|
||||||
|
# Automatischer Rollback
|
||||||
|
./scripts/deploy-production.sh --rollback
|
||||||
|
|
||||||
|
# Manuell zu Commit
|
||||||
|
git log --oneline -10
|
||||||
|
git reset --hard <commit-sha>
|
||||||
|
pnpm install && pnpm build
|
||||||
|
pm2 restart payload
|
||||||
|
```
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## CI/CD Pipeline
|
||||||
|
|
||||||
|
| Workflow | Trigger | Aktion |
|
||||||
|
|----------|---------|--------|
|
||||||
|
| `ci.yml` | Push/PR auf main, develop | Lint, Test, Build |
|
||||||
|
| `security.yml` | Push/PR, Schedule | Security Scanning |
|
||||||
|
| `deploy-staging.yml` | Push auf develop | Auto-Deploy zu Staging |
|
||||||
|
| `deploy-production.yml` | Manuell | Production Deployment |
|
||||||
|
|
||||||
|
### GitHub Secrets
|
||||||
|
|
||||||
|
| Secret | Beschreibung |
|
||||||
|
|--------|-------------|
|
||||||
|
| `STAGING_SSH_KEY` | SSH Private Key für sv-payload |
|
||||||
|
| `PRODUCTION_SSH_KEY` | SSH Private Key für Hetzner 3 |
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## Umgebungsvariablen
|
||||||
|
|
||||||
|
### Production (.env)
|
||||||
|
|
||||||
|
```env
|
||||||
|
DATABASE_URI=postgresql://payload:***@localhost:5432/payload_db
|
||||||
|
PAYLOAD_PUBLIC_SERVER_URL=https://cms.c2sgmbh.de
|
||||||
|
NODE_ENV=production
|
||||||
|
PORT=3001
|
||||||
|
REDIS_URL=redis://localhost:6379
|
||||||
|
```
|
||||||
|
|
||||||
|
### Staging (.env)
|
||||||
|
|
||||||
|
```env
|
||||||
|
DATABASE_URI=postgresql://payload:***@127.0.0.1:6432/payload_db
|
||||||
|
PAYLOAD_PUBLIC_SERVER_URL=https://pl.porwoll.tech
|
||||||
|
NODE_ENV=production
|
||||||
|
PORT=3000
|
||||||
|
REDIS_URL=redis://localhost:6379
|
||||||
|
```
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## Health Check
|
||||||
|
|
||||||
|
```bash
|
||||||
|
pm2 status
|
||||||
|
pm2 logs payload --lines 50
|
||||||
|
curl -I https://cms.c2sgmbh.de/api/users
|
||||||
|
curl -I https://cms.c2sgmbh.de/admin
|
||||||
|
redis-cli ping
|
||||||
|
```
|
||||||
|
|
|
||||||
|
|
@ -1,5 +1,150 @@
|
||||||
# Deployment-Strategie
|
# Deployment-Strategie: Dev → Production
|
||||||
|
|
||||||
> Siehe Projektdatei DEPLOYMENT_STRATEGY.md für Details
|
*Erstellt: 27. Dezember 2025 | Aktualisiert: 29. Dezember 2025*
|
||||||
|
|
||||||
Platzhalter - wird mit Inhalt aus dem Claude Project befüllt.
|
## Zusammenfassung
|
||||||
|
|
||||||
|
Diese Strategie gewährleistet fehlerfreie Deployments 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
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## 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 |
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## Phase 1: Development & Testing (develop)
|
||||||
|
|
||||||
|
```bash
|
||||||
|
git checkout develop
|
||||||
|
git add . && git commit -m "feat: your feature"
|
||||||
|
git push origin develop
|
||||||
|
```
|
||||||
|
|
||||||
|
- **Push auf develop:** ESLint, Build Test, Auto-Deploy zu Staging
|
||||||
|
- **Pull Request:** Volle Test-Suite inkl. E2E
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## Phase 2: Production Deployment (main)
|
||||||
|
|
||||||
|
### Via GitHub Actions (Empfohlen)
|
||||||
|
|
||||||
|
```bash
|
||||||
|
git checkout main && git merge develop && git push origin main
|
||||||
|
gh workflow run deploy-production.yml
|
||||||
|
```
|
||||||
|
|
||||||
|
Optionen: `skip_tests`, `skip_backup`, `skip_migrations`, `deploy_tag`
|
||||||
|
|
||||||
|
### Via Deploy-Script
|
||||||
|
|
||||||
|
```bash
|
||||||
|
ssh payload@162.55.85.18
|
||||||
|
cd ~/payload-cms
|
||||||
|
./scripts/deploy-production.sh
|
||||||
|
./scripts/deploy-production.sh --rollback # Rollback
|
||||||
|
./scripts/deploy-production.sh --dry-run # Dry-Run
|
||||||
|
```
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## Schema-Synchronisation
|
||||||
|
|
||||||
|
```bash
|
||||||
|
pnpm payload migrate # Payload-Migrationen
|
||||||
|
pnpm exec drizzle-kit push --force # Schema-Sync
|
||||||
|
```
|
||||||
|
|
||||||
|
### Best Practices
|
||||||
|
|
||||||
|
1. Nach Collection-Änderungen: `pnpm payload migrate:create` auf DEV
|
||||||
|
2. Migrations committen: `git add src/migrations/`
|
||||||
|
3. Vor Deployment testen: `./scripts/sync-schema.sh --dry-run`
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## Rollback-Strategie
|
||||||
|
|
||||||
|
```bash
|
||||||
|
# Automatischer Rollback
|
||||||
|
./scripts/deploy-production.sh --rollback
|
||||||
|
|
||||||
|
# Zu spezifischem Commit
|
||||||
|
git log --oneline -10
|
||||||
|
git reset --hard <commit-sha>
|
||||||
|
pnpm install --frozen-lockfile && pnpm build
|
||||||
|
pm2 restart payload
|
||||||
|
|
||||||
|
# Datenbank-Rollback
|
||||||
|
gunzip -c ~/backups/pre-deploy/payload_db_*.sql.gz | psql -U payload -d payload_db
|
||||||
|
```
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## Pre-Deployment Checkliste
|
||||||
|
|
||||||
|
- [ ] CI-Tests auf develop erfolgreich
|
||||||
|
- [ ] Staging-Deployment erfolgreich
|
||||||
|
- [ ] Features auf Staging manuell getestet
|
||||||
|
- [ ] Keine offenen kritischen Bugs
|
||||||
|
- [ ] develop in main gemergt
|
||||||
|
- [ ] Bei DB-Änderungen: Migration auf Staging getestet
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## GitHub Actions Workflows
|
||||||
|
|
||||||
|
| Workflow | Trigger | Geschätzte Dauer |
|
||||||
|
|----------|---------|------------------|
|
||||||
|
| CI (Push) | Push develop | ~3 Min |
|
||||||
|
| CI (PR) | Pull Request | ~15 Min |
|
||||||
|
| Security | PR + Wöchentlich | ~5 Min |
|
||||||
|
| Deploy Staging | Push develop | ~5 Min |
|
||||||
|
| Deploy Production | Manual | ~8 Min |
|
||||||
|
|
||||||
|
**Geschätzte monatliche Nutzung:** ~255 Min (von 2.000 kostenlos)
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## Dateien
|
||||||
|
|
||||||
|
| Datei | Beschreibung |
|
||||||
|
|-------|-------------|
|
||||||
|
| `.github/workflows/ci.yml` | CI Pipeline |
|
||||||
|
| `.github/workflows/security.yml` | Security Scanning |
|
||||||
|
| `.github/workflows/deploy-staging.yml` | Staging-Deployment |
|
||||||
|
| `.github/workflows/deploy-production.yml` | Production-Deployment |
|
||||||
|
| `scripts/deploy-staging.sh` | Manuelles Staging-Script |
|
||||||
|
| `scripts/deploy-production.sh` | Manuelles Production-Script |
|
||||||
|
| `ecosystem.config.cjs` | PM2 Konfiguration |
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## Best Practices
|
||||||
|
|
||||||
|
### Do's
|
||||||
|
- Immer erst auf Staging testen
|
||||||
|
- Backups vor kritischen Änderungen
|
||||||
|
- Kleine, inkrementelle Deployments
|
||||||
|
- 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
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
*Dokumentation: Complex Care Solutions GmbH | 27.12.2025*
|
||||||
|
|
|
||||||
|
|
@ -1,5 +1,119 @@
|
||||||
# Staging Deployment
|
# Staging Deployment
|
||||||
|
|
||||||
> Siehe Projektdatei STAGING-DEPLOYMENT.md für Details
|
> **Staging URL:** https://pl.porwoll.tech
|
||||||
|
> **Server:** sv-payload (37.24.237.181)
|
||||||
|
> **Branch:** `develop`
|
||||||
|
|
||||||
Platzhalter - wird mit Inhalt aus dem Claude Project befüllt.
|
> **Siehe auch:** [DEPLOYMENT_STRATEGY.md](./DEPLOYMENT_STRATEGY.md) für die vollständige Deployment-Strategie
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## Trigger
|
||||||
|
|
||||||
|
| Trigger | Beschreibung |
|
||||||
|
|---------|-------------|
|
||||||
|
| **Push auf `develop`** | Automatisches Deployment |
|
||||||
|
| **workflow_dispatch** | Manuelles Deployment via GitHub UI |
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## Workflow-Ablauf
|
||||||
|
|
||||||
|
### 1. Pre-deployment Checks (~1 Min)
|
||||||
|
|
||||||
|
- ESLint prüfen
|
||||||
|
- Unit Tests ausführen
|
||||||
|
- Bei Fehler: Deployment wird abgebrochen
|
||||||
|
|
||||||
|
### 2. Deploy to Staging (~2-3 Min)
|
||||||
|
|
||||||
|
1. SSH-Verbindung zum Server
|
||||||
|
2. `git fetch origin develop && git reset --hard origin/develop`
|
||||||
|
3. `pnpm install --frozen-lockfile`
|
||||||
|
4. `pnpm payload migrate`
|
||||||
|
5. `pnpm build` (mit Memory-Limit 2GB)
|
||||||
|
6. `pm2 restart payload queue-worker`
|
||||||
|
7. Health Check auf `http://localhost:3000/admin`
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## Manuelles Deployment
|
||||||
|
|
||||||
|
### Via GitHub UI
|
||||||
|
|
||||||
|
1. Gehe zu: https://github.com/c2s-admin/cms.c2sgmbh/actions
|
||||||
|
2. Wähle "Deploy to Staging"
|
||||||
|
3. Klicke "Run workflow"
|
||||||
|
4. Optional: "Skip tests" aktivieren
|
||||||
|
|
||||||
|
### Via CLI (auf dem Server)
|
||||||
|
|
||||||
|
```bash
|
||||||
|
./scripts/deploy-staging.sh
|
||||||
|
./scripts/deploy-staging.sh --skip-build
|
||||||
|
./scripts/deploy-staging.sh --skip-migrations
|
||||||
|
DEPLOY_BRANCH=feature/xyz ./scripts/deploy-staging.sh
|
||||||
|
```
|
||||||
|
|
||||||
|
### Via SSH (Remote)
|
||||||
|
|
||||||
|
```bash
|
||||||
|
ssh payload@37.24.237.181 'cd ~/payload-cms && ./scripts/deploy-staging.sh'
|
||||||
|
```
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## Konfiguration
|
||||||
|
|
||||||
|
### GitHub Secrets
|
||||||
|
|
||||||
|
| Secret | Beschreibung |
|
||||||
|
|--------|-------------|
|
||||||
|
| `STAGING_SSH_KEY` | SSH Private Key für `payload@37.24.237.181` |
|
||||||
|
|
||||||
|
### Environment
|
||||||
|
|
||||||
|
| Variable | Wert |
|
||||||
|
|----------|------|
|
||||||
|
| `STAGING_HOST` | 37.24.237.181 |
|
||||||
|
| `STAGING_USER` | payload |
|
||||||
|
| `STAGING_PATH` | /home/payload/payload-cms |
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## Troubleshooting
|
||||||
|
|
||||||
|
### Build schlägt fehl (OOM)
|
||||||
|
|
||||||
|
```bash
|
||||||
|
pm2 stop all
|
||||||
|
NODE_OPTIONS="--max-old-space-size=1536" pnpm build
|
||||||
|
pm2 start ecosystem.config.cjs
|
||||||
|
```
|
||||||
|
|
||||||
|
### SSH-Verbindung fehlgeschlagen
|
||||||
|
|
||||||
|
1. `STAGING_SSH_KEY` Secret prüfen
|
||||||
|
2. Public Key in `~/.ssh/authorized_keys` prüfen
|
||||||
|
3. Server erreichbar: `ping 37.24.237.181`
|
||||||
|
|
||||||
|
### Service startet nicht
|
||||||
|
|
||||||
|
```bash
|
||||||
|
pm2 status
|
||||||
|
pm2 logs payload --err --lines 100
|
||||||
|
pm2 start ecosystem.config.cjs
|
||||||
|
```
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## Branching-Strategie
|
||||||
|
|
||||||
|
| Branch | Deployment | URL |
|
||||||
|
|--------|------------|-----|
|
||||||
|
| `main` | Produktion (manuell) | cms.c2sgmbh.de |
|
||||||
|
| `develop` | Staging (automatisch) | pl.porwoll.tech |
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
*Letzte Aktualisierung: 29.12.2025*
|
||||||
|
|
|
||||||
Loading…
Reference in a new issue