AFC-Demo/SYNOLOGY_DEPLOYMENT.md

# Synology NAS Deployment Anleitung

Diese Anleitung beschreibt, wie du diese Laravel-Anwendung auf deiner Synology NAS mit Portainer deployen kannst.

## 📋 Inhaltsverzeichnis

1. [Voraussetzungen](#voraussetzungen)
2. [Manuelles Deployment](#-vorbereitung)
3. [Automatisches CI/CD Deployment](#-automatisches-deployment-mit-gitea-actions)
4. [Monitoring & Wartung](#-monitoring--wartung)
5. [Troubleshooting](#-troubleshooting)

## Voraussetzungen

- Synology NAS mit Docker-Unterstützung
- Portainer läuft bereits auf deiner NAS
- SSH-Zugriff auf die Synology NAS (optional, aber empfohlen)
- Mindestens 2GB freier RAM
- Mindestens 5GB freier Speicherplatz
- (Optional) Gitea für automatisches CI/CD Deployment

## 📦 Vorbereitung

### 1. Projekt-Dateien auf die NAS übertragen

Es gibt mehrere Möglichkeiten, die Dateien auf deine Synology zu übertragen:

#### Option A: Via Git (empfohlen)
```bash
# SSH auf die Synology NAS
ssh admin@your-synology-ip

# Navigiere zu einem geeigneten Verzeichnis (z.B. /volume1/docker/laravel)
cd /volume1/docker
git clone <dein-repository-url> laravel-app
cd laravel-app
```

#### Option B: Via File Station
1. Öffne die Synology File Station
2. Erstelle einen Ordner: `/docker/laravel-app`
3. Lade alle Projekt-Dateien in diesen Ordner hoch

#### Option C: Via rsync/scp
```bash
# Vom lokalen Rechner aus
rsync -avz --exclude 'node_modules' --exclude 'vendor' \
  /Users/sebastianfrohlich/Herd/frontend/ \
  admin@your-synology-ip:/volume1/docker/laravel-app/
```

### 2. Umgebungsvariablen konfigurieren

```bash
# SSH auf der NAS
cd /volume1/docker/laravel-app

# Kopiere die Synology-Beispiel-Datei
cp .env.synology.example .env.synology

# Bearbeite die Datei mit deinen spezifischen Einstellungen
nano .env.synology
```

**Wichtige Anpassungen in `.env.synology`:**

```env
# Ersetze mit deiner Synology IP-Adresse
APP_URL=http://192.168.1.100:8080

# Setze APP_DEBUG auf false für Produktion
APP_DEBUG=false

# Generiere einen neuen APP_KEY (wichtig für Sicherheit!)
# Dies kann später mit: docker exec laravel_app php artisan key:generate gemacht werden

# PostgreSQL Passwort - ändere dies!
DB_PASSWORD2=dein_sicheres_passwort_hier
```

## 🚀 Deployment mit Portainer

### Methode 1: Docker Compose Stack (empfohlen)

1. **Öffne Portainer** in deinem Browser: `http://your-synology-ip:9000`

2. **Navigiere zu "Stacks"**:
   - Klicke auf "Stacks" im linken Menü
   - Klicke auf "+ Add stack"

3. **Stack konfigurieren**:
   - **Name**: `laravel-app`
   - **Build method**: Wähle "Repository"
   - **Repository URL**: Gib deine Git-Repository-URL ein (falls vorhanden)
   - Oder wähle "Upload" und lade `docker-compose.synology.yml` hoch
   - Oder wähle "Web editor" und kopiere den Inhalt von `docker-compose.synology.yml`

4. **Umgebungsvariablen setzen**:
   Klicke auf "Add an environment variable" und füge folgende Variablen hinzu:

   ```
   APP_NAME=Laravel
   APP_ENV=production
   APP_KEY=base64:L9RVZ3pNFyAvTbMqicT1rL5GbgE+7lJerkU9wyc95H8=
   APP_DEBUG=false
   APP_URL=http://your-synology-ip:8080
   DB_CONNECTION2=pgsql
   DB_HOST2=postgres
   DB_PORT2=5432
   DB_DATABASE2=ingest_db
   DB_USERNAME2=ingest_user
   DB_PASSWORD2=dein_sicheres_passwort
   ```

5. **Stack deployen**:
   - Klicke auf "Deploy the stack"
   - Warte, bis der Build-Prozess abgeschlossen ist (kann 5-10 Minuten dauern)

### Methode 2: Build und Deploy manuell via SSH

```bash
# SSH auf die Synology
ssh admin@your-synology-ip

# Navigiere zum Projekt-Verzeichnis
cd /volume1/docker/laravel-app

# Baue das Docker Image
docker build -t laravel-app:latest .

# Starte die Services mit docker-compose
docker-compose -f docker-compose.synology.yml up -d
```

## 🔍 Verifikation

### 1. Überprüfe den Container-Status

In Portainer:
- Gehe zu "Containers"
- Du solltest zwei laufende Container sehen:
  - `laravel_app` (Status: running, Port: 0.0.0.0:8080->80/tcp)
  - `laravel_postgres` (Status: running, Port: 5432/tcp)

Via SSH:
```bash
docker ps
```

### 2. Überprüfe die Logs

In Portainer:
- Klicke auf den Container `laravel_app`
- Wähle "Logs"
- Du solltest keine Fehler sehen

Via SSH:
```bash
# Laravel App Logs
docker logs laravel_app

# PostgreSQL Logs
docker logs laravel_postgres
```

### 3. Teste die Anwendung

Öffne deinen Browser und navigiere zu:
```
http://your-synology-ip:8080
```

Du solltest die Laravel-Anwendung sehen!

## 🔧 Nützliche Befehle

### Artisan-Befehle ausführen

```bash
# Laravel Cache leeren
docker exec laravel_app php artisan cache:clear

# Neuen APP_KEY generieren
docker exec laravel_app php artisan key:generate

# Migrationen ausführen
docker exec laravel_app php artisan migrate

# Seeder ausführen
docker exec laravel_app php artisan db:seed
```

### Container neustarten

Via Portainer:
- Gehe zu "Containers"
- Wähle den Container aus
- Klicke auf "Restart"

Via SSH:
```bash
docker-compose -f docker-compose.synology.yml restart
```

### Container stoppen und entfernen

Via Portainer:
- Gehe zu "Stacks"
- Wähle den Stack "laravel-app"
- Klicke auf "Stop" oder "Delete"

Via SSH:
```bash
docker-compose -f docker-compose.synology.yml down

# Mit Volumes löschen (Achtung: Löscht die Datenbank!)
docker-compose -f docker-compose.synology.yml down -v
```

### Logs live verfolgen

```bash
# Alle Container
docker-compose -f docker-compose.synology.yml logs -f

# Nur Laravel App
docker logs -f laravel_app

# Nur PostgreSQL
docker logs -f laravel_postgres
```

## 🔐 Sicherheitshinweise

1. **APP_KEY ändern**: Generiere einen neuen APP_KEY für die Produktion:
   ```bash
   docker exec laravel_app php artisan key:generate
   ```

2. **Datenbank-Passwort**: Ändere das Standard-PostgreSQL-Passwort in `.env.synology`

3. **APP_DEBUG**: Stelle sicher, dass `APP_DEBUG=false` in der Produktion

4. **Firewall**: Konfiguriere die Synology-Firewall, um nur benötigte Ports zu öffnen

5. **SSL/HTTPS**: Für den Produktionsbetrieb solltest du einen Reverse Proxy (z.B. Synology DSM Reverse Proxy) mit SSL-Zertifikat einrichten

## 🌐 Reverse Proxy einrichten (optional, aber empfohlen)

Für den Zugriff über eine Domain mit HTTPS:

1. **In Synology DSM**:
   - Gehe zu "Systemsteuerung" → "Anmeldungsportal" → "Erweitert"
   - Klicke auf "Reverse Proxy" → "Erstellen"

2. **Konfiguration**:
   - **Protokoll**: HTTPS
   - **Hostname**: your-domain.com
   - **Port**: 443
   - **Zielprotokoll**: HTTP
   - **Zielhost**: localhost
   - **Zielport**: 8080

3. **SSL-Zertifikat**:
   - Gehe zu "Systemsteuerung" → "Sicherheit" → "Zertifikat"
   - Füge ein Let's Encrypt-Zertifikat hinzu

## 📊 Monitoring & Wartung

### Container-Ressourcen überwachen

In Portainer:
- Gehe zu "Containers"
- Wähle einen Container
- Klicke auf "Stats" für Echtzeit-Metriken (CPU, RAM, Netzwerk)

### Backup

```bash
# PostgreSQL Datenbank sichern
docker exec laravel_postgres pg_dump -U ingest_user ingest_db > backup_$(date +%Y%m%d).sql

# Gesamten Stack sichern (inkl. Volumes)
docker run --rm \
  -v laravel-app_postgres-data:/data \
  -v /volume1/docker/backups:/backup \
  alpine tar czf /backup/postgres-backup-$(date +%Y%m%d).tar.gz /data
```

### Updates

```bash
# Projekt-Code aktualisieren (wenn via Git)
cd /volume1/docker/laravel-app
git pull

# Neu bauen und deployen
docker-compose -f docker-compose.synology.yml up -d --build

# Migrationen ausführen
docker exec laravel_app php artisan migrate --force
```

## ❓ Troubleshooting

### Problem: Container startet nicht

```bash
# Logs prüfen
docker logs laravel_app

# Container interaktiv starten für Debugging
docker exec -it laravel_app sh
```

### Problem: Datenbank-Verbindung fehlgeschlagen

```bash
# PostgreSQL-Container prüfen
docker exec laravel_postgres pg_isready -U ingest_user

# Umgebungsvariablen prüfen
docker exec laravel_app env | grep DB_
```

### Problem: Permissions-Fehler

```bash
# Storage-Permissions korrigieren
docker exec laravel_app chmod -R 775 storage bootstrap/cache
docker exec laravel_app chown -R nginx:nginx storage bootstrap/cache
```

### Problem: Port bereits belegt

Wenn Port 8080 bereits verwendet wird:
1. Öffne `docker-compose.synology.yml`
2. Ändere die Port-Mapping: `"8081:80"` statt `"8080:80"`
3. Aktualisiere `APP_URL` in `.env.synology` entsprechend

## 🤖 Automatisches Deployment mit Gitea Actions

Wenn du Gitea auf deiner Synology NAS verwendest, kannst du den gesamten Build- und Deployment-Prozess automatisieren!

### Vorteile von CI/CD

- ✅ Automatischer Build bei jedem Git Push
- ✅ Automatische Tests vor Deployment
- ✅ Automatisches Deployment auf die NAS
- ✅ Rollback bei Fehlern
- ✅ Keine manuellen Schritte mehr nötig

### Quick Start

1. **Gitea Runner einrichten**
   - Siehe detaillierte Anleitung: [GITEA_RUNNER_SETUP.md](GITEA_RUNNER_SETUP.md)
   - Kurz: Runner Docker Container auf NAS deployen
   - Runner in Gitea registrieren

2. **Repository Secrets konfigurieren**

   Gehe in Gitea zu: **Repository → Settings → Secrets**

   Füge folgende Secrets hinzu:
   ```
   SYNOLOGY_HOST=192.168.1.100
   SYNOLOGY_USER=admin
   SYNOLOGY_SSH_KEY=<dein-ssh-private-key>
   APP_KEY=<dein-laravel-app-key>
   ```

3. **Workflow pushen**

   Der Workflow in [`.gitea/workflows/deploy-synology.yml`](.gitea/workflows/deploy-synology.yml) ist bereits vorkonfiguriert.

   ```bash
   git add .gitea/workflows/deploy-synology.yml
   git commit -m "ci: add automated deployment workflow"
   git push origin main
   ```

4. **Automatisches Deployment genießen! 🎉**

   Bei jedem Push auf `main` oder `develop`:
   - Tests werden ausgeführt
   - Docker Image wird gebaut
   - Deployment auf NAS erfolgt automatisch
   - Health Check verifiziert Deployment

### Workflow-Ablauf

```mermaid
graph LR
    A[Git Push] --> B[Run Tests]
    B --> C{Tests OK?}
    C -->|Ja| D[Build Docker Image]
    C -->|Nein| E[Abbruch]
    D --> F[Transfer zu NAS]
    F --> G[Deploy auf NAS]
    G --> H[Health Check]
    H --> I{Healthy?}
    I -->|Ja| J[✅ Success]
    I -->|Nein| K[Rollback]
```

### Workflow überwachen

1. Gehe zu deinem Repository in Gitea
2. Klicke auf **Actions**
3. Siehe alle Workflow-Runs mit Status
4. Klicke auf einen Run für Details und Logs

### Erweiterte Konfiguration

Weitere Details zur CI/CD-Konfiguration findest du in:
- [GITEA_RUNNER_SETUP.md](GITEA_RUNNER_SETUP.md) - Detaillierte Runner-Setup Anleitung
- [`.gitea/workflows/deploy-synology.yml`](.gitea/workflows/deploy-synology.yml) - Workflow-Konfiguration
- [`scripts/deploy-synology.sh`](scripts/deploy-synology.sh) - Deployment-Script

## 📝 Weitere Ressourcen

- [Laravel Dokumentation](https://laravel.com/docs)
- [Docker Dokumentation](https://docs.docker.com/)
- [Portainer Dokumentation](https://docs.portainer.io/)
- [Synology Docker Anleitung](https://www.synology.com/en-us/dsm/packages/Docker)
- [Gitea Actions Dokumentation](https://docs.gitea.com/usage/actions/overview)

## 🆘 Support

Bei Problemen:
1. Prüfe die Container-Logs
2. Überprüfe die Umgebungsvariablen
3. Stelle sicher, dass alle Ports verfügbar sind
4. Prüfe die Synology-Firewall-Einstellungen
5. Bei CI/CD: Prüfe Gitea Actions Logs und Runner Status