AFC-Demo/terraform/QUICKSTART.md

# 🚀 Quickstart Guide - Laravel auf Azure AKS

Diese Anleitung führt dich in ~30 Minuten durch das komplette Deployment deiner Laravel-Anwendung auf Azure Kubernetes Service.

## ✅ Voraussetzungen Check

```bash
# Prüfe ob alle Tools installiert sind
terraform version  # >= 1.9.0
az version        # >= 2.0
kubectl version   # >= 1.28
docker version    # >= 20.10
php -v            # >= 8.2
```

## 📝 Schritt-für-Schritt Anleitung

### 1️⃣ Azure Login (2 Min)

```bash
# Login
az login

# Subscription setzen
az account set --subscription "77677a80-2dea-493d-9867-f1c961b80fb3"

# Verify
az account show
```

### 2️⃣ Container Registry Setup (5 Min)

```bash
# ACR erstellen (wenn nicht vorhanden)
az acr create \
  --resource-group trusted_ai_demo_rg \
  --name mylaravelregistry \
  --sku Basic \
  --location germanywestcentral

# AKS Zugriff auf ACR geben
az aks update \
  --resource-group trusted_ai_demo_rg \
  --name trai_k8s_cluster \
  --attach-acr mylaravelregistry

# Login
az acr login --name mylaravelregistry
```

### 3️⃣ Docker Image Build & Push (5 Min)

```bash
# Zum Projekt-Root wechseln
cd /Users/sebastianfrohlich/Herd/frontend

# Image bauen
docker build -t mylaravelregistry.azurecr.io/laravel-app:v1.0.0 .

# Image pushen
docker push mylaravelregistry.azurecr.io/laravel-app:v1.0.0
```

### 4️⃣ Laravel APP_KEY generieren (1 Min)

```bash
# Im Projekt-Root
php artisan key:generate --show

# Beispiel Output: base64:abcdefgh12345...
# Kopiere diesen Wert für den nächsten Schritt
```

### 5️⃣ Terraform Konfiguration (5 Min)

```bash
# Zu Terraform wechseln
cd terraform

# Konfiguration kopieren
cp terraform.tfvars.example terraform.tfvars

# Bearbeiten
nano terraform.tfvars
```

**Wichtige Werte in `terraform.tfvars` ändern:**

```hcl
# Docker Image (von Schritt 3)
docker_image = "mylaravelregistry.azurecr.io/laravel-app:v1.0.0"

# Laravel Key (von Schritt 4)
app_key = "base64:abcdefgh12345..."

# PostgreSQL Password (sicheres Passwort wählen!)
postgresql_admin_password = "YourSecurePassword123!"

# Email für Alerts
alert_email_address = "your-email@example.com"
```

### 6️⃣ Deployment ausführen (10 Min)

```bash
# Automatisches Deployment mit Script
./scripts/deploy.sh
```

Das Script führt automatisch aus:
- ✅ Prerequisite-Check
- ✅ Terraform init
- ✅ Terraform validate
- ✅ Terraform plan
- ✅ Terraform apply (nach Bestätigung)
- ✅ kubectl konfigurieren
- ✅ Pod-Status prüfen

**Oder manuell:**

```bash
# Init
terraform init

# Plan
terraform plan -out=tfplan

# Apply
terraform apply tfplan

# kubectl konfigurieren
az aks get-credentials \
  --resource-group trusted_ai_demo_rg \
  --name trai_k8s_cluster \
  --overwrite-existing
```

### 7️⃣ Datenbank wiederherstellen (5 Min)

```bash
# Automatisches Restore-Script
./scripts/restore-db.sh

# Script fragt:
# - Welches Backup-File? (z.B. backup_backend_20251203_101741.dump)
# - Bestätigung: yes
# - Zeigt Fortschritt und Logs
```

**Oder in terraform.tfvars setzen und nochmal apply:**

```hcl
db_restore_enabled  = true
db_backup_file_path = "../backups/backup_backend_20251203_101741.dump"
```

```bash
terraform apply
```

### 8️⃣ Anwendung testen (2 Min)

```bash
# LoadBalancer IP abrufen
kubectl get svc ingress-nginx-controller -n ingress-nginx

# Oder über Terraform Output
terraform output app_url

# Example Output:
# app_url = "http://20.79.123.456"
```

🎉 **Öffne die URL im Browser!**

### 9️⃣ Status prüfen

```bash
# Pods prüfen
kubectl get pods -n laravel-app

# Services prüfen
kubectl get svc -n laravel-app

# Ingress prüfen
kubectl get ingress -n laravel-app

# Logs anzeigen
kubectl logs -n laravel-app -l app=laravel-app -f

# Database restore job prüfen (wenn aktiviert)
kubectl get jobs -n laravel-app
kubectl logs -n laravel-app -l job-type=database-restore
```

## 🔧 Häufige Probleme

### Problem: Pods starten nicht (ImagePullBackOff)

