Wer meinenletzten Beitrag zum Homelab Setup 2025 gelesen hat, weiß dass ich dortKomodo (externer Link) als GitOps-Werkzeug für meine Docker Compose Stacks einsetze. Das Prinzip dahinter ist gut: Git als Single Source of Truth, Renovate für automatische Version-Updates, und bei einem neuen Commit deployed Komodo die Änderungen auf das Zielsystem. Funktioniert im Grunde auch – aber Komodo hat mich mit einer Sache regelmäßig zur Weißglut gebracht: File Permissions. Das funktioniert einfach nicht konsistent. Entweder stimmen die Berechtigungen auf dem Host nicht, oder Komodo meckert beim Deployment, oder irgendwas dazwischen. Nach dem x-ten Mal hatte ich genug und wollte eine schlankere Lösung.

Die Anforderung ist dabei überschaubar: Wenn Renovate einen neuen Commit in das Repo pusht (nach meinem Merge des Pull Requests), soll die compose-Datei auf dem Server aktualisiert und die betroffenen Container neu gestartet werden. Kein Kubernetes, kein weiteres Framework. Einfach git pull und docker compose up.

Das Grundprinzip

Das Setup basiert auf drei Komponenten die zusammenspielen:

1. Gitea (externer Link) – mein selbst gehosteter Git-Server, auf dem die Compose-Dateien liegen
2. Renovate (externer Link) – überprüft alle vier Stunden per Cronjob die verwendeten Image-Tags gegen die jeweiligen Container-Registries und öffnet bei neuen Versionen automatisch Pull Requests. Ich merge den PR, der Commit landet aufmain.
3. webhook (externer Link) – ein einzelnes Go-Binary, das auf dem Zielserver einen HTTP-Endpunkt bereitstellt. Gitea feuert bei jedem Push einen Webhook dorthin, woraufhin das Deploy-Script ausgeführt wird.

Der Datenfluss sieht so aus:

Renovate erkennt neues Image-Tag
→ PR in Gitea
→ Merge
→ Gitea feuert Webhook
→ webhook-Binary ruft deploy.sh auf
→ git pull + docker compose up -d

Kein Polling, kein Daemon der irgendwelche Container-Registries beobachtet, kein Framework das eigene Meinungen zu File Permissions hat.

Warum nicht einfach Watchtower oder ein Cron-Script?

Bevor ich zu webhook gegriffen habe, hatte ich kurz zwei andere Ansätze im Kopf.

Watchtower (externer Link) überwacht laufende Container und zieht neue Images automatisch. Das Problem: Watchtower reagiert auf neue Images in der Registry, nicht auf Git-Commits. Wenn Renovate einen PR öffnet und ich den merge, hat Watchtower davon keine Ahnung – der zieht einfach irgendwann wenn er selbst nachschaut. Das passt nicht zu einem Setup bei dem Git die einzige Quelle der Wahrheit sein soll. Außerdem will ich den Merge-Zeitpunkt kontrollieren, nicht Watchtower.

Cron-Script mitgit fetch wäre die andere Möglichkeit – alle paar Minuten nachschauen ob es Änderungen gibt und dann deployen. Funktioniert, hat aber einen konzeptionellen Nachteil: Es ist Polling. Ich baue mit Gitea bereits eine Infrastruktur auf die Push-Events liefern kann, die sollte ich auch nutzen. Ein Webhook reagiert innerhalb von Sekunden, ein Cron-Job mit 5-Minuten-Intervall verzögert unnötig.

webhook ist der sauberste Weg: Event-getrieben, kein Extra-Daemon, ein einzelnes Binary ohne Abhängigkeiten.

Repo-Struktur

Ich habe pro Server ein eigenes Repository:

• apps-stack für dendocker01 – dort laufen Tools wiePaperless-ngx (externer Link) ,Immich (externer Link) ,Vaultwarden (externer Link) und ähnliches
• media-stack für denmedia01 – dort leben alle*arr-Container und was sonst noch zum Medien-Stack gehört

