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
2. Manuelles Deployment
3. Automatisches CI/CD Deployment
4. Monitoring & Wartung
5. 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)

# 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

# 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

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

# 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

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

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:

# 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

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

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:

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

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

   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

# 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

# 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

# Logs prüfen
docker logs laravel_app

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

Problem: Datenbank-Verbindung fehlgeschlagen

# 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

# 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
   • 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 ist bereits vorkonfiguriert.

   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

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 - Detaillierte Runner-Setup Anleitung
• .gitea/workflows/deploy-synology.yml - Workflow-Konfiguration
• scripts/deploy-synology.sh - Deployment-Script

📝 Weitere Ressourcen

• Laravel Dokumentation
• Docker Dokumentation
• Portainer Dokumentation
• Synology Docker Anleitung
• Gitea Actions Dokumentation

🆘 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