Lokales CI/CD für den Raspberry Pi: Automatisierung von Docker-Compose-Deployments
Teil 4 von 4 der Reihe Homelab auf dem Raspberry Pi
Inhalt
Die Verwaltung von Container-Infrastrukturen auf Edge-Geräten wie einem Raspberry Pi ist im Alltag oft mit wiederholten manuellen SSH-Sitzungen, händischen Image-Downloads und dem direkten Ausführen von Docker-Compose-Befehlen verbunden. Der Wechsel zu einer lokalen CI/CD-Pipeline automatisiert den gesamten Lebenszyklus selbstgehosteter Anwendungen – darunter Home Assistant, Nextcloud und maßgeschneiderte Python-Skripte – mit Git-Repositories, Webhook-Listenern und lokalen Deploy-Agenten.
1. Architektur von lokalem GitOps auf Edge-Hardware
Die Einführung eines GitOps-Konzepts verlagert die zentrale Datengrundlage sämtlicher Infrastrukturkonfigurationen vom lokalen Dateisystem in ein zentrales Git-Repository. Anstatt YAML-Dateien direkt auf dem System zu modifizieren, werden alle Bereitstellungsdefinitionen in der Versionskontrolle gepflegt.
- Deklarative Konfiguration: Sämtliche Dienste, Netzwerkdefinitionen und persistenten Speicherinhalte werden klar strukturiert in
docker-compose.yml-Dateien innerhalb eines Git-Repositories abgebildet. - Nachvollziehbarkeit & Rollbacks: Die Versionskontrolle bietet eine lückenlose Historie aller Konfigurationsänderungen, was im Fehlerfall ein sofortiges Zurücksetzen auf einen stabilen vorherigen Zustand ermöglicht.
- Wartungsfreier Betrieb: Der Edge-Server agiert als kontinuierlicher Abnehmer des Repository-Zustands, wodurch manuelle Shell-Eingriffe bei Standard-Updates entfallen.
2. Automatisierte Deployments über Webhook-Listener
Um manuelle SSH-Befehle vollständig abzulösen, können ressourcenschonende Webhook-Server (wie adnanh/webhook oder spezialisierte Automatisierungsdienstprogramme) direkt auf dem Raspberry Pi installiert werden. Diese Dienste empfangen eingehende HTTP-POST-Signale, die durch Push-Ereignisse im Code-Repository oder durch externe CI/CD-Systeme ausgelöst werden.
Ablauf der Webhook-Ausführung
- Validierung der Anfragen: Eingehende Webhook-Aufrufe werden kryptografisch über HMAC-Schlüssel auf Authentizität geprüft, um unbefugten Zugriff zu verhindern.
- Automatischer Git-Abruf: Nach erfolgreicher Prüfung startet der Hintergrunddienst einen Aktualisierungsprozess, um das lokale Arbeitsverzeichnis auf den Stand des externen Hauptbranches zu bringen.
- Rekonvergenz der Container: Der Ausführungsdienst startet den Befehl
docker compose up -d --remove-orphans, sodass ausschließlich veränderte Container-Images oder angepasste Konfigurationen neu erstellt werden.
3. Lebenszyklus-Management ohne SSH
Architekturen für die kontinuierliche Bereitstellung im Self-Hosting-Bereich profitieren von lokalen Agenten, die Container-Registries überwachen und die Erneuerung von Containern vollautomatisch durchführen.
- Automatisierte Überwachung von Image-Registries: Werkzeuge aus der Watchtower-Familie prüfen regelmäßig Image-Digests aktiver Container und starten Dienste automatisch neu, sobald aktuelle Builds bereitstehen. Das ursprüngliche Repository
containrrr/watchtowerwurde im Dezember 2025 archiviert, das ältere Projekt Ouroboros wird nicht mehr entwickelt; gepflegte Community-Forks wienickfedor/watchtowerlassen sich als direkter Ersatz einsetzen. - Lokale Build-Automatisierung: Für eigene Python-Anwendungen oder Mikroservices können Build-Prozesse per Dockerfile direkt auf der ARM-Architektur ausgeführt werden, um komplexe Cross-Compilation-Schritte zu vermeiden.
- Health Checks & automatische Wiederherstellung: Die Integration nativer Docker-Health-Checks stellt sicher, dass fehlerhafte Aktualisierungen umgehend identifiziert werden, ohne dass manuelle Log-Analysen erforderlich sind.
4. Sicherheitsaspekte für lokale CI/CD-Pipelines
Die Bereitstellung automatisierter Endpunkte im lokalen Netzwerk erfordert eine strikte Rechteentflechtung. Webhook-Dienste sollten niemals mit Root-Berechtigungen ausgeführt werden; stattdessen ist der Zugriff auf den Docker-Socket über dedizierte Gruppenrechte oder schreibgeschützte Socket-Proxys zu reglementieren. Zudem schützt ein restriktives Management-VLAN die Automatisierungs-Dienste vor unautorisierten Zugriffen aus anderen Subnetzen.
Quellen
Homelab auf dem Raspberry Pi
- Raspberry Pi 4 und 5: Vom SSD-Laufwerk booten über den Bootloader
- Unterbrechungsfreie Stromversorgung (USV) für Raspberry Pi 4 und 5: Die Top 5 Lösungen für anspruchsvolle Setups
- Automatisierte Docker-Deployments auf dem Raspberry Pi: Local-First Dev Environments
- Lokales CI/CD für den Raspberry Pi: Automatisierung von Docker-Compose-Deployments
Passend dazu
2 Kommentare
Der Gedanke, dass das Gerät den Zustand selbst abholt statt bespielt zu werden, nimmt der ganzen Kette den heikelsten Teil — es muss nichts von aussen hineinreichen.
Zur Ausführung habe ich eine Frage:
docker compose up -d --remove-orphansbei jedem Push klingt gründlich, aber auch riskant. Was passiert mit Containern, deren Abbild sich nicht geändert hat, und was mit den Datenträgern?Compose vergleicht die gewünschte Beschreibung mit dem laufenden Zustand und fasst nur an, was abweicht. Gleiches Abbild und gleiche Definition heisst: Der Container läuft weiter, ohne Neustart. Datenträger bleiben ohnehin bestehen, weil sie nicht Teil des Container-Lebenszyklus sind — dafür bräuchte es
--volumes, und genau deshalb steht es hier nicht.Aufmerksamkeit verdient
--remove-orphans. Es entfernt Container, die dieses Compose-Projekt einmal angelegt hat und die in der Datei nicht mehr stehen. Das ist gewollt, solange der Projektname stabil ist. Ändert er sich — ein umbenanntes Verzeichnis genügt —, gelten die alten Container als fremd und bleiben stehen, während die neuen daneben starten.Der umgekehrte Fall ist der teurere: Liegen zwei Projekte im selben Verzeichnis oder teilen sie sich versehentlich einen Namen, räumt der Lauf die Container des jeweils anderen ab. Deshalb gehört der Projektname ausdrücklich gesetzt (
name:in der Compose-Datei oder-pim Aufruf) und nicht dem Verzeichnisnamen überlassen.