AFC-Demo/GITEA_RUNNER_SETUP.md

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:

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:

RUNNER_TOKEN=dein_gitea_runner_token_hier

4. Runner starten

cd /volume1/docker/gitea-runner
docker-compose up -d

5. Runner verifizieren

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

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:

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:

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

# In Gitea Repository Settings → Secrets
✅ SYNOLOGY_HOST
✅ SYNOLOGY_USER
✅ SYNOLOGY_SSH_KEY
✅ APP_KEY

Workflow aktivieren

1. Workflow-Datei pushen

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

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

# 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

# Laravel App Logs
docker logs -f laravel_app

# Deployment Script Logs
# Diese werden in der Workflow-Ausgabe angezeigt

Troubleshooting

Problem: Runner verbindet sich nicht

# 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

# 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

# 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

# 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

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:

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:

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

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:

- 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
• Act Runner Dokumentation
• Docker Compose Dokumentation

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