Jedes Repo enthält einfach diecompose.yaml sowie ggf. weitere Konfigurationsdateien die einzelne Anwendungen benötigen. Nichts Besonderes.

Renovate in den Repos

Renovate läuft selfhosted und überprüft per Cronjob alle vier Stunden die Image-Tags in den Compose-Dateien. Dafür reicht eine minimalerenovate.json im Repo-Root:

{"$schema":"https://docs.renovatebot.com/renovate-schema.json","extends": ["config:base"],"docker-compose": {"enabled":true }}

Renovate erkennt dann automatisch die Image-Tags in der Compose-Datei und öffnet PRs wenn eine neuere Version verfügbar ist. Bei Software die semantische Versionierung verwendet (alsomajor.minor.patch) lässt sich das besonders fein steuern – z. B. nur Patch-Updates automatisch mergen, bei Minor-Updates erst schauen was sich geändert hat.

Für Postgres-Container würde ich Renovate übrigens ausschließen. Major-Upgrades zwischen Postgres-Versionen erfordern einen manuellen Datenbankdump und -import, das soll mir kein Bot automatisch reinschießen.

webhook installieren und konfigurieren

webhook gibt es als einzelnes Binary, alternativ auch als Paket:

apt install webhook

Die Konfiguration liegt unter/etc/webhook/webhook.conf:

-id:deployexecute-command:/opt/scripts/deploy.shcommand-working-directory:/opt/media-stacktrigger-rule:match:type:payload-hmac-sha256secret:"{{getenv \"WEBHOOK_SECRET\"}}"parameter:source:headername:X-Gitea-Signature

Ein paar Anmerkungen dazu:

Header-Name: Gitea schickt die Signatur alsX-Gitea-Signature – ohne-256-Suffix und ohnesha256=-Präfix im Wert. Das klingt trivial, hat mich aber beim ersten Versuch einen Debugging-Durchgang gekostet.

Secret als Umgebungsvariable: Das HMAC-Secret gehört nicht im Klartext in die Konfigurationsdatei, erst recht nicht wenn die Datei im Repo versioniert ist. Deshalb wird es pergetenv aus der Umgebung gelesen.

Das Secret generieren:

openssl rand -hex32

Und in eine Secrets-Datei schreiben die nur root lesen kann:

# /etc/webhook/secrets.envWEBHOOK_SECRET=dein-generierter-string

chmod600 /etc/webhook/secrets.env

Systemd-Unit

# /etc/systemd/system/webhook.service[Unit]Description=Webhook ReceiverAfter=network.target[Service]User=teqqy # Hier den eigenen Usernamen eintragenEnvironmentFile=/etc/webhook/secrets.envExecStart=/usr/bin/webhook -hooks /etc/webhook/webhook.conf -port 9000Restart=on-failure[Install]WantedBy=multi-user.target

User=teqqy sorgt dafür dass der webhook-Daemon und damit auch das Deploy-Script nicht als root laufen. Das ist mir wichtig – Prozesse die nur git pull und docker compose up ausführen müssen haben nichts als root verloren. Den Usernamen natürlich durch den eigenen ersetzen; der User braucht Zugriff auf das Repo-Verzeichnis und muss Mitglied derdocker-Gruppe sein.

EnvironmentFile lädt diesecrets.env und stelltWEBHOOK_SECRET als Umgebungsvariable bereit, bevor der Prozess startet – so kommt das Secret sauber in dengetenv-Aufruf der Konfiguration.Restart=on-failure sorgt dafür dass der Daemon bei einem unerwarteten Absturz automatisch neu startet, ohne dass man manuell eingreifen muss.

systemctl enable --now webhook

Gitea Webhook einrichten

In Gitea unterRepository → Einstellungen → Webhooks → Webhook hinzufügen → Gitea:

• Ziel-URL:http://media01.example.com:9000/hooks/deploy
• Secret: denselben String den du oben generiert hast
• Trigger: NurPush-Events reichen aus

