# Staging Deployment

> **Staging URL:** https://pl.c2sgmbh.de
> **Server:** sv-payload (37.24.237.181)
> **Branch:** `develop`

---

## Übersicht

```
┌─────────────────────────────────────────────────────────────────────────────┐
│                        STAGING DEPLOYMENT WORKFLOW                          │
│                                                                             │
│  ┌──────────────┐     ┌──────────────┐     ┌──────────────────────────────┐│
│  │   Developer  │     │    GitHub    │     │      Staging Server          ││
│  │              │     │   Actions    │     │    pl.c2sgmbh.de             ││
│  └──────┬───────┘     └──────┬───────┘     └──────────────┬───────────────┘│
│         │                    │                            │                 │
│         │  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)

```yaml
Jobs: pre-checks
```

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

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

```yaml
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.c2sgmbh.de/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)

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

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

---

## Dateien

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

---

## Logs & Debugging

### GitHub Actions Logs

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

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

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

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

### Service startet nicht

```bash
# 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.c2sgmbh.de |

---

## Workflow-Status prüfen

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