AFC-Demo/CI_CD_README.md

# CI/CD Automatisierung für Synology NAS

Dieses Projekt ist vollständig für automatisches Deployment auf deiner Synology NAS mit Gitea Actions vorbereitet.

## 🚀 Schnellstart

### 1. Gitea Runner einrichten (einmalig)

```bash
# Auf der Synology NAS
cd /volume1/docker
mkdir gitea-runner
cd gitea-runner

# Environment Datei erstellen
cat > .env << 'EOF'
GITEA_URL=http://your-synology-ip:3000
RUNNER_TOKEN=your_token_from_gitea
RUNNER_NAME=synology-runner
EOF

# Runner starten
ll
```

**Runner Token generieren:**
1. Gitea öffnen
2. Repository → Settings → Actions → Runners
3. "Create new Runner" klicken
4. Token kopieren und in `.env` einfügen

📖 Detaillierte Anleitung: [GITEA_RUNNER_SETUP.md](GITEA_RUNNER_SETUP.md)

### 2. Repository Secrets konfigurieren (einmalig)

In Gitea: **Repository → Settings → Secrets**

| Secret Name | Wert | Beschreibung |
|------------|------|--------------|
| `SYNOLOGY_HOST` | `192.168.1.100` | IP deiner Synology |
| `SYNOLOGY_USER` | `admin` | SSH-Benutzername |
| `SYNOLOGY_SSH_KEY` | `-----BEGIN...` | Private SSH-Key |
| `APP_KEY` | `base64:...` | Laravel APP_KEY |

**SSH-Key erstellen:**

```bash
# Auf der Synology NAS
ssh-keygen -t ed25519 -C "gitea-deploy" -f ~/.ssh/gitea_deploy
cat ~/.ssh/gitea_deploy.pub >> ~/.ssh/authorized_keys
cat ~/.ssh/gitea_deploy  # Diesen Key als Secret verwenden
```

### 3. Code pushen und automatisch deployen! 🎉

```bash
git add .
git commit -m "feat: meine neue Funktion"
git push origin main
```

Das wars! Der Rest läuft automatisch:
- ✅ Tests werden ausgeführt
- ✅ Docker Image wird gebaut
- ✅ Deployment auf NAS
- ✅ Health Check
- ✅ Benachrichtigung bei Erfolg/Fehler

## 📁 Wichtige Dateien

| Datei | Beschreibung |
|-------|--------------|
| [`.gitea/workflows/deploy-synology.yml`](.gitea/workflows/deploy-synology.yml) | Gitea Actions Workflow |
| [`docker-compose.synology.yml`](docker-compose.synology.yml) | Docker Compose für Deployment |
| [`scripts/deploy-synology.sh`](scripts/deploy-synology.sh) | Deployment-Script |
| [`.env.synology.example`](.env.synology.example) | Environment-Beispiel |
| [`SYNOLOGY_DEPLOYMENT.md`](SYNOLOGY_DEPLOYMENT.md) | Vollständige Deployment-Doku |
| [`GITEA_RUNNER_SETUP.md`](GITEA_RUNNER_SETUP.md) | Gitea Runner Setup-Anleitung |

## 🔄 Workflow-Prozess

```
1. Developer pushed Code zu Gitea
   ↓
2. Gitea Actions Workflow startet
   ↓
3. Tests laufen (Pest)
   ↓
4. Docker Image wird gebaut
   ↓
5. Image wird zur Synology NAS übertragen
   ↓
6. Deployment-Script läuft auf NAS
   ↓
7. Container werden aktualisiert
   ↓
8. Migrationen & Cache-Optimierung
   ↓
9. Health Check
   ↓
10. ✅ Deployment erfolgreich!
```

## 🎯 Features

### Automatisierte Tests
- PHP-Tests mit Pest
- Frontend-Build-Validierung
- Nur erfolgreiche Builds werden deployed

### Intelligentes Deployment
- Automatisches Backup vor Deployment
- Rollback bei Fehlern
- Health Checks nach Deployment
- Zero-Downtime durch Docker