Gitea berechnet bei jedem Push automatisch eine HMAC-SHA256-Signatur über den Request-Body und schickt sie alsX-Gitea-Signature-Header mit. Das webhook-Binary verifiziert die Signatur bevor es das Script ausführt – ein simpler Authorization-Header wäre hier deutlich unsicherer, weil man den Payload damit nicht gegen Manipulation absichert.

Port 9000 sollte nicht direkt ins Internet exponiert sein. In meinem Setup sind Gitea und der webhook-Daemon im selben internen Netz, der Port ist von außen nicht erreichbar. Wer den Endpunkt für eine externe Gitea-Instanz oder GitHub erreichbar machen muss, sollte das zumindest hinter einem Reverse Proxy mit IP-Beschränkung tun.

Das Deploy-Script

#!/bin/bashset -euo pipefailREPO=/opt/media-stackLOG=/opt/deploy-logs/deploy-$(date +%Y%m%d-%H%M%S).logexec >>"$LOG" 2>&1echo"=== Deploy$(date) ==="cd"$REPO"git pull origin maindocker compose up -d --remove-orphansdocker compose psecho"=== Done ==="

set -euo pipefail sorgt dafür dass das Script bei jedem Fehler sofort abbricht und einen Exit-Code ≠ 0 zurückgibt. Den loggt webhook dann ebenfalls, sodassjournalctl -u webhook bei Problemen der erste Anlaufpunkt ist.

Das Log-Verzeichnis muss dem ausführenden User gehören:

mkdir -p /opt/deploy-logschown teqqy:teqqy /opt/deploy-logs

Stolpersteine die ich unterwegs getroffen habe

.git-Verzeichnis Ownership: Wenn das Repo irgendwann mal als anderer User geklont oder gepullt wurde, verweigert Git den Zugriff mit einer Warnung zu “dubiosen Besitzverhältnissen”. Fix:

chown -R teqqy:teqqy /opt/media-stack/.git

safe.directory: In manchen Setups hilft zusätzlich:

git config --global --add safe.directory /opt/media-stack

/var/log Permissions: Der ausführende User hat dort keine Schreibrechte. Deshalb das Log-Verzeichnis in einen Pfad legen der dem User gehört – ich nutze/opt/deploy-logs.

*arr-Container und UID/GID: Meine*arr-Container laufen mit99:100 (Unraid-kompatibel wegen NFS). Beim allerersten Deployment legt Docker die Bind-Mount-Verzeichnisse mit1000:1000 an wenn sie noch nicht existieren. Einmalig vor dem ersten Start:

chown -R 99:100 /mnt/data/arr/

Danach ist das kein Thema mehr da die Verzeichnisse bereits existieren.

Monitoring

Ich setzeUptime Kuma (externer Link) ein und beobachte dort ob die Container nach einem Deployment noch sauber laufen. Das reicht für meinen Use Case: Wenn ein Container nach einem fehlgeschlagenen Update nicht mehr antwortet, schlägt Uptime Kuma an. Das deploy.log undjournalctl -u webhook liefern dann die Details warum es schiefgelaufen ist.

Ein Dead-Man’s-Switch (z. B. über Healthchecks.io) wäre der nächste sinnvolle Schritt wenn man auch merken will wenn ein Deploy einfachausbleibt – aber für einen Media-Stack ist das für mich nicht kritisch genug um extra Aufwand zu treiben.

Fazit

Das Setup ist jetzt seit kurzem in Betrieb und macht genau was es soll – ohne dass ich irgendwas an Komodo debuggen muss. Das webhook-Binary ist stabil, der Deployment-Flow ist deterministisch, und der Gesamtoverhead beschränkt sich auf ein paar Konfigurationsdateien und ein Shell-Script.

Wer ähnliche Anforderungen hat und kein Kubernetes betreiben möchte: Das ist meiner Meinung nach der pragmatischste Weg. Keine Magie, keine Frameworks, kein Overengineering. Nur git pull und docker compose up.

Bei Fragen oder Anmerkungen erreichst du mich über die Links in der Menüleiste.

