cms.c2sgmbh/docs/STAGING-DEPLOYMENT.md

Staging Deployment

Staging URL: https://pl.porwoll.tech Server: sv-payload (37.24.237.181) Branch: develop

Siehe auch: DEPLOYMENT_STRATEGY.md für die vollständige Deployment-Strategie (Dev → Prod)

---

Übersicht

┌─────────────────────────────────────────────────────────────────────────────┐
│                        STAGING DEPLOYMENT WORKFLOW                          │
│                                                                             │
│  ┌──────────────┐     ┌──────────────┐     ┌──────────────────────────────┐│
│  │   Developer  │     │    GitHub    │     │      Staging Server          ││
│  │              │     │   Actions    │     │    pl.porwoll.tech             ││
│  └──────┬───────┘     └──────┬───────┘     └──────────────┬───────────────┘│
│         │                    │                            │                 │
│         │  git push          │                            │                 │
│         │  develop           │                            │                 │
│         ├───────────────────►│                            │                 │
│         │                    │                            │                 │
│         │                    │  1. Lint Check             │                 │
│         │                    │  2. Unit Tests             │                 │
│         │                    │     ↓                      │                 │
│         │                    │  [Pre-checks OK?]          │                 │
│         │                    │     ↓                      │                 │
│         │                    │  3. SSH Connect ──────────►│                 │
│         │                    │                            │  4. git pull    │
│         │                    │                            │  5. pnpm install│
│         │                    │                            │  6. migrate     │
│         │                    │                            │  7. build       │
│         │                    │                            │  8. pm2 restart │
│         │                    │                            │     ↓           │
│         │                    │◄─────────────────────────  │  9. Health Check│
│         │                    │                            │                 │
│         │  ✅ Success        │                            │                 │
│         │◄───────────────────│                            │                 │
│                                                                             │
└─────────────────────────────────────────────────────────────────────────────┘

---

Trigger

Trigger	Beschreibung
Push auf develop	Automatisches Deployment
workflow_dispatch	Manuelles Deployment via GitHub UI

---

Workflow-Ablauf

1. Pre-deployment Checks (~1 Min)

Jobs: pre-checks

• ESLint prüfen
• Unit Tests ausführen
• Bei Fehler: Deployment wird abgebrochen

2. Deploy to Staging (~2-3 Min)

Jobs: deploy

1. SSH-Verbindung zum Server herstellen
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

3. Verify Deployment

• HTTP-Status von https://pl.porwoll.tech/admin prüfen
• Bei Fehler: Benachrichtigung im Workflow-Summary

---

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 für schnelleres Deployment

Via CLI (auf dem Server)

# Vollständiges Deployment
./scripts/deploy-staging.sh

# Nur Code-Update (ohne Build)
./scripts/deploy-staging.sh --skip-build

# Ohne Migrationen
./scripts/deploy-staging.sh --skip-migrations

# Anderer Branch
DEPLOY_BRANCH=feature/xyz ./scripts/deploy-staging.sh

Via SSH (Remote)

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

---

Dateien

Datei	Beschreibung
.github/workflows/deploy-staging.yml	GitHub Actions Workflow
scripts/deploy-staging.sh	Manuelles Deploy-Script

---

Logs & Debugging

GitHub Actions Logs

# Letzte Workflow-Runs anzeigen
gh run list --workflow=deploy-staging.yml

# Details eines Runs
gh run view <run-id>

# Logs eines Jobs
gh run view <run-id> --job=<job-id> --log

Server Logs

# Deployment Log
tail -f /home/payload/logs/deploy-staging.log

# PM2 Logs
pm2 logs payload --lines 50
pm2 logs queue-worker --lines 50

---

Troubleshooting

Build schlägt fehl (OOM)

# PM2 stoppen um RAM freizugeben
pm2 stop all

# Build mit reduziertem Memory
NODE_OPTIONS="--max-old-space-size=1536" pnpm build

# Services wieder starten
pm2 start ecosystem.config.cjs

SSH-Verbindung fehlgeschlagen

1. Prüfen ob STAGING_SSH_KEY Secret korrekt ist
2. Prüfen ob Public Key in ~/.ssh/authorized_keys auf dem Server ist
3. Prüfen ob Server erreichbar ist: ping 37.24.237.181

Migrations fehlgeschlagen

# Direkt auf dem Server
cd /home/payload/payload-cms
pnpm payload migrate:status
pnpm payload migrate

Service startet nicht

# PM2 Status prüfen
pm2 status

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

# Manuell starten
pm2 start ecosystem.config.cjs

---

Branching-Strategie

main (Produktion)
  │
  └── develop (Staging) ◄── Feature-Branches
        │
        ├── feature/xyz
        ├── fix/abc
        └── ...

Branch	Deployment	URL
main	Produktion (manuell)	cms.c2sgmbh.de
develop	Staging (automatisch)	pl.porwoll.tech

---

Workflow-Status prüfen

# CLI
gh run list --workflow=deploy-staging.yml --limit=5

# Oder im Browser
# https://github.com/c2s-admin/cms.c2sgmbh/actions/workflows/deploy-staging.yml

---

Letzte Aktualisierung: 29.12.2025