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)

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

# 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

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:

# 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

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:

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

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

# 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

# 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

# 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

# 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

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

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

Schritt 6: Environment konfigurieren

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

Minimal Configuration:

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:

# DB Password
openssl rand -base64 32

# JWT Secret
openssl rand -base64 64

Schritt 7: Build und Start

# 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

# 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

# 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

# Als root
exit

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

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

Nginx Configuration:

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;
    }
}

# 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

# 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

# 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

# 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

# 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:

# 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 - Schneller Einstieg
• Deployment Workflow - Detaillierter Prozess
• Production Guide - Umfassende Referenz
• Deployment Checklist - Printable Checklist
• README - 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.

Viel Erfolg! 🚀