michaelschiemer/DEPLOYMENT_PLAN.md

# Production Deployment Plan

**Projekt**: Custom PHP Framework
**Datum**: 2025-01-15
**Ziel**: Erstes Production Deployment

---

## Status Check

### Git Status
- ✅ 18 Commits ahead of remote
- ⚠️ Viele unstaged changes
- ⚠️ Neue Deployment-Dokumentation noch nicht committed

### Code Status
- ✅ Health Check System implementiert
- ✅ Metrics Endpoint implementiert
- ✅ Production Logging konfiguriert
- ✅ Deployment-Dokumentation vollständig

---

## Vor dem Deployment

### 1. Code vorbereiten (15 Minuten)

```bash
# Alle Änderungen committen
git add .
git commit -m "feat(Production): Complete production deployment infrastructure

- Add comprehensive health check system with multiple endpoints
- Add Prometheus metrics endpoint
- Add production logging configurations
- Add complete deployment documentation (Quick Start, Workflow, Ansible, Checklists)
- Add deployment scripts and automation
- Update README with deployment links

All production infrastructure is now complete and ready for deployment."

# Zu Remote pushen
git push origin main
```

### 2. Lokale Tests (10 Minuten)

```bash
# Tests ausführen
./vendor/bin/pest

# Code Style Check
composer cs

# PHPStan
./vendor/bin/phpstan analyse

# Health Checks lokal testen
curl http://localhost/health/summary
curl http://localhost/health/detailed
```

### 3. Server-Informationen sammeln (5 Minuten)

**Benötigte Informationen**:
- [ ] Server IP-Adresse: _________________
- [ ] Domain Name: _________________
- [ ] SSH Username: _________________
- [ ] SSH Key vorhanden: [ ] Ja [ ] Nein

**Prüfen ob Server Anforderungen erfüllt**:
- [ ] Ubuntu 22.04+ oder Debian 11+
- [ ] Root oder sudo Zugriff
- [ ] Mindestens 4GB RAM
- [ ] Mindestens 40GB Festplatte
- [ ] Ports 22, 80, 443 offen

---

## Deployment Optionen

### Option A: Quick Start (Empfohlen für erstes Deployment)
**Zeit**: 30 Minuten
**Dokumentation**: [docs/deployment/QUICKSTART.md](docs/deployment/QUICKSTART.md)

**Schritte**:
1. SSH zum Server
2. System updates
3. Docker installieren
4. SSL Zertifikat mit Let's Encrypt
5. Repository klonen
6. Secrets generieren
7. Environment konfigurieren
8. Container starten
9. Health checks verifizieren
10. Nginx konfigurieren

**Vorteile**:
- Schnellster Weg zu laufendem System
- Minimal konfiguration
- Sofortige Verifikation

**Starten**:
```bash
# Dokumentation öffnen
cat docs/deployment/QUICKSTART.md

# Oder online auf GitHub
```

### Option B: Kompletter Workflow (Für Produktions-Setup)
**Zeit**: 2 Stunden
**Dokumentation**: [docs/deployment/DEPLOYMENT_WORKFLOW.md](docs/deployment/DEPLOYMENT_WORKFLOW.md)

**Schritte**:
- Phase 1: Initial Server Setup (einmalig)
- Phase 2: Initial Deployment
- Phase 3: Ongoing Deployment Setup
- Phase 4: Monitoring Setup

**Vorteile**:
- Vollständige Produktions-Konfiguration
- Monitoring und Alerting
- Automatisierte Deployment-Scripts
- Backup-Strategien

**Starten**:
```bash
cat docs/deployment/DEPLOYMENT_WORKFLOW.md
```

### Option C: Ansible (Für Multiple Server)
**Zeit**: 4 Stunden initial, 5 Minuten ongoing
**Dokumentation**: [docs/deployment/ANSIBLE_DEPLOYMENT.md](docs/deployment/ANSIBLE_DEPLOYMENT.md)

**Nur verwenden wenn**:
- Multiple Server (Staging + Production)
- Team Collaboration
- Infrastructure as Code gewünscht

---

## Empfohlener Ablauf für dich

Basierend auf deinem Setup empfehle ich **Option A: Quick Start** für das erste Deployment.

### Schritt 1: Code vorbereiten

```bash
# Im Projekt-Verzeichnis
cd /home/michael/dev/michaelschiemer

# Alle Änderungen committen
git add .
git commit -m "feat(Production): Complete production deployment infrastructure"
git push origin main
```

### Schritt 2: Server vorbereiten