Wie Menschen die mir auf social media folgen wissen, betreibe ich einen kleinenKubernetes Cluster im GitOps Prinzip. Meinevollständige Konfiguration (externer Link) befindet sich auf der Cloud Plattform GitHub und kann dort von allen eingesehen werden. Dazu setze ich auf eine saubere Versionverwaltung beim Update der Container. Das hilft um schnell auf eine alte Version zurück zu springen. Da ich mich nicht selbst um das heraussuchen der neusten Versionen kümmern möchte, nutze ichRenovate (externer Link) als App bei GitHub. Diese schaut in die verschiedenen Dateien und vergleicht die konfigurierte Version eines Containers mit der zuletzt veröffentlichten und erstellt daraus ein pull request.

Im Standard sind alle Labels bei den Plattformen wie GitHub, Gitlab odergitea (externer Link) in grau gehalten. Hier fehlt also etwas die Übersicht zur schnelleren Einschätzung der Situation. Aus diesem Grund verwende ich ein kleinen Workflow der mir die von Renovate angehäfteten Labels bunt einfärbt. Ich nutze das Vorgehen auf GitHub, sollte aber fast identisch auch bei GitLab oder gitea funktionieren.

Ich gehe davon aus, dass es bereit ein vorhandenes Repository gibt und sich dies lokal auf deiner Workstation befindet. Entsprechend erstellen wir im Hauptverzeichnis des Repos einen Unterordner mit dem Namen.github. Auf anderen Plattformen sollte er analog zur Plattform heißen.

In diesem Unterordner erstellen wir einen weiteren Order mit dem Namenworkflows. Sämtlichey(a)mlDateien werden hier als eingenständiger Workflow auf der jeweiligen Plattform aufgeführt.

Nun können wir auch den Workflow bzw. GitHub Action anlegen. Ich habe sie bei mirlabel-sync.yaml genannt und folgendes in die Datei kopiert:

---# yaml-language-server: $schema=https://json.schemastore.org/github-workflow.jsonname:"Label Sync"on:workflow_dispatch:push:branches:["main"]paths:[".github/labels.yaml"]jobs:label-sync:name:Label Syncruns-on:ubuntu-lateststeps:-name:Checkoutuses:actions/checkout@v4with:sparse-checkout:.github/labels.yaml-name:Sync Labelsuses:EndBug/label-sync@v2with:config-file:.github/labels.yamldelete-other-labels:true

Glücklicherweise brauchen wir hierfür ein Bot oder ähnliches, sondern es funktioniert direkt. Wie du gegebenenfalls in dem workflow siehst, verweisen wir auf eine Datei mit dem Namenlabels.yaml. Diese müssen wir noch in dem Ordner.github anlegen und befüllen.

In diese Datei kommen dann sämtliche Labels mit dem entsprechenden HTML-Farbcode. Bei mir sieht die Datei so aus:

---# Areas-name:area/ansiblecolor:"0e8a16"-name:area/docscolor:"0e8a16"-name:area/githubcolor:"0e8a16"-name:area/kubernetescolor:"0e8a16"-name:area/terraformcolor:"0e8a16"# Clusters-name:cluster/maincolor:"ffc300"-name:cluster/storagecolor:"ffc300"# Renovate Types-name:renovate/ansiblecolor:"027fa0"-name:renovate/containercolor:"027fa0"-name:renovate/github-actioncolor:"027fa0"-name:renovate/grafana-dashboardcolor:"027fa0"-name:renovate/github-releasecolor:"027fa0"-name:renovate/helmcolor:"027fa0"-name:renovate/terraformcolor:"027fa0"# Semantic Types-name:type/digestcolor:"ffeC19"-name:type/patchcolor:"ffeC19"-name:type/minorcolor:"ff9800"-name:type/majorcolor:"f6412d"# Uncategorized-name:holdcolor:"ee0701"

Wir können jetzt unsere Änderungen commiten und pushen. Beim nächsten push wird dann der Workflow angestoßen und ausgeführt. Nun sollten alle Labels die ihr als Issue oder Pull Request habt in der entsprechenden Farbe dargestellt werden. Bei mir sieht das z. B. so aus: ]]>githubgitlabgitearenovate