ci: add automated Gitea Actions deployment workflow for Synology NAS

- Add Gitea Actions workflow for automated build and deployment - Add deployment script for Synology NAS - Add Docker Compose configurations for production deployment - Add Gitea runner setup - Add comprehensive documentation for CI/CD setup - Add health check endpoint for deployment verification - Update .gitignore for CI/CD artifacts
2025-12-17 13:02:38 +01:00
1 parent 2f7bd923df
commit 94d02736f7
@@ -0,0 +1,411 @@
+# Gitea Runner Setup auf Synology NAS
+
+Diese Anleitung erklärt, wie du einen Gitea Actions Runner auf deiner Synology NAS einrichtest, um automatische Deployments durchzuführen.
+
+## Voraussetzungen
+
+- Gitea läuft auf deiner Synology NAS
+- Docker ist auf der Synology NAS installiert
+- SSH-Zugriff auf die Synology NAS
+- Portainer läuft (optional, aber empfohlen für Container-Management)
+
+## Option 1: Gitea Runner mit Docker Compose (empfohlen)
+
+### 1. Runner Docker Compose Datei erstellen
+
+Erstelle eine Datei `/volume1/docker/gitea-runner/docker-compose.yml`:
+
+```yaml
+version: "3.9"
+
+services:
+  runner:
+    image: gitea/act_runner:latest
+    container_name: gitea-runner
+    restart: unless-stopped
+
+    environment:
+      - GITEA_INSTANCE_URL=http://your-gitea-url:3000
+      - GITEA_RUNNER_REGISTRATION_TOKEN=${RUNNER_TOKEN}
+      - GITEA_RUNNER_NAME=synology-runner
+      - GITEA_RUNNER_LABELS=ubuntu-latest:docker://node:20-bullseye
+
+    volumes:
+      - ./data:/data
+      - /var/run/docker.sock:/var/run/docker.sock
+
+    networks:
+      - gitea-network
+
+networks:
+  gitea-network:
+    external: true
+```
+
+### 2. Runner Token generieren
+
+1. Öffne deine Gitea-Instanz im Browser
+2. Navigiere zu deinem Repository
+3. Gehe zu **Settings** → **Actions** → **Runners**
+4. Klicke auf **Create new Runner**
+5. Kopiere den generierten Token
+
+### 3. Environment Variables setzen
+
+Erstelle eine `.env` Datei im selben Verzeichnis:
+
+```env
+RUNNER_TOKEN=dein_gitea_runner_token_hier
+```
+
+### 4. Runner starten
+
+```bash
+cd /volume1/docker/gitea-runner
+docker-compose up -d
+```
+
+### 5. Runner verifizieren
+
+```bash
+# Logs anschauen
+docker logs -f gitea-runner
+
+# Status prüfen
+docker ps | grep gitea-runner
+```
+
+In Gitea solltest du nun unter **Settings** → **Actions** → **Runners** deinen registrierten Runner sehen.
+
+## Option 2: Runner direkt in Portainer deployen
+
+### 1. In Portainer einloggen
+
+Öffne Portainer: `http://your-synology-ip:9000`
+
+### 2. Stack erstellen
+
+1. Gehe zu **Stacks** → **+ Add stack**
+2. Name: `gitea-runner`
+3. Wähle **Web editor**
+4. Füge die obige docker-compose.yml ein
+
+### 3. Environment Variables
+
+Füge folgende Environment Variable hinzu:
+- **RUNNER_TOKEN**: Dein Gitea Runner Token
+
+### 4. Deploy
+
+Klicke auf **Deploy the stack**
+
+## Runner Konfiguration
+
+### Custom Runner Labels
+
+Um spezifische Workflows auszuführen, kannst du Custom Labels hinzufügen:
+
+```yaml
+environment:
+  - GITEA_RUNNER_LABELS=ubuntu-latest:docker://node:20-bullseye,ubuntu-22.04:docker://ubuntu:22.04,php-8.4:docker://php:8.4-cli
+```
+
+### Mehrere Runner
+
+Für parallele Builds kannst du mehrere Runner starten:
+
+```yaml
+services:
+  runner-1:
+    image: gitea/act_runner:latest
+    container_name: gitea-runner-1
+    # ... config ...
+
+  runner-2:
+    image: gitea/act_runner:latest
+    container_name: gitea-runner-2
+    # ... config ...
+```
+
+## Repository Secrets konfigurieren
+
+Um das automatische Deployment zu ermöglichen, musst du Secrets in deinem Gitea-Repository hinterlegen:
+
+### 1. In Gitea Repository Settings
+
+1. Gehe zu deinem Repository
+2. Klicke auf **Settings** → **Secrets**
+3. Füge folgende Secrets hinzu:
+
+| Secret Name | Beschreibung | Beispiel |
+|------------|--------------|----------|
+| `SYNOLOGY_HOST` | IP oder Hostname deiner Synology | `192.168.1.100` |
+| `SYNOLOGY_USER` | SSH-Benutzername | `admin` |
+| `SYNOLOGY_SSH_KEY` | Privater SSH-Key für Zugriff | `-----BEGIN OPENSSH PRIVATE KEY-----...` |
+| `APP_KEY` | Laravel Application Key | `base64:xyz...` |
+
+### 2. SSH-Key generieren (falls nicht vorhanden)
+
+Auf deiner Synology NAS:
+
+```bash
+# SSH-Key-Pair generieren
+ssh-keygen -t ed25519 -C "gitea-runner@synology" -f ~/.ssh/gitea_deploy
+
+# Public Key zum authorized_keys hinzufügen
+cat ~/.ssh/gitea_deploy.pub >> ~/.ssh/authorized_keys
+chmod 600 ~/.ssh/authorized_keys
+
+# Private Key anzeigen (für Secret)
+cat ~/.ssh/gitea_deploy
+```
+
+Kopiere den **gesamten** Private Key (inklusive `-----BEGIN` und `-----END` Zeilen) und füge ihn als `SYNOLOGY_SSH_KEY` Secret hinzu.
+
+### 3. Secrets verifizieren
+
+Stelle sicher, dass alle benötigten Secrets gesetzt sind:
+
+```bash
+# In Gitea Repository Settings → Secrets
+✅ SYNOLOGY_HOST
+✅ SYNOLOGY_USER
+✅ SYNOLOGY_SSH_KEY
+✅ APP_KEY
+```
+
+## Workflow aktivieren
+
+### 1. Workflow-Datei pushen
+
+```bash
+# Lokal im Projekt
+git add .gitea/workflows/deploy-synology.yml
+git commit -m "ci: add automated deployment workflow"
+git push origin main
+```
+
+### 2. Workflow ausführen
+
+Gitea Actions wird automatisch bei jedem Push auf `main` oder `develop` ausgelöst.
+
+### 3. Workflow Status prüfen
+
+1. Gehe zu deinem Repository in Gitea
+2. Klicke auf **Actions**
+3. Du siehst alle Workflow-Runs mit Status (Success/Failure)
+4. Klicke auf einen Run, um Details und Logs zu sehen
+
+## Workflow manuell auslösen
+
+Falls du den Workflow manuell starten möchtest:
+
+### 1. Workflow-Datei erweitern
+
+Füge in `.gitea/workflows/deploy-synology.yml` hinzu:
+
+```yaml
+on:
+  push:
+    branches:
+      - main
+      - develop
+  workflow_dispatch:  # Ermöglicht manuelles Auslösen
+```
+
+### 2. Manuell auslösen
+
+1. Gehe zu **Actions** in deinem Repository
+2. Wähle den Workflow aus
+3. Klicke auf **Run workflow**
+
+## Monitoring & Logs
+
+### Runner Logs
+
+```bash
+# Live Logs
+docker logs -f gitea-runner
+
+# Letzte 100 Zeilen
+docker logs --tail 100 gitea-runner
+```
+
+### Workflow Logs
+
+In Gitea UI:
+1. **Actions** Tab
+2. Wähle einen Workflow Run
+3. Klicke auf die einzelnen Jobs, um Logs zu sehen
+
+### Deployment Logs auf Synology
+
+```bash
+# Laravel App Logs
+docker logs -f laravel_app
+
+# Deployment Script Logs
+# Diese werden in der Workflow-Ausgabe angezeigt
+```
+
+## Troubleshooting
+
+### Problem: Runner verbindet sich nicht
+
+```bash
+# Logs prüfen
+docker logs gitea-runner
+
+# Runner neu registrieren
+docker-compose down
+docker-compose up -d
+```
+
+### Problem: Workflow startet nicht
+
+1. **Runner Status prüfen**: Gehe zu Repository → Settings → Actions → Runners
+2. **Runner Labels prüfen**: Stelle sicher, dass `runs-on: ubuntu-latest` mit den Runner Labels übereinstimmt
+3. **Secrets prüfen**: Alle benötigten Secrets müssen gesetzt sein
+
+### Problem: SSH-Verbindung fehlschlägt
+
+```bash
+# SSH-Key Permissions prüfen
+chmod 600 ~/.ssh/gitea_deploy
+chmod 644 ~/.ssh/gitea_deploy.pub
+chmod 700 ~/.ssh
+chmod 600 ~/.ssh/authorized_keys
+
+# SSH-Verbindung testen (lokal auf der NAS)
+ssh -i ~/.ssh/gitea_deploy admin@localhost
+```
+
+### Problem: Deployment schlägt fehl
+
+```bash
+# Prüfe deployment script permissions
+cd /volume1/docker/laravel-app
+ls -la deploy-synology.sh
+
+# Mache es executable
+chmod +x deploy-synology.sh
+
+# Teste deployment script manuell
+./deploy-synology.sh
+```
+
+### Problem: Health Check fehlschlägt
+
+```bash
+# Prüfe ob Container läuft
+docker ps | grep laravel_app
+
+# Prüfe Logs
+docker logs laravel_app
+
+# Teste Health Endpoint manuell
+curl http://localhost:8080/health
+```
+
+## Best Practices
+
+### 1. Separate Runner für Production und Staging
+
+```yaml
+services:
+  runner-production:
+    environment:
+      - GITEA_RUNNER_LABELS=production:docker://ubuntu:22.04
+
+  runner-staging:
+    environment:
+      - GITEA_RUNNER_LABELS=staging:docker://ubuntu:22.04
+```
+
+Im Workflow:
+```yaml
+jobs:
+  deploy-production:
+    runs-on: production
+    if: github.ref == 'refs/heads/main'
+```
+
+### 2. Workflow nur für Conventional Commits
+
+Der aktuelle Workflow filtert bereits nach Conventional Commits:
+- `feat:` - Neue Features
+- `fix:` - Bugfixes
+- `docs:` - Dokumentation
+- `chore:` - Wartungsarbeiten
+- etc.
+
+### 3. Notifications
+
+Erweitere den Workflow um Benachrichtigungen:
+
+```yaml
+- name: Send Notification
+  if: always()
+  run: |
+    # Telegram, Discord, Email, etc.
+    curl -X POST https://api.telegram.org/bot${{ secrets.TELEGRAM_BOT_TOKEN }}/sendMessage \
+      -d chat_id=${{ secrets.TELEGRAM_CHAT_ID }} \
+      -d text="Deployment status: ${{ job.status }}"
+```
+
+### 4. Rollback-Strategie
+
+Im deployment script ist bereits ein Backup-Mechanismus implementiert:
+- Datenbank-Backups vor jedem Deployment
+- Letzte 5 Backups werden aufbewahrt
+- Automatischer Rollback bei Fehlern
+
+## Erweiterte Konfiguration
+
+### Multi-Stage Deployments
+
+Für staging und production environments:
+
+```yaml
+jobs:
+  deploy-staging:
+    if: github.ref == 'refs/heads/develop'
+    # ... deploy to staging ...
+
+  deploy-production:
+    if: github.ref == 'refs/heads/main'
+    needs: [test, deploy-staging]
+    # ... deploy to production ...
+```
+
+### Caching
+
+Um Build-Zeiten zu verkürzen:
+
+```yaml
+- name: Cache Composer
+  uses: actions/cache@v3
+  with:
+    path: vendor
+    key: ${{ runner.os }}-composer-${{ hashFiles('composer.lock') }}
+
+- name: Cache NPM
+  uses: actions/cache@v3
+  with:
+    path: node_modules
+    key: ${{ runner.os }}-npm-${{ hashFiles('package-lock.json') }}
+```
+
+## Weitere Ressourcen
+
+- [Gitea Actions Dokumentation](https://docs.gitea.com/usage/actions/overview)
+- [Act Runner Dokumentation](https://gitea.com/gitea/act_runner)
+- [Docker Compose Dokumentation](https://docs.docker.com/compose/)
+
+## Support
+
+Bei Problemen:
+1. Prüfe Runner Logs: `docker logs gitea-runner`
+2. Prüfe Workflow Logs in Gitea Actions Tab
+3. Verifiziere alle Secrets sind korrekt gesetzt
+4. Teste SSH-Verbindung zur Synology manuell