```bash
# SSH zum Server
ssh user@your-server.com

# System aktualisieren
sudo apt update && sudo apt upgrade -y

# Docker installieren
curl -fsSL https://get.docker.com -o get-docker.sh
sudo sh get-docker.sh

# Docker Compose installieren
sudo apt install docker-compose-plugin -y

# Certbot installieren
sudo apt install certbot -y

# Application User erstellen
sudo useradd -m -s /bin/bash appuser
sudo usermod -aG docker appuser
```

### Schritt 3: SSL Zertifikat

```bash
# Webroot erstellen
sudo mkdir -p /var/www/certbot

# Zertifikat holen (ersetze yourdomain.com)
sudo certbot certonly --webroot \
    -w /var/www/certbot \
    -d yourdomain.com \
    --email your-email@example.com \
    --agree-tos \
    --non-interactive

# Zertifikate prüfen
ls -la /etc/letsencrypt/live/yourdomain.com/
```

### Schritt 4: Application klonen

```bash
# Als appuser
sudo su - appuser

# Repository klonen
git clone https://github.com/your-org/your-repo.git /home/appuser/app
cd /home/appuser/app

# Production Branch
git checkout main
```

### Schritt 5: Secrets generieren

```bash
# Vault Key generieren
php scripts/deployment/generate-vault-key.php

# WICHTIG: Output sicher speichern!
# Beispiel: vault_key_abc123def456...
```

### Schritt 6: Environment konfigurieren

```bash
# .env.production erstellen
cp .env.example .env.production
nano .env.production
```

**Minimal Configuration**:
```env
APP_ENV=production
APP_DEBUG=false
APP_URL=https://yourdomain.com

DB_HOST=database
DB_PORT=3306
DB_NAME=app_production
DB_USER=app_user
DB_PASS=<GENERATED_PASSWORD>

VAULT_ENCRYPTION_KEY=<YOUR_KEY_FROM_STEP_5>

LOG_PATH=/var/log/app
LOG_LEVEL=INFO

ADMIN_ALLOWED_IPS=<YOUR_IP>,127.0.0.1
```

**Passwords generieren**:
```bash
# DB Password
openssl rand -base64 32

# JWT Secret
openssl rand -base64 64
```

### Schritt 7: Build und Start

```bash
# Dependencies installieren
docker compose -f docker-compose.production.yml run --rm php composer install --no-dev --optimize-autoloader

# Container bauen
docker compose -f docker-compose.production.yml build

# Container starten
docker compose -f docker-compose.production.yml up -d

# Status prüfen
docker compose -f docker-compose.production.yml ps
```

### Schritt 8: Database initialisieren

```bash
# Migrations ausführen
docker compose -f docker-compose.production.yml exec php php console.php db:migrate

# Status prüfen
docker compose -f docker-compose.production.yml exec php php console.php db:status
```

### Schritt 9: Health Checks

```bash
# Health endpoint prüfen
curl http://localhost/health/summary

# Erwartete Ausgabe:
# {
#   "overall_healthy": true,
#   "summary": {
#     "total_checks": 8,
#     "healthy": 8
#   }
# }

# Bei Problemen: Logs prüfen
docker compose -f docker-compose.production.yml logs php
```

### Schritt 10: Nginx konfigurieren

```bash
# Als root
exit

# Nginx installieren (falls nicht vorhanden)
sudo apt install nginx -y

# Config erstellen
sudo nano /etc/nginx/sites-available/app
```

**Nginx Configuration**:
```nginx
server {
    listen 80;
    server_name yourdomain.com;
    return 301 https://$server_name$request_uri;
}

server {
    listen 443 ssl http2;
    server_name yourdomain.com;

    ssl_certificate /etc/letsencrypt/live/yourdomain.com/fullchain.pem;
    ssl_certificate_key /etc/letsencrypt/live/yourdomain.com/privkey.pem;

    ssl_protocols TLSv1.2 TLSv1.3;
    ssl_prefer_server_ciphers on;
    ssl_ciphers 'ECDHE-ECDSA-AES128-GCM-SHA256:ECDHE-RSA-AES128-GCM-SHA256';

    location / {
        proxy_pass http://localhost:8080;
        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
        proxy_set_header X-Forwarded-Proto $scheme;
    }

    location /health {
        proxy_pass http://localhost:8080/health;
        access_log off;
    }
}
```

```bash
# Site aktivieren
sudo ln -s /etc/nginx/sites-available/app /etc/nginx/sites-enabled/

# Config testen
sudo nginx -t

# Nginx neu starten
sudo systemctl restart nginx
```

### Schritt 11: Finale Verifikation

```bash
# HTTPS Endpoint testen
curl -f https://yourdomain.com/health/summary

# Detailed Health Check
curl -f https://yourdomain.com/health/detailed

# Metrics prüfen
curl -f https://yourdomain.com/metrics
```

---

## Nach dem Deployment

### Sofort

