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

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