### Branch-spezifisches Deployment
- `main` → Production (Port 8080)
- `develop` → Staging (Port 8081)
- Feature-Branches → Nur Tests

### Conventional Commits
Der Workflow akzeptiert nur Conventional Commits:
- `feat:` - Neue Features
- `fix:` - Bugfixes
- `docs:` - Dokumentation
- `chore:` - Wartung
- `refactor:` - Code-Refactoring
- `test:` - Tests
- `ci:` - CI/CD Änderungen

**Beispiel:**
```bash
git commit -m "feat: add user authentication"
git commit -m "fix: resolve database connection issue"
```

## 🔍 Monitoring

### Workflow Status prüfen

**In Gitea:**
1. Repository öffnen
2. Tab "Actions" anklicken
3. Alle Runs mit Status sehen

**Logs ansehen:**
- Klicke auf einen Run
- Klicke auf einen Job (test/build/deploy)
- Sieh detaillierte Logs

### Container Logs

```bash
# Auf der Synology NAS via SSH
docker logs -f laravel_app
docker logs -f laravel_postgres
```

### Health Endpoint

```bash
curl http://your-synology-ip:8080/health
```

Response:
```json
{
  "status": "healthy",
  "timestamp": "2025-12-17T10:30:00Z",
  "app": "Laravel",
  "env": "production"
}
```

## 🛠 Manuelle Befehle

### Manuelles Deployment

```bash
# Auf der Synology NAS
cd /volume1/docker/laravel-app
./scripts/deploy-synology.sh
```

### Container verwalten

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

# Logs ansehen
docker-compose -f docker-compose.synology.yml logs -f

# Neustart
docker-compose -f docker-compose.synology.yml restart

# Stoppen
docker-compose -f docker-compose.synology.yml down
```

### Laravel Artisan

```bash
# Migrationen
docker exec laravel_app php artisan migrate

# Cache leeren
docker exec laravel_app php artisan cache:clear

# Shell öffnen
docker exec -it laravel_app sh
```

## 🐛 Troubleshooting

### Workflow startet nicht

**Prüfen:**
1. Runner Status in Gitea → Settings → Actions → Runners
2. Commit-Message ist Conventional Commit Format
3. Branch ist `main` oder `develop`

**Lösung:**
```bash
# Runner neu starten
docker restart gitea-runner

# Runner Logs prüfen
docker logs gitea-runner
```

### Deployment schlägt fehl

**Prüfen:**
1. SSH-Verbindung zur NAS funktioniert
2. Alle Secrets sind korrekt gesetzt
3. Deployment-Script ist executable

**Lösung:**
```bash
# SSH-Key testen
ssh -i ~/.ssh/gitea_deploy admin@your-synology-ip

# Permissions prüfen
chmod +x scripts/deploy-synology.sh
```

### Health Check fehlschlägt

**Prüfen:**
1. Container läuft: `docker ps | grep laravel_app`
2. Logs: `docker logs laravel_app`
3. Netzwerk: `curl http://localhost:8080/health`

**Lösung:**
```bash
# Container neu starten
docker-compose -f docker-compose.synology.yml restart

# .env prüfen
docker exec laravel_app cat .env.synology
```

## 📚 Weitere Dokumentation

- **Deployment Details:** [SYNOLOGY_DEPLOYMENT.md](SYNOLOGY_DEPLOYMENT.md)
- **Gitea Runner Setup:** [GITEA_RUNNER_SETUP.md](GITEA_RUNNER_SETUP.md)
- **Workflow Konfiguration:** [.gitea/workflows/deploy-synology.yml](.gitea/workflows/deploy-synology.yml)
- **Deployment Script:** [scripts/deploy-synology.sh](scripts/deploy-synology.sh)

## 🎉 Das wars!

Nach der einmaligen Einrichtung läuft alles automatisch:

1. Code schreiben
2. Commit & Push
3. Warten bis Deployment fertig ist
4. Anwendung ist live! 🚀

**Happy Deploying!** 🎊