- [ ] Health Checks alle grün
- [ ] SSL Zertifikat gültig
- [ ] Logs werden geschrieben
- [ ] Metrics erreichbar
- [ ] Admin Panel erreichbar (von erlaubten IPs)

### Innerhalb 24 Stunden

- [ ] Backup Script einrichten
- [ ] Log Rotation konfigurieren
- [ ] Monitoring Alerts konfigurieren
- [ ] Firewall konfigurieren (UFW)
- [ ] SSH Key-Only Authentication
- [ ] Fail2Ban installieren

### Innerhalb 1 Woche

- [ ] Monitoring Dashboard (Grafana)
- [ ] Performance Baseline etablieren
- [ ] Security Audit durchführen
- [ ] Team Zugriff dokumentieren
- [ ] Disaster Recovery testen

---

## Troubleshooting

### Container startet nicht

```bash
# Logs prüfen
docker compose -f docker-compose.production.yml logs php

# Häufige Probleme:
# - Falsche DB Credentials → .env.production prüfen
# - Port bereits in Verwendung → netstat -tulpn | grep 8080
# - Permissions → chown -R appuser:appuser /home/appuser/app
```

### Health Checks failing

```bash
# Spezifischen Check prüfen
curl http://localhost/health/category/database

# Häufige Probleme:
# - Database nicht migriert → php console.php db:migrate
# - Cache nicht beschreibbar → ls -la /var/cache/app
# - Queue läuft nicht → docker compose ps
```

### SSL Probleme

```bash
# Zertifikat prüfen
openssl x509 -in /etc/letsencrypt/live/yourdomain.com/fullchain.pem -noout -dates

# Erneuern
certbot renew --force-renewal

# Nginx neu starten
systemctl restart nginx
```

---

## Rollback Plan

Falls Deployment fehlschlägt:

```bash
# Container stoppen
docker compose -f docker-compose.production.yml down

# Alten Code auschecken (falls deployed)
git checkout <previous-commit>

# Container mit altem Code starten
docker compose -f docker-compose.production.yml up -d

# Migrations rollback (falls nötig)
docker compose -f docker-compose.production.yml exec php php console.php db:rollback
```

---

## Checklisten

### Pre-Deployment Checklist

- [ ] Alle Tests grün lokal
- [ ] Code committed und gepushed
- [ ] Server Anforderungen geprüft
- [ ] Domain DNS konfiguriert
- [ ] SSL Email-Adresse bereit
- [ ] Passwords generiert

### Deployment Checklist

- [ ] SSH Zugriff funktioniert
- [ ] Docker installiert
- [ ] SSL Zertifikat erhalten
- [ ] Repository geklont
- [ ] Secrets generiert und gesichert
- [ ] Environment konfiguriert
- [ ] Container laufen
- [ ] Migrations ausgeführt
- [ ] Health Checks grün
- [ ] Nginx konfiguriert
- [ ] HTTPS funktioniert

### Post-Deployment Checklist

- [ ] Alle Health Checks passing
- [ ] Metrics endpoint erreichbar
- [ ] Logs werden geschrieben
- [ ] Backups konfiguriert
- [ ] Monitoring aktiv
- [ ] Security hardening begonnen
- [ ] Team informiert

---

## Dokumentation

**Vollständige Guides**:
- [Quick Start Guide](docs/deployment/QUICKSTART.md) - Schneller Einstieg
- [Deployment Workflow](docs/deployment/DEPLOYMENT_WORKFLOW.md) - Detaillierter Prozess
- [Production Guide](docs/deployment/PRODUCTION_DEPLOYMENT.md) - Umfassende Referenz
- [Deployment Checklist](docs/deployment/DEPLOYMENT_CHECKLIST.md) - Printable Checklist
- [README](docs/deployment/README.md) - Navigation

---

## Support

Bei Problemen:

1. **Deployment-Dokumentation prüfen** (siehe oben)
2. **Logs prüfen**: `docker compose logs -f`
3. **Health Endpoints prüfen**: `curl http://localhost/health/detailed`
4. **Metrics prüfen**: `curl http://localhost/metrics`

---

## Nächste Schritte nach erfolgreichem Deployment

1. **Monitoring einrichten** (Phase 4 in DEPLOYMENT_WORKFLOW.md)
2. **Backup-System aktivieren** (siehe QUICKSTART.md)
3. **Security Hardening** (siehe DEPLOYMENT_CHECKLIST.md)
4. **Team Training** (Deployment-Prozess dokumentieren)
5. **Performance Baseline** (Metrics über 7 Tage sammeln)

---

**Bereit zum Deployment?**

Führe die Schritte 1-11 oben aus oder folge direkt dem [Quick Start Guide](docs/deployment/QUICKSTART.md).

**Viel Erfolg! 🚀**