```bash
# Prüfe ob ACR-Integration funktioniert
az aks check-acr \
  --resource-group trusted_ai_demo_rg \
  --name trai_k8s_cluster \
  --acr mylaravelregistry.azurecr.io

# Fix: ACR Integration neu setzen
az aks update \
  --resource-group trusted_ai_demo_rg \
  --name trai_k8s_cluster \
  --attach-acr mylaravelregistry
```

### Problem: LoadBalancer IP bleibt "Pending"

```bash
# Prüfe Service Events
kubectl describe svc ingress-nginx-controller -n ingress-nginx

# Warte 5-10 Minuten - Azure braucht Zeit für LoadBalancer Setup
kubectl get svc -n ingress-nginx -w
```

### Problem: Database Connection Failed

```bash
# Prüfe PostgreSQL Firewall Rules
az postgres flexible-server firewall-rule list \
  --resource-group trusted_ai_demo_rg \
  --name <server-name>

# Prüfe Secrets
kubectl get secret laravel-app-db-credentials -n laravel-app -o yaml | grep DB_
```

### Problem: 502 Bad Gateway

```bash
# Prüfe ob Pods ready sind
kubectl get pods -n laravel-app

# Prüfe Pod Logs
kubectl logs -n laravel-app <pod-name>

# Teste direkt zum Service
kubectl port-forward -n laravel-app svc/laravel-app 8080:80
# Dann: http://localhost:8080
```

## 📊 Nützliche Befehle

### Status-Übersicht

```bash
# Alles auf einen Blick
kubectl get all -n laravel-app
kubectl get all -n ingress-nginx

# Terraform Outputs
terraform output
```

### Logs anzeigen

```bash
# Application Logs (alle Pods)
kubectl logs -n laravel-app -l app=laravel-app -f

# Bestimmter Pod
kubectl logs -n laravel-app <pod-name> -f

# Ingress Controller Logs
kubectl logs -n ingress-nginx -l app.kubernetes.io/component=controller -f
```

### Scale Up/Down

```bash
# Mehr Replicas
kubectl scale deployment/laravel-app --replicas=3 -n laravel-app

# Prüfen
kubectl get pods -n laravel-app
```

### Shell in Pod

```bash
# Shell öffnen
kubectl exec -it -n laravel-app <pod-name> -- /bin/sh

# Laravel Artisan in Pod ausführen
kubectl exec -it -n laravel-app <pod-name> -- php artisan migrate:status
kubectl exec -it -n laravel-app <pod-name> -- php artisan route:list
```

### Port-Forward für lokalen Zugriff

```bash
# App direkt aufrufen (ohne LoadBalancer)
kubectl port-forward -n laravel-app svc/laravel-app 8080:80

# Dann: http://localhost:8080
```

## 🔄 Updates deployen

### Neue Version deployen

```bash
# 1. Code ändern
# 2. Neues Image bauen
docker build -t mylaravelregistry.azurecr.io/laravel-app:v1.0.1 .
docker push mylaravelregistry.azurecr.io/laravel-app:v1.0.1

# 3. Deployment updaten (schnell)
kubectl set image deployment/laravel-app \
  laravel-app=mylaravelregistry.azurecr.io/laravel-app:v1.0.1 \
  -n laravel-app

# Rollout Status prüfen
kubectl rollout status deployment/laravel-app -n laravel-app
```

### Rollback

```bash
# Zur vorherigen Version zurück
kubectl rollout undo deployment/laravel-app -n laravel-app
```

## 🧹 Cleanup

### Nur App löschen (DB behalten)

```bash
terraform destroy -target=kubernetes_deployment.app
terraform destroy -target=kubernetes_service.app
```

### Alles löschen

```bash
terraform destroy
```

## 📚 Weitere Informationen

- Ausführliche Dokumentation: [README.md](README.md)
- Terraform Outputs: `terraform output`
- Azure Portal: https://portal.azure.com

## 🆘 Hilfe benötigt?

```bash
# Terraform Outputs anzeigen
terraform output deployment_instructions

# Kubernetes Events prüfen
kubectl get events -n laravel-app --sort-by='.lastTimestamp'

# Resource Status
kubectl describe deployment laravel-app -n laravel-app
kubectl describe svc laravel-app -n laravel-app
```

## ✨ Next Steps

Nach erfolgreichem Deployment:

1. **Domain konfigurieren** (optional):
   ```hcl
   # In terraform.tfvars
   ingress_host = "app.yourdomain.com"
   ssl_enabled = true
   ssl_issuer_email = "admin@yourdomain.com"
   ```

   ```bash
   terraform apply
   ```

2. **Monitoring einrichten**: Prüfe Azure Monitor in Azure Portal

3. **CI/CD Pipeline**: Erstelle GitHub Actions oder Azure DevOps Pipeline

4. **Backups testen**: Teste Restore-Prozess

5. **Security Hardening**:
   - VNet Integration für PostgreSQL
   - Private Endpoints
   - RBAC konfigurieren

---

**Deployment Time:** ~30 Minuten
**Kosten:** ~50-100€/Monat (abhängig von Ressourcen)
**Scaling:** Horizontal (mehr Pods) & Vertikal (größere VMs)