diff --git a/Kapitel 13/Premium Rohtext.md b/Kapitel 13/Premium Rohtext.md new file mode 100644 index 0000000..6ec3618 --- /dev/null +++ b/Kapitel 13/Premium Rohtext.md @@ -0,0 +1,459 @@ +# Premium – CI-Pipelines, Self-Hosted Runner & Webhooks mit Gitea + +Im Free-Kapitel hast du eine stabile Gitea-Instanz eingerichtet, die deine Projekte versioniert und über HTTPS erreichbar ist. +Damit steht das Fundament für saubere Versionsverwaltung und Team-Strukturen. + +Im Premium-Teil erweitern wir dieses System zu einer **automatisierten Entwicklungs- und Produktionsumgebung**, die eigenständig Builds, Tests oder Deployments ausführt – komplett lokal, ohne externe CI-Dienste. +Du lernst, wie Gitea mit Self-Hosted-Runnern arbeitet, wie du CI-Pipelines definierst und wie Webhooks Aktionen in anderen UCC-Systemen (z. B. n8n oder Vaultwarden) auslösen. + +Ziel ist nicht mehr nur das reine Speichern von Code, sondern **automatisches Ausführen, Prüfen und Verteilen** – alles innerhalb deines Homelabs. + +In diesem Kapitel behandeln wir: + +1. **Einrichtung des Gitea-Actions-Systems** + Aktivierung der integrierten CI-Umgebung auf deiner Instanz. + Einrichtung des ersten Self-Hosted-Runners im Container oder auf einem separaten Node. + +2. **Definition einer CI-Pipeline** + Aufbau eines vollständigen Workflow-YAMLs, der Code überprüft, Dateien erstellt oder Skripte automatisch testet. + Praxisbeispiel: Automatischer PDF-Build aus Markdown-Tutorials. + +3. **Integration mit n8n und Vaultwarden** + Nutzung von Webhooks für Benachrichtigungen, Status-Monitoring und automatisches Key-Handling. + Beispiel: Push → Webhook → n8n startet Backup oder Deployment. + +4. **Erweiterte Automatisierungen (optional)** + Nutzung mehrerer Runner, paralleler Jobs und Artefakt-Uploads. + Wie du Gitea als zentrales Automatisierungs-Backbone des UCC nutzt. + +> [!NOTE] +> Alle Schritte basieren auf der bestehenden Installation aus dem Free-Kapitel. +> Die dort erstellte Gitea-Instanz bleibt unverändert – du erweiterst sie lediglich um CI- und Webhook-Funktionen. +> Stelle sicher, dass dein Git-LXC aktiv und über HTTPS erreichbar ist, bevor du beginnst. + +Mit diesen Erweiterungen wird Gitea zu einem **vollwertigen Automations-Server** – +es verwaltet Projekte, testet Änderungen, verteilt Ergebnisse und kann mit anderen Komponenten deines UCC (n8n, Vaultwarden, Nextcloud) direkt interagieren. + +--- + +## Gitea Actions – lokale CI/CD-Automatisierung + +Mit **Gitea Actions** kannst du Prozesse automatisieren, die sonst manuell erledigt werden müssten – etwa das Erstellen, Testen oder Verteilen von Projekten. +Das System funktioniert ähnlich wie GitHub Actions, läuft aber vollständig lokal und benötigt keine Verbindung zu externen Diensten. +Damit bleibt deine Entwicklungs- und Produktionsumgebung komplett unter deiner Kontrolle. + +> [!NOTE] +> Gitea Actions ist seit Version 1.19 integriert. +> Stelle sicher, dass dein Image aktuell ist, bevor du beginnst: +> ```bash +> docker pull gitea/gitea:latest +> docker compose up -d +> ``` + +Ziel dieses Abschnitts ist der Aufbau einer funktionsfähigen Actions-Umgebung mit einem eigenen **Self-Hosted Runner**, der deine Workflows im Homelab ausführt. + +### Schritt 1 – Voraussetzungen prüfen + +Bevor du Actions aktivierst, überprüfe: + +* Deine Gitea-Version ist **≥ 1.19**. + In der Weboberfläche unter **About** oder per CLI prüfen: + ```bash + docker exec -it gitea gitea --version + ``` +* Der Server hat Zugriff auf lokale oder interne Runner (HTTP erreichbar). +* Docker und Docker Compose laufen stabil. + +> [!TIP] +> Gitea Actions verwendet Runner, die containerisierte Jobs ausführen. +> Je nach Projekt kannst du sie auf demselben Host oder in einem separaten LXC-Container betreiben. + +### Schritt 2 – Actions aktivieren + +Actions sind standardmäßig deaktiviert. +Aktiviere sie über die Konfigurationsdatei `app.ini`: + +```bash +nano /gitea/gitea/conf/app.ini +``` + +Füge unter `[actions]` den folgenden Block hinzu: + +``` +[actions] +ENABLED = true +DEFAULT_ACTIONS_URL = https://gitea.com +``` + +Datei speichern und Container neu starten: + +```bash +docker compose restart +``` + +> [!NOTE] +> Die Angabe `DEFAULT_ACTIONS_URL` zeigt auf die Quelle für Standard-Workflows. +> Wenn du keine externen Templates nutzen möchtest, kannst du sie auch leer lassen. + +Nach dem Neustart ist im Repository-Menü der neue Tab **Actions** sichtbar. + +👉 **Screenshot geeignet:** Gitea-Repository mit sichtbarem Reiter „Actions“ + +### Schritt 3 – Self-Hosted Runner installieren + +Der Runner ist das lokale Programm, das die definierten Workflows ausführt. +Er kann auf demselben LXC wie Gitea oder auf einem separaten Node laufen. + +1. Wechsle auf deinen Ziel-Container oder Host: + ```bash + pct enter + ``` +2. Lade den Runner: + ```bash + mkdir -p /runner && cd /runner + curl -L -o gitea-runner https://dl.gitea.com/runner/latest/gitea-runner-linux-amd64 + chmod +x gitea-runner + ``` +3. Registrierung starten: + ```bash + ./gitea-runner register + ``` + Danach wirst du nach folgenden Angaben gefragt: + - **Gitea instance URL:** `https://git.deinedomain.tld` + - **Token:** generierst du im Gitea-Webinterface + → *Site Administration → Actions → Runner Tokens → Add New Token* + - **Runner name:** frei wählbar (z. B. `ucc-runner-01`) + - **Executor:** `shell` oder `docker` (empfohlen) +4. Dienst aktivieren: + ```bash + ./gitea-runner daemon & + ``` + +> [!TIP] +> Wenn du Docker im Runner nutzt, kannst du Build- oder Test-Container isoliert starten. +> Für einfache Automatisierungen reicht der `shell`-Modus. + +Nach erfolgreicher Registrierung erscheint der Runner unter +**Site Administration → Actions → Runners** mit Status **online**. + +👉 **Screenshot geeignet:** Gitea-Weboberfläche mit aktivem Runner (Status: online) + +### Schritt 4 – Test-Workflow anlegen + +Im Repository legst du unter `.gitea/workflows` eine YAML-Datei an: + +```yaml +# Datei: .gitea/workflows/test.yml +name: Test-Workflow + +on: [push] + +jobs: + check-setup: + runs-on: self-hosted + steps: + - name: Repository klonen + uses: actions/checkout@v3 + + - name: Testausgabe + run: echo "Gitea Actions läuft erfolgreich!" +``` + +Committe die Datei und pushe sie ins Repository: + +```bash +git add .gitea/workflows/test.yml +git commit -m "CI: Testworkflow hinzugefügt" +git push +``` + +> [!NOTE] +> Jeder Push löst automatisch den hinterlegten Workflow aus. +> Die Ausgabe kannst du direkt im Tab **Actions** ansehen. + +👉 **Screenshot geeignet:** Gitea-Workflow-Log mit erfolgreichem Joblauf + +### Schritt 5 – Erweiterung für reale Workflows + +Beispiel: Automatischer PDF-Build aus Markdown-Tutorials (analog zum UCC-Dokumentationsprozess): + +```yaml +name: Build Tutorials + +on: [push] + +jobs: + build-pdf: + runs-on: self-hosted + steps: + - uses: actions/checkout@v3 + - name: Pandoc installieren + run: apt update && apt install -y pandoc + - name: PDF erstellen + run: | + pandoc README.md -o tutorial.pdf + - name: Artefakt speichern + run: cp tutorial.pdf /srv/assets/projects/ +``` + +> [!TIP] +> Damit kannst du Markdown-Tutorials aus Gitea automatisch in dein Asset-LXC exportieren. +> Gitea, Runner und Asset-System arbeiten dadurch direkt zusammen. + +--- + +### Schritt 2 – n8n-Workflow aufbauen + +In diesem Abschnitt baust du einen voll funktionsfähigen Workflow, der automatisch reagiert, wenn in Gitea ein Push oder Release erfolgt. +Alle verwendeten Nodes sind in der kostenlosen n8n-Version enthalten. + +#### Node 1 – Webhook + +| Feld | Wert | +|------|------| +| **HTTP Method** | `POST` | +| **Path** | `git-ci` | +| **Response Mode** | `On Received` | +| **Response Data** | `{ "status": "received" }` | +| **Response Code** | `200` | + +Nach dem Speichern siehst du oben die **Webhook-URL**, z. B.: +``` +https://n8n.deinedomain.tld/webhook/git-ci +``` +Diese trägst du im Gitea-Webhook ein. + +> [!TIP] +> Der Node funktioniert sofort nach Speichern. +> Ein Test-Delivery in Gitea zeigt dir, ob n8n korrekt reagiert. + +#### Node 2 – Set (Daten reduzieren) + +Zweck: Nur die relevanten Felder aus dem JSON behalten. + +1. Verbinde den **Webhook** mit einem **Set**-Node. +2. Öffne den Node und wähle **Keep Only Set** → aktivieren. +3. Trage die folgenden Felder ein: + +| Name | Ausdruck | +|------|-----------| +| `repository` | `={{ $json["repository"]["full_name"] }}` | +| `event` | `={{ $json["action"] || $json["event_name"] }}` | +| `ref` | `={{ $json["ref"] }}` | +| `user` | `={{ $json["sender"]["login"] }}` | + +Speichern → **Execute Node** klicken → du solltest ein kompaktes JSON mit vier Feldern erhalten. + +#### Node 3 – Switch (Ereignis prüfen) + +1. Füge einen **Switch**-Node hinzu. +2. Verbinde ihn mit dem **Set**-Node. +3. Im Feld **Value to Compare**: + ``` + {{$json["event"]}} + ``` +4. Füge drei Cases hinzu: + +| Case Name | Wert | +|------------|-------| +| Push | `push` | +| Release | `release` | +| Workflow | `workflow_run` | + +Jetzt entscheidet der Node automatisch, welcher Zweig ausgeführt wird. + +#### Node 4 – SSH (Befehl ausführen) + +Dieser Node startet auf einem entfernten Server oder Container einen definierten Befehl. +Beispiel für automatische Aktualisierung eines Projekts bei Push. + +| Feld | Wert | +|------|------| +| **Host** | `10.0.0.20` | +| **Port** | `22` | +| **Username** | `deploy` | +| **Password / SSH Key** | entsprechend eintragen | +| **Command** | `cd /srv/project && git pull && systemctl restart app` | + +Speichern → über den **Switch-Zweig Push** verbinden. + +#### Node 5 – HTTP Request (Deployment oder Benachrichtigung) + +Beispiel für automatisches Triggern eines Deployments bei Release. + +| Feld | Wert | +|------|------| +| **Method** | `POST` | +| **URL** | `https://ucc-api.deinedomain.tld/deploy` | +| **Body Content Type** | `JSON` | +| **JSON/RAW Parameters** | `{"repo":"={{$json.repository}}","ref":"={{$json.ref}}"}` | + +Verbinde diesen Node mit dem **Switch-Zweig Release**. + +#### Node 6 – Discord (optional) + +Zum Senden von Statusmeldungen oder Benachrichtigungen. +Nutze den kostenlosen Standard-Discord-Node. + +| Feld | Wert | +|------|------| +| **Resource** | `Message` | +| **Operation** | `Create` | +| **Channel ID** | `123456789012345678` | +| **Text** | `=📦 Neues Event in {{$json.repository}} ({{$json.event}})` | + +Verbinde diesen Node mit allen Switch-Zweigen, falls du immer informiert werden möchtest. + +👉 **Screenshot geeignet:** kompletter n8n-Workflow von Webhook → Set → Switch → SSH/HTTP/Discord + +> [!NOTE] +> Alle hier genutzten Nodes sind Standard-Bestandteil der n8n Community Edition. +> Keine Cloud-Verbindung, keine Zusatzmodule nötig. +> Du kannst den gesamten Workflow exportieren, sichern und auf jedem n8n-System importieren. + +--- + +## Vaultwarden-Integration + +Damit deine Automatisierung sicher bleibt, verwaltet Vaultwarden alle Zugangsdaten, Tokens und Secrets zentral. +So liegen Passwörter und API-Keys nicht im Klartext in n8n oder Gitea, sondern werden nur bei Bedarf abgerufen. +Das schützt dein System vor versehentlichen Leaks oder unbefugtem Zugriff. + +> [!NOTE] +> Für diese Integration genügt der Standard-Vaultwarden-Container aus dem UCC-System. +> Es wird keine Erweiterung oder API-Plugin benötigt – die REST-API ist in jeder Installation verfügbar. + +### Ziel + +Du verknüpfst n8n mit Vaultwarden, um: +- das Webhook-Secret aus Gitea sicher zu speichern +- Zugriffsdaten für SSH oder API-Calls nur zur Laufzeit bereitzustellen +- CI-Prozesse automatisiert und trotzdem verschlüsselt auszuführen + +### Secret in Vaultwarden anlegen + +1. Öffne die Weboberfläche von Vaultwarden. +2. Klicke auf **+ Add Item** → Typ **Secure Note**. +3. Trage folgende Werte ein: + +| Feld | Beispiel | +|------|-----------| +| **Name** | `GITEA_WEBHOOK_SECRET` | +| **Folder** | `CI/CD` | +| **Notes** | dein Webhook-Secret aus Gitea | +| **Favorite** | optional aktivieren | + +4. Speichern. + Vaultwarden verschlüsselt das Secret automatisch. + Du kannst es später per API abrufen, ohne es jemals im Klartext zu sehen. + +👉 **Screenshot geeignet:** Vaultwarden-Interface mit angelegtem Secret `GITEA_WEBHOOK_SECRET` + +### API-Token für n8n erstellen + +Damit n8n auf Vaultwarden zugreifen darf, benötigt es ein Zugriffstoken. + +1. In Vaultwarden → **Settings → API Keys** +2. Auf **Generate New Key** klicken. +3. Einen Namen vergeben, z. B. `n8n-access`. +4. Optional Ablaufdatum setzen. +5. Key kopieren (er wird nur einmal angezeigt). + +> [!TIP] +> Der API-Key sollte **nur Lesezugriff** haben, wenn dein Vault mehrere Benutzer oder Secrets enthält. + +### Secret aus Vaultwarden in n8n abrufen + +In n8n fügst du vor sicherheitsrelevanten Schritten (z. B. SSH oder API-Call) einen **HTTP Request Node** ein, der das Secret abfragt. + +| Feld | Wert | +|------|------| +| **Method** | `GET` | +| **URL** | `https://vault.deinedomain.tld/api/secrets/GITEA_WEBHOOK_SECRET` | +| **Response Format** | `JSON` | +| **Authentication** | `Header Auth` | +| **Header Name** | `Authorization` | +| **Header Value** | `Bearer ` | + +Nach Ausführen erhältst du eine Antwort ähnlich: + +```json +{ + "data": { + "id": "123abc", + "type": "note", + "name": "GITEA_WEBHOOK_SECRET", + "notes": "meinSuperSecret123" + } +} +``` + +Im nächsten Node kannst du den Wert dynamisch verwenden: + +```js +={{ $json["data"]["notes"] }} +``` + +> [!TIP] +> Verwende dieses Secret z. B. im Webhook-Verification-Schritt, SSH-Node oder API-Aufruf. +> So bleibt der Schlüssel außerhalb des Workflows gespeichert und kann zentral rotiert werden. + +### Secret-Rotation automatisieren (optional) + +Vaultwarden unterstützt über die API das Ersetzen von Werten. +Damit kannst du in regelmäßigen Abständen neue Tokens oder Passwörter generieren und direkt im Vault ablegen. + +In n8n kombinierst du dazu: +- **Cron Node** (z. B. alle 30 Tage) +- **HTTP Request (PUT)** mit neuem Tokenwert +- **Discord Node** oder **Email Node** zur Benachrichtigung + +Beispiel für API-Request zur Aktualisierung: + +| Feld | Wert | +|------|------| +| **Method** | `PUT` | +| **URL** | `https://vault.deinedomain.tld/api/secrets/GITEA_WEBHOOK_SECRET` | +| **Body Content Type** | `JSON` | +| **JSON Body** | `{"notes":"{{ $json.newToken }}"}` | +| **Header Auth** | `Bearer ` | + +> [!IMPORTANT] +> Automatische Token-Rotation ist optional, aber sehr empfehlenswert, wenn dein System dauerhaft online ist. +> So stellst du sicher, dass alte oder kompromittierte Tokens keine Gefahr darstellen. + +👉 **Screenshot geeignet:** n8n-Workflow mit HTTP-Node zum Secret-Abruf vor einem SSH- oder API-Schritt + +Mit dieser Integration bleiben alle Zugangsdaten dezentral verwaltet, verschlüsselt gespeichert und jederzeit austauschbar. +Vaultwarden wird so zur zentralen Sicherheitsinstanz deiner gesamten Automatisierung im UCC. + +--- + +## Abschluss + +Mit der Erweiterung aus diesem Premium-Kapitel hast du aus einer einfachen Git-Verwaltung eine vollwertige Automatisierungsplattform gemacht. +Gitea arbeitet nun nicht nur als Code- und Dokumentenarchiv, sondern als aktiver Bestandteil deiner Produktions- und Streaming-Infrastruktur. +Durch Actions, n8n und Vaultwarden ist ein geschlossenes System entstanden, das Builds, Backups und Deployments selbstständig steuert – komplett lokal und unabhängig von externen CI-Diensten. + +Die Kombination aus **Self-Hosted Runnern** und **n8n-Webhooks** ermöglicht dir flexible Workflows: +Markdown-Dateien können automatisch in PDFs umgewandelt, Projektdaten gesichert oder Statusmeldungen an Discord gesendet werden. +Vaultwarden sorgt dabei dafür, dass sensible Daten nie im Klartext auftauchen und jederzeit zentral ausgetauscht werden können. + +> [!NOTE] +> Mit dieser Integration hast du die Grundlage geschaffen, um alle Projekte im UCC miteinander zu verknüpfen: +> Git speichert und versioniert, n8n führt Aktionen aus, Vaultwarden verwaltet die Secrets – +> zusammen bilden sie eine vollständig automatisierte Entwicklungs- und Betriebsumgebung. + +Ein korrekt eingerichtetes CI-System mit Gitea bietet dir: + +- Lokale, cloudfreie CI/CD-Pipelines +- Self-Hosted Runner für flexible Aufgabenverteilung +- Direkte Anbindung an n8n für Benachrichtigung, Backup oder Deployment +- Sichere Geheimnisverwaltung durch Vaultwarden +- Vollständige Kontrolle über Build- und Release-Prozesse + +👉 **Screenshot geeignet:** Gitea Actions-Tab mit laufendem Workflow und verknüpftem Runner + +Mit Abschluss dieses Kapitels hast du eine robuste, skalierbare und sichere Basis geschaffen, +auf der künftige Premium-Kapitel wie **automatische Dokumentverteilung**, **Build-Pipelines für UCC-Projekte** oder **integrierte Testumgebungen** direkt aufbauen können. +Gitea wird so zu einem der zentralen Werkzeuge im UCC – effizient, transparent und vollständig unter deiner Kontrolle. \ No newline at end of file