CI/CD on Schallberts Blog

Giteas act_runner rootless: Startprobleme

Schallbert — Sat, 28 Mar 2026

Das Fehlerbild

Mein docker-in-docker (DinD) act_runner stürzt kurz nach dem Start mit folgender Fehlermeldung ab:

Issue-Ticket bei Gitea

In der Gitea-Community (issue #721) habe ich ein Ticket für das Problem angelegt. Im Folgenden gehe ich auf eigene Erkenntnisse ein und fasse die Diskussion etwas zusammen.

Problem mit Kernel-Berechtigungen?

Der act_runner muss bei der Docker-in-Docker Konfiguration selbst einen eigenen Docker Daemon betreiben. Nur so kann der Runner für die Actions eigene Container erstellen. Dies ist aus Sicherheitsgründen erst einmal nicht erlaubt.

Warum Container keine Container starten dürfen

Im Kontext des act_runner führt eine Action Code aus, der selbst Teil des Repository ist. Wird unbemerkt Schadcode in die Action eingeschleust, z.B. von einem “Collaborator”, so kann dieser bei einer Docker-Installation ohne DinD über den unter Umständen mit root-Rechten ausgestatteten Docker-Daemon dockerd direkt auf das Hostsystem durchgreifen.

Auswirkungen, falls trotz DinD etwas schief geht

Bei Anwendung des DinD-Konzeptes kann dies bei einem Angriff lediglich zum Zugriff auf den dockerd innerhalb des act_runner Containers führen - und das nur, wenn die Action nicht sauber gekapselt ist. Immer noch nicht gut, aber vertretbar: Bei Neustart des Containers ist der Status quo ante wiederhergestellt. Durchgriff auf das Hostsystem besteht allenfalls indirekt dadurch, dass der Container selbst mit sämtlichen Kernel-Features ausgestattet ist.

Einfache Lösung: DinD-Container `privileged` starten

Um dem DinD-Container jetzt die Möglichkeit zu geben eigene Actions aufzusetzen, kann in der Konfiguration privileged: true gesetzt werden. Damit werden dem Container alle Kernel-Fähigkeiten eingeräumt. Dies ist laut (dem hervorragend gemachten) OWASP Security Cheat Sheet möglichst zu vermeiden. Sollte act_runner nun selbst angegriffen werden oder kritische Sicherheitslücken offenbaren, hätte der Eindringling auf diese Weise bereits alle Möglichkeiten, der Kapselung vor dem Host-System zu entgehen.

Will man den einfachen Weg gehen, sieht die entsprechende docker-compose.yml wie folgt aus.

# docker-compose.yml
# section ACT_RUNNER
runner:
 image: gitea/act_runner:latest-dind-rootless
 container_name: gitea-runner
 privileged: true
# [...]

“And remember: Do not run containers with the –privileged flag!!!” - OWASP’s Docker Security Cheat Sheet, 2026 License

Sackgasse: Nur unbedingt benötigte Rechte vergeben

Nach kurzer Recherche finde ich einen Artikel auf CodeStudy.net¹, welcher sich mit dem Thema DinD beschäftigt. Hieraus bastele ich Änderungen in meiner docker-compose.yml zusammen.

Meine Vorgehensweise:

Änderungen in docker-compose.yml vornehmen
Service neu starten docker compose restart <service>
Logs anschauen docker logs --tail 100 <container-name>
Falls gestartet: Programm laufen lassen web-app->repo->jobs->rerun_all-jobs
Bei Fehlschlag: Wiederholen

Ich beginne mit wenigen, aber sehr mächtigen Rechten. Nach ein paar Iterationen erhalte ich:

# docker-compose.yml
# section act_runner DinD-rootless
runner:
 image: gitea/act_runner:latest-dind-rootless
 container_name: gitea-runner
 privileged: false
 cap_add:
 - SYS_ADMIN
 security_opt:
 - no-new-privileges:true
 - apparmor:unconfined 
 - systempaths=unconfined
 - writable-cgroups=true
# [...]

Aber noch immer fehlen mir Rechte, die außerhalb von Kernel-Privilegien und Sicherheitszonen liegen: Der Docker-Daemon möchte auf sysfs und proc, also Systemdateiverzeichnisse und -Prozesse zugreifen können.

level=warning msg="[rootlesskit:child ] failed to mount sysfs, falling back to read-only mount: operation not permitted"

Das kann ich selbst mit cap_add: ALL nicht ausgleichen. Zudem wird die Quellenlage im Internet auf dieser technischen Ebene echt dünn (und ich bin kein Docker-Spezialist). Ein Re-Mount der Dateisysteme könnte hier noch helfen; das erscheint mir aber zu experimentell und fehleranfällig.

Nach weiteren Stunden Recherche und Trial-and-Error auf meinem Server muss ich @tianon in einer Diskussion auf Github zustimmen: Der Docker Daemon benötigt so viele Rechte und Fähigkeiten, dass man gleich bei privileged: true bleiben kann und sich nicht mit einer Armada an CAP_ADD und System-bind-mounts herumschlagen muss.

Zukünftige Lösung: Virtualisierung oder Daemonless

Doch es gibt möglicherweise bessere Lösungen: Eigene Container-Laufzeitumgebungen wie Sysbox. Die Box hat selbst auf dem Hostsystem keine besonderen Rechte, ähnlich wie in einer virtuellen Maschine scheint sie in ihr laufenden Applikationen aber alle Rechte und Fähigkeiten zur Verfügung stellen zu können.

Installation und Inbetriebnahme bis hin zu funktionierenden Job-Containern führt für diesen Post zu weit. Daher muss ich vorerst auf andere Quellen verweisen.

Auch das Umschwenken von Docker auf Podman ist eine mögliche Lösung: Podman ist Daemonless, rootless und bietet ähnlichen Funktionsumfang wie Docker. Ein Umzug nach Podman wäre für mich ein eigenes Projekt und passt nicht in den Kontext dieses Posts.

Linux Security Modules (seccomp, AppArmor, SELinux)

Begriffsklärung: LSM ermöglichen verschiedene Sicherheitsprüfungen und -Sperren auf Kernelebene. Durch “Mandatory Access Control” können Sicherheitserweiterungen wie AppArmor Kernel-Fähigkeiten für einzelne Anwendungen steuern und Zugriffe falls nötig sperren.

Apparmor

Ich betreibe meinen Server (VPS) mit Ubuntu. Dieses Betriebssystem hat in den aktuelleren Versionen “user namespace creation restrictions” in AppArmor integriert, was das Betreiben von appimages, WebApps und eben auch Containers mit höheren Rechten verhindert.

“Unprivileged user namespaces are a feature in the Linux kernel […]; it enables unprivileged users to gain administrator (root) permissions within a confined environment […]” - mbelair, Ubuntu Discourse, as of May-2026, Ubuntu Discourse Website

Kurzgesagt wurde dieses Werkzeug als security-hardening-Maßnahme entwickelt, um Angriffsfläche auf dem Host-System bei Ausführung von Programmen zu reduzieren, die höhere Rechte erfordern.

Einfache Lösung: Komplett abstellen

Die Dampfhammermethode stellt das Feature für Benutzernamensräume komplett kalt. Wir teilen AppAmor mit, dass Drittprogramme wie in alten Betriebssystemversionen auch ohne Einschränkungen Kernel-Features oder höhere Rechte nutzen dürfen. Den zugehörigen Befehl habe ich aus dem askubuntu-Forum entliehen.

Er schaltet die Einschränkung von Nicht-Admin-Benutzernamensräumen (die Übertragung ins Deutsche tut schon fast weh) für diese Sitzung ab, indem er die Kernelparameter zur Laufzeit umschreibt (-w).

schallbertTestsThis@machine:~# sudo sysctl -w kernel.apparmor_restrict_unprivileged_userns=0

Ich halte den Befehl zur Fehlersuche für sehr hilfreich. Möchte man herausfinden, ob das gewünschte Programm wegen AppArmor nicht startet:

Obiges Kommando eingeben
das Drittprogramm, den Container etc. testen
durchbooten. Oder den Befehl mit =1 eingeben. Danach ist der Ursprungszustand wiederhergestellt.

Möchte man diese Verwundbarkeit permanent erhalten, so gibt man ein:

makeVulnerability@machine:~# echo 'kernel.apparmor_restrict_unprivileged_userns = 0' | sudo tee /etc/sysctl.d/20-apparmor-donotrestrict.conf
makeVulnerability@machine:~# sudo shutdown -r now

Dies alleine stellt noch keine Sicherheitslücke dar. Es ist jetzt nur prinzipiell einfacher geworden, eventuelle Schwächen im Kernel auszunutzen und der “Sandbox” des Containers zu entrinnen.

Richtige Lösung: Für jede Anwendung justieren

Es gibt Anwendungen (wie meine DinD-Version von act_runner), die benötigen zwingend erweiterte Rechte um ordnungsgemäß zu funktionieren. Und nur diese sollten die Möglichkeit erhalten, Nicht-Admin-Benutzernamensräume zu erhalten.

Docker selbst hat AppAmor einen Abschnitt in der Dokumentation gewidmet. Um zur Lösung für den DinD-Runner zu gelangen, benötigt es eine Transferleistung (danke, @thespad). Zur Wiederholung nochmal die Fehlermeldung von oben:

gitea-runner | [rootlesskit:parent] error: failed to start the child: fork/exec /proc/self/exe: operation not permitted
gitea-runner | s6-svwait: fatal: some services reported permanent failure or their supervisor died

Das Logfile sagt aus, dass der parent (Docker-Daemon im Container) sein child (Runner-Container) nicht starten kann, weil er für andere Teilnehmer (fork) selbst keine Prozesse (/proc/self) erstellen kann. Wer ist der User dieses Daemons? rootlesskit. Genau hier hakt unsere Lösung ein: Wir müssen in der docker-compose.yml das AppArmor-Profil für rootlesskit im DinD-Container des act_runner freigeben.

# docker-compose.yml
# section act_runner DinD-rootless
runner:
 image: gitea/act_runner:latest-dind-rootless
 container_name: gitea-runner
 privileged: true
 security_opt:
 - apparmor=rootlesskit
 # [...]

Entsprechend gut sieht jetzt auch das Logfile aus. Fertig!

Ich habe das Gefühl, dass jener Post mit “KI” geschrieben wurde. Wenn es konkret wird und es um “critical volume mounts” geht, stehen dort nämlich keine echten System-Pfade mehr und der Artikel wird insgesamt so vage, dass ich den Ratschlägen folgend gar nicht bis zum Ziel komme. ↩︎

Jekyll-dockerimage: Bundler und Gemfile

Schallbert — Fri, 14 Nov 2025

Was ist bundler?

Bundler ist ein Werkzeug, mit dem Abhängigkeiten zwischen Modulen und Bibliotheken in der Programmiersprache Ruby verwaltet und versioniert werden können. Ich benutze Bundler-Kommandos regelmäßig, z.B. um meinen Blog zu bauen und auf dem Server live zu stellen.

Will ich lokal bauen, so tippe ich beispielsweise

bundle exec jekyll serve --incremental --future

in die Konsole. Dieser Befehl sagt Bundler, es soll die Applikation jekyll im Server-Modus ausführen und ihr Parameter mitgeben, welche jekyll nicht bei jeder Dateiänderung komplett neu bauen lässt und noch nicht veröffentlichte Seiten dennoch mit erstellt.

bundler in der CI-Pipeline

Auch für die Veröffentlichung meiner Seite nutze ich Bundler als Teil eines Jekyll-Dockerimages, wie bereits öfters auf meiner Seite verlinkt, z.B. bei der Umstellung auf self-hosted. Seit ich auf eine neue Version der Blog-Software umgestiegen bin, sehe ich in meiner CI-Pipeline rätselhafte Fehler. Lokal baut das System jedoch einwandfrei. Wie man solche Fehler angeht und behebt, habe ich hier festgehalten.

“There was an error while trying to write to /path/to/Gemfile.lock” - CI console output

Keine Schreibrechte

Bundler selbst kann auf meiner CI wie der Jekyll-user auch nur Dateien lesen und nicht schreiben. Was ich für den Jekyll output mit chown beheben kann, möchte ich bundler aber gar nicht erlauben: Ich will ja gerade, dass Gemfile.lock zwischen meiner lokalen Bauumgebung und der CI identisch bleibt, damit ich mögliche Fehler schon vorab beheben kann.

Spezifikationsdatei für bundler

In der Datei Gemfile.lock stehen alle Abhängigkeiten der verwendeten Applikation drin, inkl. Versionsnummer und Bezugsquelle. Wird nur der Quellcode der Anwendung plus diese Datei geliefert, so kann bundler eine konkrete Version aller Abhängigkeiten beim Bauen ziehen, sodass unabhängig von Maschine und Version mit ähnlichen Voraussetzungen gearbeitet werden kann.

Fehlerbehebung

Ein erster Versuch der Behebung durch Angleichung sämtlicher Versionen zwischen lokal und CI schlug fehl. Der zweite Versuch, dem Jekyll-user Schreibrechte auf die Gemfile.lock zu geben, schlug ebenfalls fehl. Der dritte Versuch führte mich zur Bundler-Website, wo ich die Parameter genauer unter die Lupe nahm, Stichwort “frozen”.

Es ist nämlich so, dass man bundler verbieten kann, die Gemfile.lock umzuschreiben. Dafür verwendet man das Kommando

bundle config set frozen true

Laut Dokumentation wird die Verarbeitung abgebrochen, sobald die Datei umgeschrieben werden müsste.

Obwohl ich diesen Befehl meiner yaml-Datei in der CI hinzugefügt hatte, schlug das Bauen erneut fehl. Auslöser war dieselbe Bibliothek nokogiri wie vorher, nur war die Fehlermeldung nun viel hilfreicher:

`Gemfile.lock` für verschiedene Umgebungen optimieren

Also befolge ich den Vorschlag und führe das gewünschte Kommando auf meinem lokalen Rechner aus:

bundle lock --add-platform x86_64_musl # my CI runner's environment

Randnotiz: musl ist eine libc-Implementierung für Linux, sprich mit ihrer Hilfe laufen viele in C geschriebene Programme.

In meiner Lockfile taucht daraufhin folgender Eintrag auf:

nokogiri (1.18.10-x86_64-linux-musl)

Nun läuft meine CI wieder sauber durch und nebenbei habe ich die Portabilität meines Jekll-Setups verbessert.

Giteas act_runner: Startprobleme

Schallbert — Fri, 30 Aug 2024

Das Problem

Seitdem ich diese Seite in Eigenregie betreibe, habe ich nach Neustart des Gitea-Containers das Problem, dass der aktivierte act_runner manchmal nicht mit hochfährt. Er bricht dann unter Angabe von Status Code -1 ab und meine Workflows werden nicht abgearbeitet, sodass ich z.B. keine Artikel bauen oder veröffentlichen kann.

Die Fehlermeldung ist immer dieselbe:

[...]
runner-1 | time="2024-08-26T10:09:46Z" level=info msg="Starting runner daemon"
runner-1 | time="2024-08-26T10:09:46Z" level=error msg="fail to invoke Declare" error="unavailable: 502 Bad Gateway"
runner-1 | Error: unavailable: 502 Bad Gateway
runner-1 exited with code 1
gitea | 2024/08/26 10:09:46 cmd/web.go:242:runWeb() [I] Starting Gitea on PID: 16

Der Runner kann sich also nicht bei Gitea einklinken. Wenn ich alle Services über Docker per docker restart erneut starte, meint der Container für act_runner, ihm fehle dafür ein Netzwerk mit ID <ellenlanger Hexcode hier>.

Die kurzfristige Lösung

Ich hatte die letzten Monate keine Zeit dem nachzugehen. Daher half ich mir stets damit, folgendes doppelt auszuführen:

# schallbert server-console
docker compose -f /path/to/giteas/composefile up -d

Beim zweiten Anlauf dann lief der Runner wiederholbar erfolgreich an (Gitea war ja schon betriebsbereit):

gitea | 2024/08/26 10:38:17 routers/init.go:116:InitWebInstalled() [I] Git version: 2.45.2 (home: /data/gitea/home)
runner-1 | time="2024-08-26T10:38:22Z" level=info msg="Starting runner daemon"
runner-1 | time="2024-08-26T10:38:22Z" level=info msg="runner: action-runner, with version: v0.2.10, with labels: [ubuntu-latest], declare successfully"
runner-1 exited with code 0
runner-1 | time="2024-08-26T10:40:32Z" level=info msg="Started runner daemon"

Dies ist natürlich nicht so schön und muss händisch von mir gemacht werden. Doch was ist die Ursache?

Ursachenforschung

Zuerst hatte ich den Reverse Proxy von Caddy im Verdacht, da er Gitea an das Internet anbindet. Doch tatsächlich ist Gitea selbst das Problem: Es ist zum Zeitpunkt, zu dem Docker den runner Container startet, noch gar nicht fertig hochgefahren. Also lese ich nach, wie ich Abhängigkeiten in Docker besser darstellen kann.

Lösung: Abhängigkeiten abbilden

Zuerst versuche ich es mit dem Einbinden der Änderung in docker compose.

depends_on

# gitea/docker-compose.yml
 ## service: runner
 ## [...]
 depends_on:
 gitea:
 condition: service_started

Doch noch immer startet der act_runner wohl zu früh. Docker stellt hier nämlich lediglich sicher, dass Gitea gestartet wurde, nicht aber, dass es hochgefahren ist und stabil läuft.

Healthcheck

Ich muss folglich sicherstellen, dass Gitea betriebsbereit ist. Dies geht prima mit der Bedingung service_healthy. Ich passe also die Instruktionen für den Runner wie folgt an:

# gitea/docker-compose.yml
 ## service: runner
 ## [...]
 depends_on:
 gitea:
 condition: service_healthy # required so runner can attach to gitea
 restart: true

Der service_healthy Qualifier ist ein Rückgabewert der healthcheck Funktion. Diese besteht aus einem sogenannten test und ein paar Begleitparametern, in welchem Intervall wie oft und nach welcher Zeit geprüft werden soll, ob der Dienst nun betriebsbereit ist.

Ich habe als Test ein einfaches Kommando gewählt mit der Annahme, dass Gitea (und damit implizit auch Caddy) fertig hochgefahren ist, sobald curl seine Webseite aufrufen kann.

# gitea/docker-compose.yml
## service: gitea
## [...]
 healthcheck:
 test: ["CMD", "curl", "-f", "https://git.schallbert.de/"] # checks if gitea is available
 interval: 10s
 retries: 3
 start_period: 30s
 timeout: 10s

Mit diesen Zeilen prüft Docker, ob Gitea “healthy” ist und startet den act_runner entsprechend später. Das oben dargestellte Problem ist auf meinem Server seitdem komplett behoben und Gitea sowie runner verhalten sich zuverlässig und stabil.

Fehler-Logdateien versenden

Schallbert — Tue, 20 Aug 2024

In diesem Artikel schaue ich mir an, wie ich “Monitoring” für meinen Server einrichte. Anwendungen und Dienste sollen mir im Fehlerfalle Benachrichtigungen senden können.

Worum geht es hier?

Sendemechaniken kennenlernen und auswählen
Testnachrichten verfassen und die Automation verifizieren
Fehlerbericht von Borgmatic automatisch senden
Senden von Runner-logs durch Gitea
Benachrichtigung bei Login auf meinem Server per ssh
Erstellen und Senden eigener Logs zu Server-Update / Server-Fehlern

Verifikation und Überwachung

Ich möchte nach dem Ausführen einer Automation wissen, ob sie erfolgreich durchgeführt wurde und alle Programme und Dienste ihre Arbeit erwartungsgemäß aufgenommen haben. Dies soll für jegliche Automation gelten - ob es sich konkret um das Senden eines Updates, die Anfertigung automatischer Backups oder eine Action von Gitea handelt, muss egal sein.

Normalerweise würde ich für so etwas Berichtsmechanismen von act_runner verwenden. Im Falle eines Server-Updates steht der Runner durch den bereits im Artikel Serverkonfiguration ausrollen erwähnten Zirkelbezug nicht zur Verfügung, da zeitweise alle Anwendungen heruntergefahren werden müssen.

Zudem kann es sein, dass Anwendungen eigene Vorgehensweisen haben, Monitoring zu betreiben. Also muss ich mir Mechanismen anschauen, mit denen ich leicht an die Informationen herankomme.

Was zeichnet ein gutes Monitoring für mich aus?

Es ist unaufdringlich, meldet sich also nur im Fehlerfall oder bei ungewöhnlichen Vorgängen.
Es liefert spezifische Informationen und gut zu verstehende Fehlermeldungen.
Es nutzt einen Nachrichtenkanal, der auch bei Absturz des zu überwachenden Systems funktioniert.
Es stellt Berichte und Fehlermeldungen isoliert von anderen Themen dar und vermischt nichts.
Es fasst sich kurz.

Methoden automatischer Berichterstattung

Diesen Abschnitt gliedere ich ich auf. Im Allgemeinen Teil gehe ich auf das mir auf dem Ubuntu-Server zur Verfügung stehende Bordwerkzeug zum asynchronen Monitoring ein. Danach schaue ich mir die bei meinen Diensten teils eingebauten Lösungen bzw. mit ihnen kompatible Anwendungen an. Dabei möchte ich mich nicht auf das klassische Instrument der E-Mail beschränken, sondern auch kurz “modernere” Kommunikationskanäle wie Messengerprogramme oder RSS-Feed beleuchten.

Mail per Konsole - curl

Versand von Mails als Benachrichtigungen sind in vielen Firmen üblich. Dies geht mit Linux meist sogar ganz ohne zusätzliche Programme: Das standardmäßig vorhandene curl kann hier bereits weiterhelfen. curl it ein Programm zum Datentransfer von oder zu einem Server. Gebe ich meinen Blog als Ziel ein, bekomme ich die HTML-Seite als Textdatei auf die Konsole ausgegeben:

curl https://blog.schallbert.de

Bei der Gelegenheit fällt mir auf, wie viel unnötige Daten meine Blogsoftware erzeugt. Da werde ich später mal aufräumen müssen. Zurück zum Thema: Man kann curl allerdings auch nutzen, um ein beliebiges Webbackend anzusprechen - Zum Beispiel einen Mailserver:

# copied from https://stackoverflow.com/questions/8260858/how-to-send-email-from-terminal
curl --url 'smtps://smtp.gmail.com:465' --ssl-reqd \
 --mail-from 'from-email@gmail.com' \
 --mail-rcpt 'to-email@gmail.com' \
 --user 'from-email@gmail.com:YourPassword' \
 -T <(echo -e 'From: from-email@gmail.com\nTo: to-email@gmail.com\nSubject: Curl Test\n\nHello')

Dies funktioniert nur dann auch für meinen Mail-Provider, wenn ich Logins durch externe Clients zulasse. Google nennt diese z.B. “weniger sichere Apps”. Ich bin wie in meinem Beitrag Server-Konfiguration mit Git beschrieben kein Fan davon, Secrets irgendwo hart hineinzuschreiben - daher würde ich den direkten Weg über curl eher nicht nutzen.

Mail per Konsole - mail, mailx, mailutils, swaks

Wer all die Konfigurationsinformationen für den Server und Secrets nicht immer mitgeben möchte, dem stehen diverse handliche Werkzeuge für die Konsole wie mailutils oder swaks zur Verfügung. Hier wird die Verbindung zum Mailserver über das Werkzeug einmalig konfiguriert und kann in z.B. in Umgebungsvariablen abgelegt werden. Die Syntax variiert von Programm zu Programm, hinten kommt aber stets eine Mail heraus.

An sich eine simple Lösung. Der einzige große Nachteil dabei für mich ist, dass sich hier Informationsdomänen vermischen. Ich hätte nur ungern noch einen “Berichtsthread” in meinen Mails, nach dem ich im Wust der Nachrichten irgendwann würde suchen müssen. Bei Benachrichtigungen auf anderen Kanälen kann ich zudem ein automatisches Verfallsdatum einstellen, sodass sie nach eingestellter Zeit aus meiner Liste verschwinden.

RSS Feed erzeugen

Ungewöhnlich aber möglich: Ich könnte das Monitoring als RSS-Feed wie meinen Blog auch (schallberts-blog-feed) z.B. per Jekyll-Instanz erzeugen und als Website online stellen. Dieser wäre leicht zu abonnieren, mit praktisch jedem Reader zu lesen und ich könnte ihn sogar für jede Applikation ganz einfach getrennt vorsehen. Doch es gibt offensichtliche Nachteile:

Hoher Aufwand: Gitea runner mit Jekyll-Instanz, Webserver und Subdomain erforderlich.
Öffentlich verfügbar: Plötzlich werden Bauvorgänge, Updates, Upgrades und Fehlermeldungen für jedermann zugänglich.
Fehleranfällig: Schmiert Gitea, der Runner, mein Proxy oder der Webserver ab, bekomme ich keine Berichte.

Spätestens mit dem letzten Punkt ist diese Option für mich raus. Ich möchte ja gerade dann einen Bericht bekommen, wenn meine Applikationen nicht das tun, was sie sollen.

Werfen wir nun mal einen Blick auf die von mir bereits betriebenen Anwendungen und schauen, wie sie dieses Problem angehen.

borgmatic

Borgmatic bringt von Haus aus Kompabitilität zu einer Menge Monitoring-Optionen mit. Darunter befinden sich apprise, ntfy, healthchecks, cronitor, pagerduty, cronhub und grafana.

Apprise ist eine Bibliothek. Sie ist quelloffen und kann von einer bestehenden Anwendung als Abhängigkeit eingebunden werden. Wie ein Adapter ermöglicht sie die asynchrone Kommunikation der Anwendung mit diversen verschiedenen Kommunikationsdiensten wie SMS, Mail, Messenger (z.B. Signal), diverse Heimautomation oder den Benachrichtigungssystemen diverser Betriebssysteme. Letzteres funktioniert allerdings nur auf der lokalen Maschine. Der Trigger für die Kommunikation muss dabei stets von der Anwendung ausgehen.
ntfy ist ein Push-Benachrichtigungsdienst. Er ist quelloffen und kann sowohl selbst gehostet als auch über eine Webanwendung als Dienstleistung in Anspruch genommen werden. Apprise z.B. unterstützt ntfy als Kommunikationsdienst. Der Aufbau ist recht einfach und funktioniert wie bei MQTT auch über einen Publication-Subscription bzw. Broker-Client Mechanismus, allerdings HTTP-basiert.
Healthchecks ist ein Dienst. Er ist quelloffen und kann selbst gehostet werden. Der Dienst ist dazu da, regelmäßige Aktivitäten zu überwachen und kann als Totmannschalter fungieren: Erfolgt anders als erwartet keine Rückmeldung vom überwachten Programm, so kann er selbst eine Fehlermeldung absetzen. Diese kann wiederum an diverse Kommunikationsdienste gesendet werden.
Cronitor ist eine Monitoringlösung und Webanwendung, die neben den von mir benötigten Benachrichtigungen eine Menge Analysetools, Leistungsmessungen und Metriken - zumeist gegen Geld - bereitstellt. Es gibt zwar einen kostenfreien “Hacker”-Account mit begrenztem Funktionsumfang, jedoch ist auch dieses Werkzeug mir entschieden zu groß und zu komplex.
PagerDuty sieht sich als kommerzielle “Operations” Plattform, die sowohl “Incident Management”, Automation, “Business Operations”, “AIOps” etc. bereitstellt. Ist für mich direkt raus. Spätestens beim Wort “AIOps” 😅
cronhub sieht mir wie eine kommerzielle Webanwendung aus, die ähnlich wie Healthchecks Cron-Jobs erstellen, überwachen und bei Fehlern melden kann. Sie ist für mich uninteressant, denn sie scheint weder open source zu sein noch könnte ich sie selbst hosten.
Grafana ist eine Open-Source-Webanwendung, die entweder selbst gehostet oder als Cloud-Dienst verwendet werden kann. Obwohl viele größere Unternehmen und Projekte die Anwendung nutzen, ist sie für meine Zwecke um Größenordnungen zu umfang- und funktionsreich.

fail2ban

Fail2ban hat keine Automationslösung wie borgmatic. Es erzeugt schlicht Logdateien die ausgewertet werden müssten, um Inhalte für Benachrichtigungen zu gewinnen. Mir fällt im Moment nichts ein, was ich unbedingt von Fail2ban wissen müsste. Daher erstelle ich mir hierfür erst einmal keine Berichte.

Gitea

Bei Gitea lassen sich die Logdateien sehr feingliedrig konfigurieren. So können Access Logs getrennt von Service Logs, Repository Logs oder Action Logs herausgeschrieben und dann weiterverarbeitet werden. Als Benachrichtigungssystem bietet Gitea nach meiner Recherche ausschließlich einen mailer an. Dieser ist meiner Ansicht nach vor Allem für Repository- und Action Logs gedacht.

Auch hier würde es mir am meisten bringen, die Logs zu analysieren und bei Bedarf einen Bericht selbst zu erstellen.

Server

Das Ausrollen meiner Server-Konfigurationsdateien übernehme ich per Skript ja sowieso schon selber. Also könnte ich auch hier im Fehlerfalle die Logs in eine Datei umleiten und sie dann einem Bericht in einen beliebigen Kanal anhängen.

Außerdem wären erfolgreiche Logins auf dem Server selbst eine Nachricht an mich wert. Dann kann ich sofort feststellen, ob ich das selbst war oder nicht.

Die Auswahl des Berichtsprogramms

Ich muss nicht nur ein Monitoring-Programm heraussuchen, sondern auch einen Kommunikationsdienst wählen über den die Berichte versendet werden.

Berichtsprogramm

Programm	Vorteil	Nachteil
curl	simpel	Konfiguration muss mitgegeben werden
	funktioniert super einfach mit ntfy¹	Keine Überwachung bei Absturz des Servers
	Bordwerkzeug
	kein Service erforderlich
Apprise	ermöglicht Einbindung der Signal-Api²	Komplex im Zusammenspiel mit externen Diensten³
	kein Service erforderlich
Healthchecks	Kann als Watchdog/Totmannschalter agieren	Registrierung erforderlich
	Kann lokal gehostet⁴ werden	Lokales Hosting widerspricht Watchdog-Konzept

Ich habe ja nur einen kleinen Server mit ein paar wenigen Anwendungen. Daher halte ich es hier so einfach wie möglich und wähle Apprise für Dienste wie borgmatic, die diese Bibliothek sowieso mitbringen und curl für jene, deren Berichtsmechanik ich selbst programmieren muss.

Kommunikationsweg

Programm	Vorteil	Nachteil
SMS	Hohe Zuverlässigkeit	Registrierung erforderlich
		Beschränkung auf wenige Zeichen
		Keine Anhänge möglich
		Keine Topics, Domänenvermischung
Mail	einfach einzurichten	Schlechte Durchsuchbarkeit
RSS-Feed	Gute Sortierbarkeit	Kompliziert einzurichten, fehleranfällig
	Client sehr leichtgewichtig	Lokales Hosting widerspricht Watchdog-Konzept
		Inhalte öffentlich verfügbar
ntfy	Simpel und leichtgewichtig	Registrierung optional bei Web-Nutzung
	Client zweckorientiert	Unsicher: Keine Verschlüsselung ohne Registrierung
	Kostenlos für Kleinanwender
	Unabhängig von der eigenen Maschine
Signal	“Note to self” einfach einzurichten	Einrichtung und Konfiguration der Signal-API komplex
	Unabhängig von der eigenen Maschine	Topics etwas schwierig umzusetzen
		Nutzlos bei Absturz des Servers

SMS, Mail und RSS-Feed sind durch teils oben bereits erläuterte Nachteile für mich bereits raus. Bleiben also ntfy und Signal. ntfy besticht durch seine Einfachheit: HTTP PUSH-request auf ein selbst definiertes “Topic” senden und selbiges auf dem Handy abonnieren - fertig. Es ist auch gut erweiterbar, denn durch self-hosting kann ich später bei Bedarf die Sicherheit erhöhen (Verschlüsselung) und das Sendeverhalten steuern. Signal hingegen macht einen eigenen Client mit verhältnismäßig aufwendiger Konfiguration erforderlich. Außerdem müssten die Geräte Server-Handy verbunden werden, sodass nicht einfach neue Abonnenten hinzuzufügen sind. Dafür ist die Übertragung bestens Ende-zu-Ende gesichert, ich muss mich nicht registrieren und kostenlos ist es auch noch.

Vorerst entscheide ich mich auch hier für die weniger komplexe Lösung mit ntfy.

Logging

Gut. Nun ist geklärt, dass ich per curl und apprise über den ntfy-Dienst nach Hause telefoniere. Nun schaue ich mal, welcher Inhalt zu übermitteln ist und wie ich möglichst unaufdringlich, dabei aber kurz und prägnant bleibe.

Wann sollen Logs gesendet werden?

borgmatic: Wenn ein Backup fehlschlägt
Bei erfolgreichem Login auf meinen Server oder Gitea
Nach Ausrollen eines Updates der Server-Konfiguration
docker: Falls eine Applikation ausfällt oder nicht hochfährt
gitea: Fehlgeschlagener Durchlauf von act_runner

Was gehört für mich in einen Bericht?

Ich möchte die klassischen “W-Fragen” beantwortet bekommen.

Wann ist es passiert (Zeitstempel)?
Welche Anwendung berichtet?
Was ist passiert?
Wo (Modul, Codezeile) etc. ist das passiert?
Wie viele Verletzte (Schweregrad, Recovery)?

Eine Benachrichtigung sieht dann etwa so aus:

TIMESTAMP APPLICATION PRIORITY MESSAGE EFFECT DETAIL

Rohfassung eines Berichts

Eine ntfy-Nachricht könnte ungefähr so aussehen:

curl \
 -H "Title: Fehler Borgmatic" \
 -H "Priority: urgent" \
 -H "Tags: warning" \
 -d "YYYY-MM-DD HH:MM:SS Backup-Erstellung abgebrochen. Zugriff auf Repository blockiert" \
 ntfy.sh/schallberts-topic

Ich installiere die entsprechende App auf meinem Handy, registriere mich auf das “Topic” und sende die Nachricht ab. Es ist schön, wenn Dinge einfach funktionieren! Aha, die App zeigt den Zeitpunkt des Einganges an. Das ist mir genau genug.

Durchführung

Ich nehme mir hier nacheinander alle Dienste vor, für die ich gern Benachrichtigungen einrichten möchte.

borgmatic

Starten wir mit einem Pilotversuch wieder in kleinen Schritten. Als Erstes konfiguriere ich Borgmatic zum Senden einer Nachricht über Apprise an ntfy bei Fehlschlag der Backup-Erstellung:

# /borgmatic.d/config.yml
on_error:
 - echo "Error while creating a backup."
 - apprise -vv --title "Borgmatic Error"
 --body "Could not run {output}. Aborted {error}."
 ntfy://schallberts-topic

Dann teste ich das Kommando, indem ich innerhalb des Borgmatic-Containers apprise anspreche. Und tatsächlich, es funktioniert. Aber der Weg hierhin hat mich locker eine Stunde gekostet, da die yml mit ihren Syntaxregeln sogar innerhalb von Strings interpretiert und borgmatic aufgrund von : sowie - Zeichen ständig die Konfigurationsdatei nicht lesen wollte. Wenn ihr einen Fehler sieht ähnlich diesem hier:

At 'on_error[1]': {'apprise -vv --title "Borgmatic Error" --body "Could not run {output}': 'Aborted {error}." ntfy://schallberts-topic'} is not of type 'string'

Daran ist zu erkennen, dass die Interpretation von Zeichen oder Einrückungen schiefgelaufen ist und die Zeichensetzung zu prüfen ist. Alternativ kann auch der Pipe-Operator | verwendet werden, um ein Kommando zu kombinieren. Referenz: yml-Spezifikation

Server

Eine Anwendung von ntfy zur Überwachung von Logins auf einem Server findet sich bereits in der Dokumentation von ntfy selbst. Die Beschreibung zeigt, dass so etwas leicht selbst umzusetzen ist und gibt unter Verwendung von Pluggable Authentication Modules (PAM-Bibliothek) ein tolles Beispiel.

Am Ende der Datei sshd im Verzeichnis etc/pam.d folgenden Code einfügen:

session optional pam_exec.so /usr/bin/ntfy-ssh-login.sh

Diese Zeile sagt PAM, dass sie bei Öffnen einer session per ssh das ausführende Modul pam_exec aufrufen soll, welches dann das hernach angegebene Skript abspult. Der Wert optional bedeutet, dass die Konfigurationsdatei auch bei Fehlschlag der Aktion weiter durchlaufen werden soll. Mehr Details zum Umgang mit PAM gibt es z.B. auf Baeldung.

Anschließend ist im Skript ntfy-ssh-login.sh schlicht der ntfy-Aufruf zu hinterlegen, wenn das Skript feststellt, dass PAM ein open_session Event festgestellt hat.

Genau so habe ich es bei mir umgesetzt und es funktioniert auf Anhieb. Klasse! Der einzige Nachteil: Diese Modifikation habe ich direkt auf dem Server gemacht. Ohne Container und außerhalb meiner Konfigurations-Sicherung. Wenn ich den Server jetzt aus irgendeinem Grund neu aufsetzen muss, ist die Änderung im PAM futsch und ich bekomme keine Benachrichtigungen mehr, bis ich die Änderung manuell erneut einpflege.

Server-Konfiguration

Für das Senden eines Berichts nach Ausführen der Konfigurationsautomation muss ich eigentlich nur das im Rahmen des letzten Artikel verfasste server-config-action Skript anpassen.

Zunächst möchte ich informiert werden, wenn das Skript fehlerfrei durchlief. Dafür füge ich am Ende der Datei einen curl-Befehl ein.

# server-config-action.sh

# action commands...
# [...]
# send success notification
curl \
 -H "Title: server-config-action" \
 -H "Priority: low" \
 -H "Tags: white_check_mark" \
 -d "Rollout successful" \
 ntfy.sh/schallbert-server-config-push-topic

Sollte das Skript allerdings nicht fehlerfrei durchlaufen, so möchte ich folgendes tun:

Aktionen nach Auftreten des Fehlers abbrechen
Ein Fehler-Log erstellen
Dieses Log versenden

Den ersten Punkt kann ich durch Hinzufügen einer Falle (Englisch “Trap”) für Fehler erreichen:

# server-config-action.sh
trap 'handle_error $LINENO' ERR

# action commands...

Hiermit wird die Funktion handle_error aufgerufen. Ihr wird die Zeilennummer mitgegeben, an der der Fehler ERR auftrat. Damit decke ich auch Fehler ab, die beim Neustart der Container entstehen können. Das Fehler-Log erstelle ich mir durch Wegschreiben der Ausgabe der einzelnen Skriptbefehle. Dies erreiche ich mit der folgenden Zeile:

# server-config-action.sh

exec 3>&1 1>server-config-action.log 2>&1

# action commands ...

Jeglicher Standard-Output stdout soll mit diesem Befehl an den Dateideskriptor 3, hier angegeben mit der Logdatai server-config-action-log, überschreibend weitergereicht werden. Für “Anhängen” müssten es zwei Umleitungsoperatoren >>⁵ sein. Somit ersetzt die Logdatei die Konsolenausgabe, welche ich im vorigen Artikel noch an dieser Stelle hatte.

Um das Log zugesandt zu bekommen, definiere ich nun folgende Funktion am Anfang des Bash-Skripts:

# server-config-action.sh
# on error, send a notification
handle_error() {
 # stop redirecting to file
 exec 1>&3 1>&2
 curl \
 -H "Title: server-config-action FAILED" \
 -H "Priority: high" \
 -H "Tags: x" \
 -T server-config-action.log \
 -H "Filename: server-config-action.log" \
 ntfy.sh/schallbert-server-config-push-topic
 exit 1
}

# set error trap
# redirect stdout and stderr to file
# action commands...

Gitea

Für Berichte von Github Actions gibt es bereits ein existierendes Beispiel auf ntfy_examples/#github-actions. Und das Beste: Da der act_runner von Gitea an den wesentlichen Stellen in den Umgebungsparametern kompatibel ist, funktioniert das Senden an ntfy bei mir auf Anhieb. In der Workflow-Datei des runners muss nur der auf der Website angegebene curl-Befehl angegeben werden und fertig.

Ergebnis

Hiermit sind jetzt fünf Benachrichtigungen über die wichtigsten Vorgänge auf meinem Server eingerichtet. Ich habe die zugrundeliegenden Mechaniken verstanden und kann jederzeit weitere Benachrichtigungen erstellen, wenn ich sie benötige. Löse ich alle Benachrichtigungen testweise aus, zeigt mein Handy das dargestellte Bild.

Eine Unabhängigkeit vom zu überwachenden System habe ich noch nicht erreicht. Die Benachrichtigungen gehen sämtlich von der betroffenen Maschine aus und es bestehen zum Teil sogar Abhängigkeiten zwischen Docker-Containern. Der act_runner muss sich zum Beispiel über Websockets mit Gitea verbinden. Und das funktioniert nur, wenn Caddy den Reverse Proxy bereitstellt.

Stelle ich in den nächsten Monaten fest, dass ein Dienst “unter meinem Radar” nicht mehr arbeitsfähig ist, werde ich diese Unabhängigkeit herstellen müssen und entsprechend darüber berichten.

Kontext zum Setup mit ntfy ↩︎
Kontext zur Signal-API ↩︎
Bericht von asad-awadia zur Einrichtung der Signal-API ↩︎
Healthchecks ist direkt verfügbar als Docker-Image. ↩︎
Übrigens sind die Operatoren << und >> für mich nicht schwer zu merken, denn früher habe ich viel mit der Programmiersprache C zu tun gehabt. Dort - und in vielen anderen Programmiersprachen auch - sind dies Shift-Operatoren, die einen Wert bitweise “verschieben” bzw. ein Feld auf ein anderes schieben können. Bei den RISC Architekturen, die ich damals verwendet habe, war die Schiebe-Operation “billig”, also sehr schnell und speicherplatzschonend umgesetzt. ↩︎

Server-Konfiguration ausrollen

Schallbert — Wed, 31 Jul 2024

Im vorigen Artikel habe ich meine Konfigurationsdateien unter Versionskontrolle gebracht. Nun will ich die auf dem Server bereitgestellten Updates automatisiert einspielen.

Worum geht es hier?

Schreiben eines Skripts zur automatischen Erkennung des Update-Triggers
Server-Anwendungen sollen heruntergefahren und eine Sicherungskopie erstellt werden
Das Skript soll die Konfiguration auf dem System verteilen
Anschließend sollen alle Anwendungen neu gestartet werden

Wege und Möglichkeiten

Auch hier habe ich wieder mehrere Stunden mit Recherche verbracht. Bei größeren Projekten verwenden Infrastrukturexperten anscheinend spezialisierte Automatisierungswerkzeuge. Dazu zählen Ansible, einfachere Tools wie cdist oder gar Kubernetes für stark skalierende Dienste.

Automatisierungsdienste Ansible, cdist, Kubernetes

Ansible und cdist scheinen dabei ein ähnliches Konzept zu verfolgen: Auf der Quellmaschine (in diesem Beispiel meinem Laptop) erstelle ich die Konfiguration für meinen Server und lege diese sowie die Vorschrift zur Konfiguration meiner Dienste in einem “Playbook” (Ansible) bzw. in “types” (cdist) ab.

Vereinfacht gesagt - so wie ich das verstanden habe - kümmert sich das Werkzeug anschließend auf Knopfdruck darum, die Konfiguration zu bauen, sich per ssh auf dem Zielhost einzuwählen, sie dort hinüberzuschieben und anschließend zu starten. Für Ansible existieren sogar für mein Szenario mit docker-compose Tutorials wie dieses, was den Einstieg nochmal erleichtert.

Einen anderen Weg geht Kubernetes, was sich als eher als Containermanager, Loadbalancer und Skalierungsagent versteht, aber für meine Zwecke Ähnliches leisten kann.

Mein Weg

Ich hingegen brauche von den Fähigkeiten dieser Programme nur einen Bruchteil. Zudem schrecken mich der “zusätzliche” ssh-Kanal, der Konfigurationsaufwand, die teils auf dem Zielsystem erforderlichen, zusätzlichen Programme sowie das erforderliche Einlesen und Auswählen des für mich besten Werkzeuges ab. Denn dank meiner sehr einfachen Pipeline aus dem letzten Artikel befindet sich die Konfiguration bereits auf meinem Server. Sie muss “nur noch” an die richtigen Stellen kopiert und betroffene Services einem Neustart unterzogen werden.

Daher versuche ich, dieses Problem mit Bordwerkzeug, meinem Gehirn in Betriebsbereitschaft und ein paar Suchanfragen bei Einschlägigen Foren zu den Themen “Ausführen eines Skriptes bei Dateiänderung, “Kopieren von Ordnerstrukturen unter Linux” zu lösen.

Risiko Zirkelbezug

Ein Risiko gehe ich dabei jedoch ein: Da das Deployment über Gitea läuft, die Konfiguration aber Gitea selbst betrifft, kann ich bei einem Fehler in diesem Modul nichts mehr um- oder zurückstellen: Der Gitea-Service ist dann ja kaputt. In diesem Szenario müsste ich also händisch mit auf dem Server die Konfiguration wieder ans Laufen bekommen.

Ich probiere es jetzt trotzdem aus und schaue, ob ich tatsächlich mit so einem Problem konfrontiert werde. Falls ja, steige ich halt auf cdist um und dokumentiere dies in einem eigenen Artikel! 🤗

Vorbereitung: Ordnersystem und Skripte erstellen

Ich überlege kurz und erstelle ein paar Ordner im Server-Dateisystem:

# /opt/server-config
mkdir automation-hooks-trigger
mkdir automation-hooks-handler

Diese Ordner sollen die zwei Seiten der Automation abbilden. trigger enthält Textdateien, die von der (Web)-Serviceseite aus manipuliert werden können. So soll act_runner beispielsweise die Datei server-config-update schreiben, sobald ein Update vorliegt.

service –> writes to trigger file ||| server_handler() –> trigger_file.changed ? run_action() : loop()

Im Handler-Ordner wiederum befinden sich Skriptdateien, die die erforderlichen Änderungen auf dem Server-Dateisystem vornehmen.

Durchführung: Shell-Script zum Abhandeln des Updates

Im vorigen Artikel habe ich im Container act_runner zum Signalisieren des Vorhandenseins einer neuen Serverkonfiguration das Kommando touch server-config-update.txt ausgeführt. Auf dem Server prüfe ich nun mit folgendem Code periodisch ab, ob sich diese Datei geändert hat.

### set directories
actionfile=/opt/server-config/automation-hooks-handler/server-config-action.sh
triggerfile=/opt/server-config/automation-hooks-trigger/server-config-update.txt

### Set initial time of file
LTIME=`stat -c %Z ${triggerfile}`

while true
do
 ATIME=`stat -c %Z ${triggerfile}`

 if [[ "$ATIME" != "$LTIME" ]]
 then
 ${actionfile} 2>&1
 LTIME=$ATIME
 fi
 sleep 10
done

Per #!/bin/bash wird dem Betriebssystem der Interpreter genannt, mit dem das Skript auszuführen ist. Der Befehl stat -c %Z fragt ab, wann die Datei zuletzt geändert wurde und gibt den Zeitpunkt im Epoch-Format zurück. Schließlich wird die zu Anfang des Skriptes mit der in der Schleife genommenen Zeit verglichen und bei Veränderung kann dann die noch zu schreibende Deploy-Routine ablaufen. Anschließend wird der Referenzzeitpunkt aktualisiert. Zum Schluss pausiert das Skript (sleep 10) für zehn Sekunden, bevor die Abfrage erneut losläuft. Ich verwende absolute Pfade, da ich das Skript sowohl für Tests von der Konsole aus als auch automatisch per cron oder systemd starten können will.

Erster Test und Einhängen in den “Autostart”

Nun müssen wir die Datei für einen ersten Test ausführbar machen:

# change file mode bits: add "executable" flag to server-config-handler script
chmod +x /opt/server-config/automation-hooks-handler/server-config-handler.sh

Dann erstelle ich die Datei server-config-action.sh und gebe ihr als einziges Kommando ein echo. Schauen wir mal, ob bis hierhin alles funktioniert. Dafür erstelle ich lokal meine Update-Triggerdatei und starte das Skript. Anschließend modifiziere ich sie in einer anderen Shell-Instanz per touch server-config-update.txt und prompt erscheint in der Konsole --- CONFIG UPDATE TRIGGER detected ---. Super!

Auf dem Server später muss ich das Skript automatisch nach einem Neustart ausführen lassen. Dafür nehme ich das Werkzeug cron zur Hilfe und erstelle einen neuen Eintrag per crontab -e:

# cron can automatically execute recurring tasks
# in this case, we're running server-config-handler script on reboot
@reboot sh /opt/server-config/automation-hooks-handler/server-config-handler.sh

Mit dem Befehl ps aux kann ich nun prüfen, ob das Skript auch wirklich ausgeführt wird:

schallbert@server: ps aux
[...]
8:15 0:00 /bin/bash ./server-config-handler.sh
8:15 0:00 sleep 10
[...]

Sicherungskopie

Eine Sicherungskopie meiner Anwendungen und Dateien anzufertigen bevor ich das Update ausrolle macht total Sinn. Also teile ich Borg mit, dass ich jetzt ein Backup anlegen möchte. Vorher muss ich natürlich alle Services stoppen. Somit sind alle Daten zugriffsfrei, kohärent und statisch.

Zustand und Daten einfrieren

Hierfür lege ich in automation-hooks-handler ein Skript an, welches alle Container bis auf borg selbst beendet.

#! /bin/bash
# /opt/automation-hooks-handler/backup-pre-action.sh
# this shell script shuts down all docker containers prior to backup

echo "Shutting down containers for backup:"
echo "watchtower..."
cd /opt/watchtower
docker compose down 2>&1
# [...]

Der Ausdruck 2>&1 bedeutet, dass eventuelle Ausgabe von Fehlern in die Konsole umgeleitet wird. Die Zahl 1 stellt nämlich den Filedescriptor für stdout dar, während 2 stderr meint. Der Operator >& funktioniert als redirect merger, also als Umleitung und Zusammenführung. Später können wir an diesem Punkt hingehen und die Ausgabe in ein Logfile schreiben - das lasse ich aber der Einfachheit halber erst einmal aus.

Borgmatic: Trigger-Handler Mechanismus #2 und #3

Das Skript kann ich nun auf zwei Arten ausführen lassen:

Als Aufruf durch das weiter oben beschriebene Skript server-config-handler
Durch die vor borg geschaltete Automatisierungslösung borgmatic

Ich entscheide mich für die zweite Option und schreibe daher in die borgmatic.d/config.yml die folgenden Befehle:

# borgmatic.d/config.yml
# List of one or more shell commands or scripts to execute before
# creating a backup, run once per repository.
before_backup:
 - echo "Triggering container shutdown for backup."
 - touch /etc/automation-hooks-trigger/backup-pre.txt
 - sleep 20
 - echo "Assuming container shutdown complete. Creating the backup now."
# [...]
after_backup:
 - echo "Triggering container restart after backup."
 - touch /etc/automation-hooks-trigger/backup-post.txt
 - sleep 10
 - echo "Assuming container restart complete. Exiting."
# [...]

Damit dies richtig funktioniert, muss ich in der zugehörigen docker-compose.yml natürlich ein Volume anlegen und auf den Pfad im Dateisystem des Servers zeigen lassen: ${VOLUME_UPDATE_TRIGGER}:/etc/automation-hooks-trigger

Nun muss ich die Gegenseite dieser Trigger einrichten: Handler überwachen die Triggerdateien auf Änderungen und rufen entsprechend Action-Skripte auf. Sie sind bis auf die Pfade von triggerfile und actionfile identisch mit dem oben erläuterten Handler.

Das Backup anlegen

Würde ich borg direkt ansprechen, so ließe sich das Backup über create erstellen. Dazu müsste ich angeben, in welchem Repository die Sicherungskopie abgelegt werden soll und unter welchem Namen. Im Beispiel unten wird das mit dem Scope-Operator vorgegeben: ::config-update. Anschließend werden die zu sichernden Ordner angegeben.

borg create /path/to/repo::config-update ~/opt

Ich verwende ja borgmatic, was mir über die Konfigurationsdatei einiges abnimmt. Dafür muss ich den Befehl allerdings im Container ausführen. Um besser prüfen zu können, ob auch alles funktioniert, lasse ich mir Statistiken “verbose” auf die Konsole ausgeben (--stats -v 1) sowie die kopierten Dateien anzeigen --files.

docker exec borgmatic sh -c "cd && borgmatic --stats -v 1 --files 2>&1"

Diese Zeile füge ich dem Automationsskript hinzu.

Zweiter Test zum Anlegen des Backups

Wenn jetzt alles funktioniert, sieht der komplette Ablauf wie folgt aus:

Nach Eingang der geänderten Dateien durch Giteas Automation legt act_runner (im Docker-Container) die Dateien auf dem Server ab und setzt anschließend den server-config-update Trigger.
Binnen 10sec wird der Trigger von server-config-handler.sh erkannt, welches anschließend server-config-action.sh aufruft.
borgmatic (im Docker-Container) wird darin beauftragt, ein Backup anzufertigen. Dieses wiederum schreibt den pre-backup Trigger.
Erneut binnen 10sec wird durch diesen pre-backup-handler.sh das backup-pre-action.sh Skript aufgerufen und alle Container bis auf borgmatic gestoppt.
Durch die eingebaute Verzögerung wartet borgmatic dies ab und erstellt nun das Backup.
Nach dem Backup schreibt borgmatic den backup-post-action.sh Trigger.
Binnen weiterer 10sec erkennt post-backup-handler.sh die geänderte Datei und fährt alle Container über post-backup-actions.sh wieder hoch.
borgmatic teilt server-config-update.sh mit, ob irgendwo im Prozess bis jetzt Fehler auftraten. Falls nicht, wird fortgefahren.
Alle Docker-Container werden gestoppt.
Die Server-Konfiguration wird auf die entsprechenden Stellen ausgerollt.
Es findet ein Neustart aller Docker-Container mit neuer Konfiguration statt.

Ein erster Erfolg: Bis Punkt 6 laufen diese Skripte sogar auf meinem Laptop bereits durch:

schallbert@laptop: touch server-config-update.txt
server-config-handler@laptop: --- RUN backup ---
borgmatic@docker: /etc/borgmatic.d/config.yml: Running 4 commands for pre-backup hook
 Triggering container shutdown for backup. 
backup-pre-handler.sh@laptop: --- RUN backup-pre-action.sh ---
 Shutting down containers for backup:
 watchtower...
 [...]
 complete.
borgmatic@docker: Assuming container shutdown complete. Creating the backup now.
 local: Creating archive
 Failed to create/acquire the lock /mnt/repository/lock.exclusive

Fehlerbehebung für “failed to acquire the lock”

Dieses Problem taucht bei mir dann auf, wenn borg beim Erstellen eines Backups einen Fehler meldet, der das Programm zum Abbruch bringt. In diesem Falle wird das Repository anscheinend nicht korrekt freigegeben, sodass es nach Neustart des Containers für den alten, nun nicht mehr existierenden Container reserviert bleibt. Das folgende Kommando löst dieses Problem:

docker exec borgmatic sh -c "cd && borg break-lock /mnt/repository

Übertragen der Konfiguration

Nun müssen die Konfigurationsdateien noch an die jeweils richtige Stelle auf dem Server kopiert werden. Glücklicherweise hatte ich die Ziel-Ordnerstruktur bereits beim Erstellen des Repository geklont, sodass ich das mit einem einzigen Kopierbefehl ohne “hardcoding” hinbekommen sollte. Nach ein paar Netzrecherchen und einem Blick in die Bedienungsanleitung für den Kopierbefehl man cp habe ich mein Kommando:

# copy recursively contents of folder "server-config" to "/opt"
sudo cp -r -v /opt/server-config/. /opt 2>&1

Somit sage ich dem Betriebssystem, es solle den Inhalt (/.) des Ordners server-config rekursiv (-r), also inklusive aller Unterordner, in den Ordner opt befördern, welcher sich im Stammverzeichnis / befindet. cp arbeitet hierbei überschreibend-ergänzend, wird also noch nicht vorhandene Dateien erstellen und vorhandene überschreiben, sie also nicht unter gleichem Namen “daneben kopieren”. Mit der Option -v lasse ich zusätzliche Details ausgeben, und mit 2>&1 leite ich die Fehlerausgabe in die Konsole um.

Alle Ordnerindikatoren müssen sich genau dort befinden, wo sie im Befehl stehen: Ein Slash hinter /opt/ würde Ordner nicht-überschreibend redundant kopieren, Dateien aber überschreiben. Ohne . würde der Ordner server-config am Zielpfad erstellt.

Umstieg auf rsync

Der cp-Befehl kopiert leider auch ein paar Dateien, die ich gar nicht kopiert haben möchte: Repository-spezifische Ordner wie .gitea, oder auch die Ordner für Trigger und Handler. Diese benötige ich nur unter server-config, nicht aber auch direkt in opt. Um dies zu beheben nutze ich stattdessen das Kommando rsync. Dort kann ich mit -u einstellen, dass nur neuere Dateien überschrieben werden sollen und über eine --exclude-Option nicht zu kopierende Dateien und Ordner ausschließen. Dies sieht dann so aus:

rsync -r -u -v --exclude '.*' --exclude 'README.md' --exclude '<otherFolders>' /opt/server-config/. /opt 2>&1

Doch plötzlich startet gitea nicht mehr. Fehlermeldung:

docker@server: [...] failed to load config file "app.ini": open: permission denied

Nach längerem Grübeln und diversen Neustarts des Docker-Clients sehe ich, dass rsync die Berechtigungen der Quelldatei auf die Zieldatei geschrieben hat, was bei cp vorher nicht der Fall war: -rw-------. Nun ändere ich dies, indem ich chmod +r app.ini ausführe. Schon fährt alles wieder wie gewohnt hoch! 🎉

Alle Anwendungen neu starten

Da ich alles auf meinem Server in Docker betreibe, genügen hierfür zwei einfache Befehle:

docker stop $(docker ps -a -q) 2>&1
# [...roll out config changes...]
docker restart $(docker ps -a -q) 2>&1

Die fertige Automation

Mein Skript ist nun fertig und ruft lediglich das Action-Skript auf.

#! /bin/bash
#/opt/automation-hooks-handler/server-config-handler.sh
#[...]
 if [[ "$ATIME" != "$LTIME" ]]
 then 
 echo "--- CONFIG UPDATE TRIGGER detected ---"
 ./server-config-action.sh 2>&1
 LTIME=$ATIME
 fi
 sleep 10
done

Das Skript server-config-action führt dann die oben beschriebenen Aktionen aus:

#! /bin/bash
#/opt/automation-hooks-handler/server-config-action.sh

echo "--- RUN backup ---"
docker exec borgmatic sh -c "cd && borgmatic --stats -v 1 --files 2>&1"
echo "--- STOP all containers ---"
docker stop $(docker ps -a -q) 2>&1
echo "--- DEPLOY config ---"
cp -r -v /opt/server-config/. /opt 2>&1
echo "--- RESTART all containers ---"
docker restart $(docker ps -a -q) 2>&1

Damit das Ganze nun zuverlässig funktioniert, müssen die drei Handler-Skripte im Hintergrund laufen:

server-config-handler.sh
backup-pre-handler.sh
backup-post-handler.sh

Sie reagieren auf die jeweiligen Trigger, ausgelöst durch act_runner von Gitea bzw. durch borgmatic. Ich erweitere das crontab jetzt entsprechend und bin dann mit der Aufgabe vorerst fertig. Die Konsolenausgabe des gesamten Vorgangs sieht so aus:

--- RUN backup ---
/etc/borgmatic.d/config.yml: Running 4 commands for pre-backup hook
Triggering container shutdown for backup.
--- RUN backup-pre-action.sh ---
Shutting down containers for backup:
gitea... 
fail2ban...
complete.
Assuming container shutdown complete. Creating the backup now.
local: Creating archive
<borg archive stats>
/etc/borgmatic.d/config.yml: Running 4 commands for post-backup hook
Triggering container restart after backup.
--- RUN backup-post-action.sh ---
Restarting containers after backup:
fail2ban...
gitea... 
watchtower...
complete.
Assuming container restart complete. Exiting.
local: Pruning archives
local: Compacting segments
compaction freed about 1.82 MB repository space.
local: Running consistency checks
summary:
/etc/borgmatic.d/config.yml: Successfully ran configuration file
--- STOP all containers ---
<container ids>
--- DEPLOY config ---
sending incremental file list
<files that are copied>
sent 206,558 bytes received 3,463 bytes 420,042.00 bytes/sec
total size is 193,167 speedup is 0.92
--- RESTART all containers ---
<container ids>

Prima! Nun fehlt mir nur noch, dass diese Ausgabe mir zugestellt wird, falls etwas bei diesem Vorgang schief geht.

Server-Konfiguration mit Git

Schallbert — Mon, 15 Jul 2024

Worum geht es?

Ich wünsche eine Versionskontrolle für die Konfiguration von Serverapplikationen
Diskussion technischer Lösungen zur Umsetzung
Tutorial: Docker/Gitea/andere “Secrets” von der Versionskontrolle ausnehmen
Tutorial: Deploy-Pipeline erstellen
Automationstrigger für nachgelagertes Ausrollen der Dateien auf dem Server programmieren
Nächster Artikel: Automation auf dem Server integrieren und Upgrades einspielen

Hintergrund

Ich habe auf meinem Server ja Watchtower laufen, um die Installierten Distributionen automatisch auf Stand und frisch gepatcht zu halten. Vor Kurzem hatte ich nun den Fall, dass sich mein Gitea Action Runner nicht mehr automatisch starten lassen wollte und auch bei manuellem Start eine Fehlermeldung ausgab.

Anscheinend hatte sich Docker ohne meine Aufsicht auf Stand gebracht und warf nun beim Hochfahren des Runner-Containers einen Volumefehler, die ich so vorher noch nicht gesehen hatte. Die Fehlermeldung war eindeutig und ließ sich mittels kleiner Änderungen in einer Konfigurationsdatei für Gitea leicht beheben. Dennoch hatte ich nun das Gefühl, dass eine Versionskontrolle für meine Konfiguration sinnvoll wäre, um Änderungen, Updates und ihre Beweggründe später besser nachvollziehen zu können.

Vorüberlegungen

Klingt nun für mich nach einem Zirkelbezug: Ich nehme die Konfigurationsdateien für meinen Server in Gitea auf, welches selbst auf meinem Server läuft. Das könnte beim Auto-Deploy noch spannend werden. Aber mehr dazu später.

Spontan fallen mir zwei Möglichkeiten ein, eine Versionskontrolle mit automatischer Synchronisation zu bekommen:

1. Hardlink

Diese Lösung würde die auf meinem Server in vielen Ordnern verstreuten Konfigurationdateien per Hardlink in einen zum Repository erklärten Ordner ablegen. Warum per Hardlink? Weil jeder Service auf meinem Server in sich gekapselt läuft und dafür jeweils eigene Konfigurationsdateien und Umgebungsvariablen gemeinsam mit dem Service abgelegt bekommt. Ohne Hardlinks müsste ich den gesamten Service-Ordner versionieren und meine .gitignore entsprechend komplex aufblasen.

Mit Git würde ich die per Hardlink abgebildeten Dateien versionieren und ihre Inhalte auf diese Weise auf Gitea verfügbar machen.

schallbert@server:/server-config-files –> hardlinks –> repository –> Gitea

Ich bekäme also eine nachgelagerte “Versionsbeobachtung” mit Sicherungskopie in dem Sinne, dass die Dateien nun mehrfach herumliegen.

2. Repo und auto-deploy auf den Server

In diesem Szenario halte ich die Konfigurationsdateien lokal auf meinem Laptop und kann sie wie üblich mit Git versionieren. Auf Gitea würde ich das Repository abbilden, und am Ende der Kette müsste mein Runner bei jeder Änderung der Konfiguration ein Auto-Deploy auf dem Server ausführen und die betroffenen Container anschließend neu starten.

schallbert@laptop:/server-config-files –> repository –> Gitea –> act-runner –> server:/<service1...ServiceN>/config-files

Ich bekäme in diesem Falle den Verwaltungs-“Main” auf meinen Laptop, und der Server würde der Abbildung auf Gitea folgen.

Probleme

In beiden Fällen habe ich noch keine Möglichkeit, geänderte Konfigurationen vorab zu testen. Alles, was ich tue geht direkt nach “Prod” und wäre live. Schlimmstenfalls kann ich mir so recht leicht mein Setup zerschießen.

Ändert nun den Status Quo ante nicht, bei dem ich die Dateien direkt auf dem Server verändere. Also ein neues Problem nur in der Hinsicht, dass ich beim Aufsetzen damals noch keinen Prod-Betrieb hatte und so kein Ausfallrisiko bestand.

Lösung Zwei scheint mir komplexer umzusetzen zu sein, denn ich benötige hierfür eine Deployment-Pipeline, welche die Dateien im Repository auf meinem Server ausrollt. Zumal sich der Runner in einem Docker-Container aufhält, während die Konfigurationsdateien direkt im Dateisystem des Servers befinden.

Ein direkter Durchgriff auf das Serverdateisystem ist zwar technisch möglich, würde aber meinem beschränkten Verständnis nach eine große Angriffsfläche für alle meine Dienste bedeuten, deren Konfigurationsdateien nun über das Repository in Gitea direkt manipulierbar würden.

Auswahl meiner Lösung

Lösung Zwei lagert mir das Sofort-Live-Problem zumindest auf meinen Laptop vor, sodass ich in einem ersten Schritt nicht direkt am Prod-System herumfuhrwerken muss. Hier ließe sich, denke ich, leichter eine Integrationsumgebung aufsetzen, mit der ich meine Konfigurationsänderungen vorab prüfen kann. Da ich alle meine Dienste im Docker laufen habe, könnte sich das vielleicht ganz bequem lösen lassen.

Frisch ans Werk

Konfigurations-Repo anlegen

Gut, dann ziehe ich mir in einem ersten Schritt die Konfigurationsdateien vom Server. Dafür nutze ich das Dateitransferkommando scp: scp server:/path/to/source path/to/target etwa ein Dutzend mal, bis ich alle Konfigurationsdateien auf meinem Server erwischt habe.

Ich setze die Ordnerstruktur in diesem Repo direkt so auf, wie die Dateien auf dem Server liegen. So, hoffe ich, mache ich mir das Leben später etwas leichter.

Secrets in `docker-compose.yml`

Nur - was tue ich mit “secrets” in den Konfigurationsdateien? Also privaten Schlüsseln, registration tokens, hashes? Die möchte ich lieber nicht mehr oder minder offen im Repository herumliegen haben. Bei Verwendung von docker-compose ist das das recht einfach: Ich kann geheime Werte in versteckte Dateien für Umgebungsvariablen auslagern und vom Git-Tracking ausnehmen. Im einfachsten Falle heißen solche Dateien schlicht .env und beinhalten eine Aufzählung an Umgebungsvariablen im Stil von

BORG_PASSPHRASE="<redacted>"

In der entsprechenden docker-compose.yml ziehe ich die Variable aus der Datei .env wie folgt an:

- BORG_PASSPHRASE=${BORG_PASSPHRASE}

Diese Änderungen nehme ich direkt mal lokal auf meinem Laptop vor. Über die .gitignore teile ich mittels .* mit, dass versteckte Dateien und damit .env nicht ins Repository aufgenommen werden sollen. Doch woher weiß ich nun, ob die Container noch korrekt hochfahren?

Secrets in Giteas `app.ini`

Bei Gitea habe ich mich schon deutlich schwerer damit getan, Secrets in Dateien auszulagern. Die app.ini wird auch von Gitea dynamisch geschrieben, sodass die Datei bei jedem Neustart des Services ein wenig anders aussieht. Nach langer Recherche fand ich dieses Issue, in welchem eine Lösung für das separate Speichern von Secrets gesucht und gefunden wurde.

Sinnvoll erscheint mir nur das separate Speichern der Werte INTERNAL_TOKEN sowie SECRET_KEY.
Die anderen beiden Properties LFS_JWT_SECRET und JWT_SECRET werden ohnehin automatisch generiert und regelmäßig überschrieben.

In meiner Konfiguration verwende ich lediglich INTERNAL_TOKEN. Also werde jenes im Klartext und ohne Anführungszeichen in eine versteckte Datei kopieren (.INTERNAL_TOKEN) und sie per Docker-Volume dem Container zur Verfügung stellen:

# Gitea's docker-compose.yml
# [...]
 volumes:
 - ./.INTERNAL_TOKEN:/run/secrets/INTERNAL_TOKEN:ro
 # [...]

In der app.ini ist es nun wichtig, den in der Composedatei angegebenen Pfad einzusetzen:

# Gitea's app.ini
# [...]
 server:
 INTERNAL_TOKEN = /run/secrets/INTERNAL_TOKEN
 # [...]

Nicht etwa wie im oben verlinkten Issue angegeben INTERNAL_TOKEN_URI=/run/secrets/INTERNAL_TOKEN, denn dies erzeugt in der von mir momentan verwendeten V1.22.1 einen Fehler: Unsupported URI-Scheme.

Mal ganz grob testen

Um zu prüfen, ob die geänderten Konfigurationsdateien noch funktionieren, installiere ich mir docker und docker-compose auf meinem Laptop. Anschließend probiere ich, die Container mal hochzufahren.

# docker console log
Error: Network 'caddy-proxy' declared as external, but could not be found.

Stimmt ja, Docker ist hier noch gar nicht konfiguriert. Also das Netzwerk erstellen: sudo docker network create caddy-proxy und erneut versuchen. Schon beginnt der Download von Gitea samt Abhängigkeiten und der Container startet - wenn auch nicht so wie ich mir das vorgestellt habe: Innerhalb von Docker stimmen die Ordnerberechtigungen nicht, sodass weder Gitea, noch Act-runner auf alle benötigten Dateien zugreifen kann.

Dennoch, einen ersten Fehler finde ich:

# gitea container log
WARNING: The GITEA_RUNNER_REGISTRATION_TOKEN variable is not set. Defaulting to a blank string.

Ich hatte nämlich vergessen, den Token-String in Anführungszeichen zu setzen.

Für eine voll funktionsfähige Integrationsumgebung musste ich also noch mindestens zwei weitere Probleme lösen: Ordnerberechtigungen für den Main auf meinem Laptop müssen so angelegt sein, dass auch der User Docker Schreibrechte bekommt. Als einfache Lösung genügt vorerst, den betreffenden Volumes ein :Z anzuhängen und sie so als private unshared kennzuzeichnen. Eine Volumendefinition sieht in meiner docker-compose.yml nun so aus:

# gitea/docker-compose.yml
# [...]
volumes:
 - ./gitea:/data:Z
 # [...]

Ich benötige eine zweite Datei für Umgebungsvariablen, um meine Dienste auf localhost umzubiegen. Immerhin startet der Service auch so und ich sehe die Logausgabe. Die meisten Konfigurationsfehler kann ich bereits jetzt entdecken.

Ich bin mir nicht sicher, aber möglicherweise bekomme ich zusätzliche Probleme mit dem caddyserver wie Zertifikatsverwaltung, Proxy-Einstellungen und so weiter.

Eine Deploy-Pipeline erstellen

Jetzt wäre es noch super, wenn die in das Gitea-Repo hochgeladenen (und vorab lokal auf Funktion getesteten) Dateien automatisch ihren Weg auf meinen Server finden würden. Hierfür könnte ich ein weiteres Docker-Volume anlegen, wo act-runner dann die per on:push Trigger abgelegten Daten hinpackt. Sie würden dann auf meinem Server verfügbar werden.

Setup

Erinnern wir uns an meine letzten Versuche mittels act_runner Artefakte auf dem Server bereit zu stellen, so können wir einen Großteil dessen auch für diese Aufgabe übernehmen:

# deploy-to-server.yml
# Workflow for saving the server's config repo to the local disk system

name: Upload-server-config
run-name: ${{ gitea.actor }} uploads server configuration files
on:
 push:
 branches:
 - main

jobs:
 # Deploy job
 build:
 runs-on: ubuntu-latest # this is the "label" the runner will use and map to docker target OS
 container: 
 volumes: 
 # left: where the output will end up on disk, right: volume name inside container
 - /opt/server-config:/workspace/schallbert/server-config/tmp

 steps:
 - name: --- CHECKOUT ---
 uses: actions/checkout@v3
 with: 
 path: ./tmp
 - name: --- RUN FILE CHANGE TRIGGER ---
 run: |
 cd ./tmp/automation-hooks-trigger
 touch server-config-update.txt

Merkwürdige Volumefehler

Doch der Weg bis hierhin war steinig. Lange hatte ich unter volumes: auf der Containerseite lediglich /server-config angegeben und nicht das Arbeitsverzeichnis des Runners. Dann läuft die Action zwar durch und alle Befehle der #TEST-Sektion funktionieren auch. Wenn ich aber auf meinem Server nachschaue, bleibt der von Docker angelegte server-config Ordner leer.

Mit folgenem Debug-Code unter RUN FILE CHANGE TRIGGER helfe ich mir, die Pfadfehler zu finden:

# deploy-to-server.yml
# [...]
run: |
 echo "hello world"
 touch updated.txt
 pwd
 ls -al

Mit echo prüfe ich, ob mein Code im Runner überhaupt ausgeführt wird. Das touch-Kommando setzt mir den aktuellen Zeitstempel in die updated.txt-Datei, sodass ich dies später als “Hook” für weitere Automation verwenden kann. pwd zeigt mir den aktiven Pfad innerhalb des Runners an, sodass ich das Docker-Volume korrekt auf die Server-Festplatte abbilden kann. ls -al zeigt mir, ob die im Schritt CHECKOUT zusammengestellten Konfigurationsdateien korrekt geschrieben wurden.

Ich erkenne dadurch, dass der Volume-Pfad auf der “rechten Seite” falsch war. Ich biege ihn entsprechend auf das aktive Verzeichnis des Runners um:

# deploy-to-server.yml
# [...]
 # left: where the output will end up on disk, right: volume name inside container
 - /opt/server-config:/workspace/schallbert/server-config/
# [...]

Anschließend bekam ich Folgendes zu lesen:

# gitea / act-runner console log
failed to create container: 'Error response from daemon: Duplicate mount point: /workspace/schallbert/server-config'

Anscheinend legt sich der Runner die “rechte Seite” des Mountpoints automatisch selbst an und kann daher nicht erneut belegt werden. Erst durch das Hinzufügen eines weiteren Pfadteiles, in meinem Falle /tmp - siehe oben - behebe ich den Fehler und auf meinem Server erscheint endlich 😌 der lang ersehnte Ordner server-config mit Inhalt:

schallbert@schallbert-ubuntu-:/opt/server-config# ls -al
total 52
drwxr-xr-x 9 root root 4096 Jul 12 15:38 .
drwxr-xr-x 9 root root 4096 Jul 11 19:56 ..
-rwxr-xr-x 1 root root 395 Jul 11 20:05 boot-after-backup.sh
drwxr-xr-x 3 root root 4096 Jul 11 20:05 borgmatic
drwxr-xr-x 2 root root 4096 Jul 11 20:05 caddy2
drwxr-xr-x 3 root root 4096 Jul 11 20:05 fail2ban
drwxr-xr-x 8 root root 4096 Jul 12 15:38 .git
drwxr-xr-x 3 root root 4096 Jul 11 20:05 .gitea
drwxr-xr-x 4 root root 4096 Jul 11 20:05 gitea
-rw-r--r-- 1 root root 312 Jul 11 20:05 .gitignore
-rw-r--r-- 1 root root 557 Jul 11 20:05 README.md
-rwxr-xr-x 1 root root 371 Jul 11 20:05 shutdown-for-backup.sh
-rw-r--r-- 1 root root 0 Jul 12 15:38 updated.txt
drwxr-xr-x 2 root root 4096 Jul 11 20:05 watchtower

Verteilen der Konfiguration auf dem Server

Gut, damit sind die ersten Schritte getan. Ich habe nun ein vernünftig konfiguriertes Git-Repository, was meine Server-Konfiguration abbildet und vom Laptop aus gepflegt und zumindest rudimentär getestet werden kann. Außerdem kann ich über eine automatische Action Updates der Konfiguration auf dem Server ablegen und eine Update-Datei mit Zeitstempel beschreiben.

Nun muss das Update auf dem Server noch entgegengenommen, verteilt und die betroffenen Programme und Dienste sollen neu gestartet werden. Doch dies schauen wir uns im Artikel Serverkonfiguration ausrollen an.

🗸 Gitea Actions Teil2 - Jekyll-Dockerimage

Schallbert — Sat, 09 Dec 2023

Die Vorgeschichte

Leider hatte ich im Teil1 mit einer leicht modifizierten Kopie der Github-Action zum Bauen von Jekyll kein Glück. Daher wollte ich nun probieren, Jekyll direkt als Dockerimage laufen zu lassen. Im Docker hub gab es nicht so furchtbar viel Auswahl. Trotzdem habe ich ein (in 2023) aktiv gewartetes und gut dokumentiertes Image finden können.

“Set up job”

Und so binde ich das Docker-Jekyllimage dann in meinen workflow ein:

# workflows/jekyll-build-action.yml
jobs:
 # Build job
 build:
 runs-on: ubuntu-latest # this is the "label" the runner will use and map to docker target OS
 container: jvconseil/jekyll-docker
# [...]

Hier wird dem gitea act_runner gesagt, dass er mit dem ubuntu-latest label laufen soll, was in meinem Fall auf eine sehr kleine und schnell hochzufahrende node16:bullseye Maschine (abgeleitet vom Betriebssystem Debian11) gemappt wird. Zusätzlich wird Docker mitgeteilt, dass bitte das jekyll-docker image zu laden ist, wo die von mir benötigten Abhängigkeiten (Ruby, Sass, Jekyll…) bereits berücksichtigt wurden.

bundle install

Das Bauen schlägt hier allerdings fehl wegen in der Gemfile angegebenen, aber nicht installierten Abhängigkeiten. Das kann dann so ählich aussehen wie hier:

bundler: failed to load command: jekyll (/usr/gem/bin/jekyll)
/usr/local/lib/ruby/gems/3.2.0/gems/bundler-2.4.22/lib/bundler/resolver.rb:332:in `raise_not_found!': Could not find gem 'github-pages' in locally installed gems. (Bundler::GemNotFound)
	from /usr/local/lib/ruby/gems/3.2.0/gems/bundler-2.4.22/lib/bundler/resolver.rb:392:in `block in prepare_dependencies'

Bundler ist der Paketmanager für in Ruby geschriebene Software. Ähnlich wie npm für Javascript oder pip für Python ist bundler in der Lage, von einem Ruby-Programm genutzte Bibliotheken und andere Abhängigkeiten herunterzuladen und so einzubinden, dass sie ohne weitere Konfiguration auf dem Zielsystem verwendet werden können. Damit bundler weiß, was zu installieren ist, wird eine sogenannte Gemfile angelegt.

Also dem Script schnell bundle install hinzufügen, etwa so:

# workflows/jekyll-build-action.yml
# [...]
 steps:
 - name: --- CHECKOUT ---
 uses: actions/checkout@v3
 - name: --- INSTALL GEMS ---
 run: bundle install # will fail with permissions rights to write to Gemfile.lock but anyways installs required dependencies.
 - name: --- BUILD WITH JEKYLL ---
 # Outputs to the './_site' directory by default
 run: bundle exec jekyll build --destination /opt/blog_staging
 env:
 JEKYLL_ENV: production

act_runner: Kein Schreibzugriff auf `Gemfile.lock`

Dies schlägt wieder fehl - wegen fehlender Schreibrechte des act_runner:

gitea-runner-1 | [Deploy Jekyll site/build] | `/workspace/schallbert/blog/Gemfile.lock`. It is likely that you need to grant
gitea-runner-1 | [Deploy Jekyll site/build] | write permissions for that path.
gitea-runner-1 | [Deploy Jekyll site/build] ❌ Failure - Main ---INSTALL GEMS ---
gitea-runner-1 | [Deploy Jekyll site/build] exitcode '23': failure

Nach langer Suche muss ich feststellen, dass Gemfile.lock auf meinem Rechner nicht der Versionskontrolle unterliegt, da es in der .gitignore auftaucht. Der Bundler des act_runner versucht nun also, diese Datei selbst aus der Gemfile zu erzeugen und scheitert, weil keine Schreibrechte auf dem Repository bzw. der temporären Kopie vorliegen.

Dies lässt sich am besten beheben, indem die Gemfile.lock in die Versionskontrolle aufgenommen wird, d.h. aus der .gitignore verschwindet. Somit stelle ich sicher, dass ich für das lokale Bauen auf meinem Laptop dieselben Umgebungsbedingungen habe wie auf dem Server.

Abhängigkeiten: `sass-embedded`

Nach weniger als 20 Sekunden die nächste Fehlermeldung:

Resolving dependencies...
Could not find gem 'sass-embedded (= 1.69.5)' with platform 'x86_64-linux' in
rubygems repository https://rubygems.org/ or installed locally.

Nach weiteren Minuten der Recherche die Lösung: In der Gemfile eine bestimmte Version des jekyll-sass-converter spezifizieren oder alternativ das Gem “github-pages” in der Gemfile belassen. Dieses kümmert sich ebenfalls darum, dass der CascadingStyleSheets (CSS) Präprozessor Sass vorhanden ist.

Nun endlich läuft bundle install erfolgreich durch:

✅ Bundle complete! 5 Gemfile dependencies, 43 gems now installed.

jekyll build

Damit Jekyll die gebauten Dateien auch irgendwo abspeichern kann, habe ich dem act_runner in der docker-compose.yml ein weiteres Volume gegönnt:

# gitea/docker-compose.yml
# [...]
volumes:
 - ./runner/blog_staging:/opt/blog_staging
 - ./runner/data:/data
 - /var/run/docker.sock:/var/run/docker.sock

Und jetzt direkt nochmal probieren, ob Jekyll erfolgreich baut:

 Destination: /opt/blog_staging
 Generating... 
 Jekyll Feed: Generating feed for posts
jekyll 3.9.3 | Error: Permission denied @ dir_s_mkdir - /opt/blog_staging
/usr/local/lib/ruby/3.2.0/fileutils.rb:406:in `mkdir': Permission denied @ dir_s_mkdir - /opt/blog_staging (Errno::EACCES)
	from /usr/local/lib/ruby/3.2.0/fileutils.rb:406:in `fu_mkdir'

Auch dieses Problem lässt sich leicht lösen, indem man entweder nach /tmp baut, wo der user jekyll während des Bauens ebenfalls Zugriff hat, oder indem man der Action vor dem jekyll build-Befehl einen Nutzerwechsel im Build-Arbeitsverzeichnis vornimmt: chown -R jekyll /opt/blog_staging.

Mit dieser Änderung läuft die Action endlich durch.

Artefakte transferieren

Doch wo finde ich jetzt die in der Action gebauten Dateien, welche mein Webserver dann veröffentlichen soll? Der _site-Ordner ist nirgendwo zu finden - weder auf dem Volume der Hostmaschine, noch im Gitea-Dockercontainer oder im Runner!

Docker volumes für `act_runner` können Artefakte nicht verteilen

Dass ich über Docker volumes nicht dort herankomme erscheint logisch wenn man weiß, wie act-runner funktioniert: Die Action erzeugt ein eigenes Dockerimage mit wiederum per Task-ID assoziierten Volumes, welches nur für dessen Laufzeit existiert.

DRIVER VOLUME NAME
--> local GITEA-ACTIONS-TASK-84_WORKFLOW-Deploy-Jekyll-site_JOB-build <--
--> local GITEA-ACTIONS-TASK-84_WORKFLOW-Deploy-Jekyll-site_JOB-build-env <--
local act-toolcache
local blog_staging

Legt man die Artefakte also nirgendwo extern ab, so werden sie nach Durchlauf der Aktionen zusammen mit dem Image demontiert und sind futsch. Das oben angelegte Volume des Runners hat gar keine Auswirkung auf die Action, weil sie wieder in einem isolierten Image läuft.

Dies zu verstehen hat mich einige Zeit und Fehlversuche gekostet, dabei ist es in einem Abschnitt der Dokumentation beschrieben.

Das Ganze gestaltet sich ja deutlich komplizierter als ich dachte. Mit Kanonen auf Spatzen schießen angesichts meiner kleinen Website und als Einziger, der sie pflegt. Egal, ich ziehe das jetzt durch.

Aber man kann doch `upload-artifact` verwenden!

Na ja, das dachte ich jedenfalls. Also habe ich mein Action-Skript entsprechend erweitert und die von Github Actions zur Verfügung gestellte Funktion eingebaut:

# workflows/jekyll-build-action.yml
# [...]
# Automatically upload the build folder to Giteas blog repo folder
 - name: --- UPLOAD ARTIFACT ---
 uses: actions/upload-artifact@v3
 with:
 path: /workspace/schallbert/blog/
 name: Blog_Staging
 retention-days: 2

Super, jetzt erscheint ein herunterladbares Zip-file auf der Weboberfläche von Gitea:

Nur: Wie bekomme ich das Ding jetzt automatisiert auf meine Serverinstanz? Schließlich kennt die Action diese nicht - sie hat ja nicht einmal einen eigenen Docker Daemon.

Also schaue ich mal im Gitea-Container selbst nach, wo die Artefakte unter /data/gitea/actions_artifacts/BUILD_ID abgelegt sind. Allerdings als ein Haufen (hunderte) .chunk.gz Dateien mit kryptischen Nummernfolgen als Name, bei denen ich wiederum nicht weiß wie ich sie zu einem Archiv zusammenfügen soll.

Und noch etwas gefällt mir an upload-artifact nicht: Da meine Website inzwischen eine Menge Bilder, Audiodateien und Videos enthält, ist sie recht groß. Daher benötigt der uploader für’s Verpacken und Versenden schon jetzt fast zwei Minuten - Tendenz linear steigend mit der Anzahl meiner Medieninhalte.

Sackgasse.

Auch Docker `cp` funktioniert in diesem Falle nicht

Dann versuche ich mit Hilfe des Kopierbefehls von Docker, die Artefakte auf meinen Host zu transferieren:

# workflows/jekyll-build-action.yml
# [...]
- name: --- COPY ARTIFACT ---
 run: docker cp gitea-runner-1:/workspace/schallbert/blog /tmp/blog_staging

Dies schlägt wieder fehl:

gitea-runner-1 | docker cp gitea-runner-1:/workspace/schallbert/blog /tmp/blog_staging
[...]
gitea-runner-1 | [Deploy Jekyll site/build] | /var/run/act/workflow/3.sh: line 2: docker: not found
gitea-runner-1 | [Deploy Jekyll site/build] ❌ Failure - Main --- COPY ARTIFACT ---

Auch erwartbar, denn der Action-Container selbst kennt kein Docker. Es ist also nicht möglich, etwas von “innerhalb” des Containers per Docker heraus zu bekommen. Dies ist für mich aber erforderlich, da die Action ja den ganzen Prozess vollständig automatisieren soll.

Oder geht es doch irgendwie? Der Daemon der Hostmaschine docker.sock steht laut Giteas Dokumentation zumindest dem act_runner per Volume zur Verfügung - wird aber scheinbar nicht in die Action weitergeleitet. Vielleicht aus gutem Grund, sonst wäre die Kapselung futsch und eine schadhafte Action könnte praktisch meinen Docker Daemon auf dem Host kapern 😰.

Transferieren per SFTP würde klappen

So langsam gehen mir die Alternativen aus. Ich überlege nun, die Artefakte per SFTP aus dem vom act_runner erzeugten Action-Dockerimage heraus in den Webserver-Container zu schieben¹.

Glücklicherweise gibt es hierfür wieder eine vorgefertigte Action: scp-files. Nun muss ich aber den Container des Webservers so umbauen, dass er per SCP erreichbar ist und den SSH-Schlüssel der Action akzeptiert.

Andererseits wird davor in vielen Foren gewarnt - Ein Container sollte nur eine Applikation beherbergen. Aber auch hier gibt es eine Lösung: ein eigener Docker-Container mit SSH-Daemon. Diesem könnte ich dann ein Volume geben, welches er mit dem Webserver teilt.

Sieht leider nach einigem Aufwand aus. Und ich möchte als fauler Entwickler mein System so einfach wie möglich halten - also recherchiere ich weiter.

Dem Action-Container ein Volume zur Verfügung stellen

Diese ganzen Fehlschläge und Sackgassen begleiten mich jetzt schon seit über einem Monat. Ich will es trotzdem unbedingt schaffen, vollautomatisch bauen, testen und veröffentlichen zu können. Auf dem Weg hierhin habe ich eine Menge gelernt und jetzt hoffe ich, dass dieser Ansatz mich endlich zur Lösung bringt.

Bei meiner Suche stieß ich auf die Möglichkeit, die Konfiguration des Runners zu verändern. So könnte ich am Ende vielleicht doch noch ein Volume einbinden, welches ich zwischen der Action und meinem Server über den Daemon auf dem Host teilen kann.

Wenn das klappt, hätte ich kein zusätzliches Sicherheitsrisiko wie ein öffentlich verfügbarer file transfer container oder die langen Wartezeiten durch upload-artifact. Also frisch ans Werk! Es gibt noch weitere Gründe, weswegen Volumes in der jeweiligen Action Sinn machen können - es muss also bereits Leute da draußen geben, die das hinbekommen haben.

Ich versuche also, die Volumes im Action-Skript anzulegen:

# workflows/jekyll-build-action.yml
# [...]
container: 
 image: jvconseil/jekyll-docker:latest
 volumes: 
 - /tmp/blog_staging:/blog_staging
 - /opt/cache:/opt/hostedtoolcache

Doch irgendwie landen die Artefakte noch immer nicht auf der Platte meines Hosts. Ich vereinfache die Action soweit, dass ich nur noch prüfe, ob die Erzeugung des Volumes auch einen entsprechenden Ordner anlegt:

# workflows/jekyll-build-action.yml
# [...]
steps:
 - name: --- CHECK_VOLUME ---
 run: |
 ls -al /blog_staging

und schon schlägt die Aktion wieder fehl:

gitea-runner-1 | [Deploy Jekyll site/build] [DEBUG] Working directory '/workspace/schallbert/blog'
gitea-runner-1 | [Deploy Jekyll site/build] | ls: /blog_staging: No such file or directory
gitea-runner-1 | [Deploy Jekyll site/build] ❌ Failure - Main --- CHECK_VOLUME ---

Nach ein paar weiteren, erfolglosen Versuchen (vielleicht hatte ich etwas falsch geschrieben?) und langer Recherche in den Foren fand ich heraus, dass es das valid_volumes Attribut im act gibt - taucht das Volume dort nicht auf, so wird es auch nicht eingebunden.

OK, also schnell der Action hinzugefügt:

# jekyll-build-action.yml
# [...]
container: 
 image: jvconseil/jekyll-docker:latest
 valid_volumes: 
 - '**' # This does not work. Also specialized lists indicating the volumes directly won't work
 volumes: 
 - /tmp/blog_staging:/blog_staging
 - /opt/cache:/opt/hostedtoolcache

Aber immer noch nichts. Immerhin kann ich in den Logs mit dem Wissen über valid_volumes jetzt eine Warnung entdecken:

gitea-runner-1 | [Deploy Jekyll site/build] [/tmp/blog_staging] is not a valid volume, will be ignored
gitea-runner-1 | [Deploy Jekyll site/build] [/opt/cache] is not a valid volume, will be ignored

Etwas stimmt mit der Übergabe dieser Option nicht. Also recherchiere ich weiter. Es gibt Berichte, in denen das Anmelden der Volumes funktioniert. Also erzeuge ich nach Anleitung eine Konfigurationsdatei, wo ich das Folgende eintrage:

# runner/config.yml

# Volumes (including bind mounts) can be mounted to containers. Glob syntax is supported, see https://github.com/gobwas/glob
 # You can specify multiple volumes. If the sequence is empty, no volumes can be mounted.
 # For example, if you only allow containers to mount the `data` volume and all the json files in `/src`, you should change the config to:
 # valid_volumes:
 # - data
 # - /src/*.json
 # If you want to allow any volume, please use the following configuration:
 # valid_volumes:
 # - '**'
 valid_volumes: ["/tmp/blog_staging", "/opt/hostedtoolcache"]

Wichtig: Die Notation muss als String vorliegen, kommasepariert, und gibt stets die Source des Volumes an. Also den Teil, der vor dem : steht. Doch noch immer erscheint beim Bauen die Fehlermeldung “not a valid volume”.

Doch dann fällt mir auf, dass die Config dem act_runner selbst als Volume zur Verfügung gestellt werden muss - sonst kann der im Container laufende Runner ja gar nicht darauf zugreifen!

Daher sieht meine docker-compose.yml für Gitea, Abschnitt “runner” nun wie folgt aus:

# gitea/docker-compose.yml
# [...]
 runner:
 image: gitea/act_runner:latest
 environment:
 - CONFIG_FILE=/config.yml
 - GITEA_INSTANCE_URL=https://git.schallbert.de
 - GITEA_RUNNER_NAME=ichlaufe
 - GITEA_RUNNER_REGISTRATION_TOKEN= <redacted>
 volumes:
 - ./runner/config.yml:/config.yml
 - ./runner/data:/data
 - /opt/hostedtoolcache:/opt/hostedtoolcache
 - /var/run/docker.sock:/var/run/docker.sock

Und endlich:

gitea-runner-1 | ls -al /blog_staging
gitea-runner-1 | [Deploy Jekyll site/build] | total 8
gitea-runner-1 | [Deploy Jekyll site/build] | drwxr-xr-x 2 root root 4096 Dec 27 07:32 .
gitea-runner-1 | [Deploy Jekyll site/build] | drwxr-xr-x 1 root root 4096 Dec 27 07:46 ..
gitea-runner-1 | [Deploy Jekyll site/build] ✅ Success - Main --- CHECK_VOLUME ---

Was für ein Akt. Ich bin so froh, dass jetzt alles durchläuft und ich auf meinem lokalen Hostsystem tatsächlich die gebauten Dateien vorfinde! 🥳

Noch ein letzter Tipp

Wenn ihr so wie ich mit einem Reverse Proxy arbeitet und so komische connection refused Fehlermeldungen beim Hochfahren des Runners erhaltet wie:

docker compose up
[+] Running 2/0
 ✔ Container gitea Created 0.0s 
 ✔ Container gitea-runner-1 Created 0.0s 
Attaching to gitea, gitea-runner-1
gitea-runner-1 | level=info msg="Starting runner daemon"
gitea-runner-1 | level=error msg="fail to invoke Declare" error="unavailable: dial tcp <address>: connect: connection refused"
gitea-runner-1 | Error: unavailable: dial tcp <address> connect: connection refused
gitea | Server listening on :: port 22.
gitea-runner-1 exited with code 1

Dann ist euer Reverse Proxy entweder falsch eingestellt oder - wie in meinem Falle - nicht hochgefahren.

Die Nutzung des SFTP (Secure File Transfer Protocol), also der Dateitransfer über ssh (secure shell), erhöht die Angriffsfläche meines Systems ein wenig. Der SSH-Dienst ist nämlich dann nicht nur für meine Action, sondern ganz allgemein von außen erreichbar. ↩︎

🗙 Gitea Actions - Jekyll Workflow

Schallbert — Thu, 30 Nov 2023

Nachdem ich in diesem Projekt meinen eigenen, kleinen Server aufgesetzt und mit den entsprechenden Programmen zum Hosten meines Blogs ausgestattet habe, möchte ich ihn nun in die Lage versetzen, die Website automatisch zu bauen.

Gewünschter Ablauf

Ich möchte folgendes erreichen: Sobald Gitea eine push-Aktion auf dem Blog-Repository verzeichnet, soll ein Action Runner in einem eigenen Docker-Container loslaufen und Ruby, Bundler, Jekyll sowie sämtliche Abhängigkeiten nachladen. Dann soll der Runner meine Quelldateien für den Blog kopieren und dem bundle exec jekyll build Prozess zur Verfügung stellen, welcher dann die Website baut und schließlich im _site-Ordner ablegt. Anschließend soll der Runner sich selbst beenden und alle in Anspruch genommenen Ressourcen wieder freigeben.

An dieser Stelle möchte ich nachkontrollieren können, ob die Website fehlerfrei gebaut wurde und in Zukunft eventuell noch ein paar weitere Prüfungen darüberlaufen lassen - z.B. kaputte Links erkennen, nicht angezeigte Bilder markieren, Rechtschreibprüfung durchführen.

Die Freigabe sowie die Veröffentlichung soll dann ein anderer Prozess übernehmen, um den ich mich später kümmere.

Ausgangspunkt: Github Actions

Wie üblich wildere ich erst einmal bei anderen Menschen, die ein ähnliches Problem für sich bereits gelöst haben. Ich wurde im Github Actions starter-workflows Repository von Github selbst fündig und habe die Workflowdatei für Jekyll mit leichten Modifikationen direkt mal mit meiner Gitea-Instanz ausprobiert:

# jekyll-build-pages.yml
# Sample workflow for building and deploying a Jekyll site
name: Deploy Jekyll site
run-name: ${{ gitea.actor }} builds Jekyll site
on: [push]

jobs:
 # Build job
 build:
 runs-on: ubuntu-latest
 steps:
 - name: Checkout
 uses: actions/checkout@v3
 - name: Setup Ruby
 uses: ruby/setup-ruby@55283cc23133118229fd3f97f9336ee23a179fcf # v1.146.0
 with:
 ruby-version: '3.1' # Not needed with a .ruby-version file
 bundler-cache: true # runs 'bundle install' and caches installed gems automatically
 cache-version: 0 # Increment this number if you need to re-download cached gems
#[...]

Nachdem ich diesen Workflow in mein Blogverzeichnis unter workflows/jekyll.yml hochgeladen hatte, lief der Runner tatsächlich direkt los:

Probleme mit der Ruby-Installation

Schon mal prima. Allerdings wenig erbaulich, dass bereits bei der Installation von Ruby etwas nicht passt. Werfen wir einen Blick in die Logs:

::error::The current runner (debian-11-x64) was detected as self-hosted because the platform does not match a GitHub-hosted runner image 
(or that image is deprecated and no longer supported).
In such a case, you should install Ruby in the $RUNNER_TOOL_CACHE yourself, for example using https://github.com/rbenv/ruby-build
You can take inspiration from this workflow for more details: 
https://github.com/ruby/ruby-builder/blob/master/.github/workflows/build.yml

Na, das ist doch mal eine hilfreiche Fehlermeldung!

Der Runner läuft um Ressourcen zu sparen standardmäßig im Docker mit einem abgespeckten Image basierend auf Debian namens node:16-bullseye (Referenz). Scheinbar ist dieser nicht kompatibel mit dem unter Ubuntu22 betriebenen Github Actions Runner. Ich habe also ein paar Lösungsmöglichkeiten zur Verfügung:

Möglichkeiten zur Fehlerbehebung

Den Runner über seine “Labels” auf Ubuntu22.04 umsatteln.
Ren Runner nicht im Docker, sondern nativ auf dem Server laufen lassen.
Wie in der Fehlermeldung vorgeschlagen, Ruby im Cache des Runners vorinstallieren.
Ein Jekyll-Dockerimage verwenden, welches Jekyll bereits im Gepäck hat und nicht erst die Installation benötigt.

Den Runner mit Ubuntu22 statt Node16 betreiben

Das entsprechende Dockerimage existiert zwar. Aber es kostet aber einen Haufen Speicherplatz auf meinem Server, benötigt durch seinen größeren Funktionsumfang mehr RAM und braucht vor allem länger, bis es hochgefahren ist.

Und Zeit ist bei Runnern wertvoll, schließlich will ich ja möglichst schnell wissen, ob das Bauen geklappt hat.

Den Runner direkt auf der Hostmaschine (Ubuntu22) laufen lassen

Ist sicherheitstechnisch nicht so sehr zu empfehlen (Bei einem ungeschützten Branch würde der Runner von Dritten per git push --force hochgeschobenen Schadcode unbesehen auf meiner Hostmaschine ausführen) und zudem ginge die Portabilität flöten, weil ich das Zielsystem des Runners dann fest verdrahte.

Gitea act_runner direkt auf dem Host laufen lassen

Für den zweiten Ansatz habe ich mir per Anleitung eine Konfiguration für den runner angelegt und darin das bestehende label-mapping so geändert, dass nicht mehr in Richtung Docker, sondern auf dem Ubuntu des Servers selbst gebaut wird. Dafür genügt es in meinem Fall, das Label ubuntu-latest:host statt ubuntu-latest in die Konfiguration zu schreiben. Leider erhielt ich hier Fehlermeldungen bei den Zugriffsrechten des Runners, welcher aus Docker heraus auf dem Hostsystem laufen müsste.

Nicht so schlimm, ich wollte diese Lösung wegen der oben beschriebenen möglichen Probleme sowieso nicht dauerhaft verwenden. Also investiere ich hier keine weitere Zeit.

Ruby im Cache vorinstallieren

Wie von der Fehlermeldung empfohlen habe ich dieser Anleitung folgend in der docker-compose.yml von Gitea ein Volume angelegt für den Tool Cache des runners und das Zielverzeichnis in der Umgebungsvariable RUNNER_TOOL_CACHE abgelegt.

# gitea/docker-compose.yml
# [...]
runner:
 image: gitea/act_runner:nightly
 environment:
 - GITEA_INSTANCE_URL=<redacted>
 - GITEA_RUNNER_NAME=<redacted>
 - RUNNER_TOOL_CACHE=/opt/hostedtoolcache
 - GITEA_RUNNER_REGISTRATION_TOKEN= <redacted>
 volumes:
 - ./runner/data:/data
 - /opt/hostedtoolcache:/opt/hostedtoolcache
 - /var/run/docker.sock:/var/run/docker.sock

Hiermit wird dem in Docker laufenden Runner der Ordner /opt/hostedtoolcache im Dateisystem des Hosts unter dem Namen /opt/hostedtoolcache zur Verfügung gestellt. Nun probiere ich mal, Ruby direkt dort hinein zu installieren.

Also lade ich das ruby-build repository herunter (git clone) und lasse das Installerscript mit ./ruby-build/install.sh durchlaufen. Danach führe ich den Build mit dem in der Fehlermeldung angegebenen Pfad aus: ruby-build 3.1.4 /opt/hostedtoolcache/Ruby/3.1.4/x64

==> Downloading openssl-3.1.4.tar.gz...
 % Total % Received % Xferd Average Speed Time Time Time Current
 Dload Upload Total Spent Left Speed
100 14.8M 100 14.8M 0 0 81.3M 0 --:--:-- --:--:-- --:--:-- 81.1M
==> Installing openssl-3.1.4...

BUILD FAILED (Ubuntu 22.04 on x86_64 using ruby-build 20231114)

Probleme mit prebuilt-Ruby

Das Log zeigt das Problem:

[...] No C compiler found, please specify one with the environment variable CC [...]

Also tippe ich apt install build-essential und stelle dann mit which gcc fest, dass er nun unter /usr/bin/gcc installiert ist. Auf ein Neues!

crypto/comp/c_zlib.c:36:11: fatal error: zlib.h: No such file or directory

Dann schnell apt install libz-dev eingeben und erneut probieren. Dieses mal läuft er recht lange, dann:

*** Following extensions are not compiled:
openssl:
 Could not be configured. It will not be installed.
 /tmp/ruby-build.20231205114312.9174.0gmhNf/ruby-3.1.4/ext/openssl/extconf.rb:100: OpenSSL library could not be found. You might Check ext/openssl/mkmf.log for more details.
readline:
 Could not be configured. It will not be installed.
 /tmp/ruby-build.20231205114312.9174.0gmhNf/ruby-3.1.4/ext/readline/extconf.rb:62: Neither readline nor libedit was found
 Check ext/readline/mkmf.log for more details.
*** Fix the problems, then remove these directories and try again if you want.
[...]

OK, nun ist es openssl. Fix nachinstallieren mit apt install libssl-dev sowie apt install libreadline-dev und endlich 🎉:

Installed ruby-3.1.4 to /opt/hostedtoolcache/Ruby/3.1.4/x64

Noch immer Fehler beim Bauen mit dem Github-Acitons script

Merkwürdig, das Log spuckt mir immer noch denselben Fehler aus:

💬 ::debug::isExplicit: 3.1.4

gitea-runner-1 | [Deploy Jekyll site/build] 💬 ::debug::checking cache: /opt/hostedtoolcache/Ruby/3.1.4/x64
gitea-runner-1 | [Deploy Jekyll site/build] | ::debug::checking cache: /opt/hostedtoolcache/Ruby/3.1.4/x64
gitea-runner-1 | [Deploy Jekyll site/build] 💬 ::debug::not found
gitea-runner-1 | [Deploy Jekyll site/build] | ::debug::not found
gitea-runner-1 | [Deploy Jekyll site/build] ❗ ::error::The current runner (debian-11-x64) was detected as self-hosted

Das geht auf folgende Abfage in der ausführenden Action zurück:

// setup-ruby/ruby-builder.js
if (common.shouldUseToolCache(engine, version)) {
 inToolCache = common.toolCacheFind(engine, version)
 if (inToolCache) {
 rubyPrefix = inToolCache
 } else {
 const toolCacheRubyPrefix = common.getToolCacheRubyPrefix(platform, engine, version)
 if (common.isSelfHostedRunner()) {
 const rubyBuildDefinition = engine === 'ruby' ? version : `${engine}-${version}`
 core.error( [...] )

Docker volume überprüfen

Mist. Prüfen wir schnell mal, ob Ruby in dem Volume auch wirklich verfügbar ist. Dafür suchen wir mit docker ps die Container ID des runners heraus und geben sie bei folgendem Kommando ein:

docker exec -it <containerID> bash

Dann navigiere ich in den gesuchten Ordner cd /opt/hostedtoolcache, liste dort den Inhalt mit ls und siehe da: Ruby. Es liegt also alles vor, nur wird es nicht gefunden.

Misserfolg anerkennen

So komme ich hier also nicht weiter 😖. Daher öffne ich mein Problem für die Community unter dem Titel act_runner cannot find hostedtoolcache und probiere

einen anderen Ansatz.

Problemursache

Der Support der Action setup-ruby für selbsgehostete CI-Pipelines wie meinen act_runner wurde wohl eingestellt. Die Dokumentation mit den Hinweisen zur Fehlerbehebung bei Verwendung selbstgehosteter Runner allerdings zum Zeitpunkt der Verwendung durch meine Wenigkeit war aber noch nicht auf Stand gebracht worden.

Mehrsprachige Webseiten - l10n

Schallbert — Tue, 14 Nov 2023

Die Bereitstellung einer Webseite in mehreren Sprachen wird “internationalization” - kurz i16n beziehungsweise “localization” l10n genannt. Sucht man nach diesen Begriffen im Netz, findet man eine Menge tollen Materials zum Thema. Die Zahlen in den Kurzformen dieser Begriffe geben die Anzahl Buchstaben in der Wortmitte an.

Motivation

Ich bin schon vor langer Zeit gefragt worden, ob ich nicht mal eine deutsche Version dieser Webseite anfertigen wolle. Bis dato hielt ich das für zu viel Arbeit. Dies änderte sich erst vor gut einem halben Jahr, als ich dieselbe Anfrage verbal von mehreren Leuten unabhängig voneinander in kurzer Zeit erhielt.

Also investierte ich einen Haufen freier Abende in die Fleißarbeit, rund 80 Artikel auf Deutsch zu übertragen. Doch ich war noch immer nicht fertig.

Jekyll plugin

Ich sah mich nach Möglichkeiten um, meinen Internetauftritt mit Jekyll mehrsprachig zu gestalten. Dabei fand ich unter Anderem demondehellis’ plugin-freie Lösung, untras polyglot plugin, kurtssons jekyll-multiple-languages-plugin und noch ein paar weitere Möglichkeiten, diesen Webauftritt in mehreren Sprachen anzubieten.

Nun musste ich mich für eine entscheiden. Die plugin-freie Lösung fiel recht schnell heraus, da ich “gleiche” Posts verschiedener Sprache gleich benennen wollte und damit Interlinks zwischen Beiträgen unabhängig von der verwendeten Sprache bestehen bleiben sollten - irgendwas muss also dafür sorgen, dass sich die Sprachen nicht wild mischen.

Blieben die Plugins übrig. Kurz gesagt stieß ich zufällig auf leo3418s hervorragende Artikelserie für die Implementierung von Polyglot - und so entschied ich mich für ebendieses Plugin.

Polyglot: Installation

Die Installation von Polyglot war einfach, denn sowohl die im Repository bereitgestellte readme.md als auch der von leo3418 geschriebene Blogartikel beschäftigen sich ausführlich mit den ersten Schritten. In der Tat fand ich die Dokumentation so gut, dass ich darauf verweisen möchte und hier gar nicht weiter darüber berichten werde.

Umstrukturierung der Website

Bei Polyglot gibt es zwei Möglichkeiten, die Ordnerstruktur für die Website auf mehrsprachig umzustellen:

Man benutzt das Sprachkürzel im Artikelnamen und ermöglicht so eine Zuordnung. Dieser Artikel hier würde dann z.B. heißen: 2023-11-14-jekyll-polyglot-language-support-de.md und analog in jeder weiteren Sprache mit einem anderen Sprachkürzel
Man erstellt Ordner mit dem Sprachkürzel, z.b. /de, behält aber identische Dateinamen für verschiedene Sprachen.

Ich habe mich für letzteres entschieden, um der Umbenennung meiner schon vorhandenen Artikel zu entgehen. Die Sprache wird von Polyglot auch bei Verwendung von Interlinks auf der Webseite beibehalten. Klickt man z.B. auf den Artikel https://schallbert.de/milling-small-parts/, so wird Polyglot ausgehend von der Sprache des aktuellen Artikels auch den neuen Artikel in dieser Sprache aufrufen. Einzig bei Überschriften von Abschnitten wird es schwierig: Die sind nämlich übersetzt. Also wird der Link auf die englische Version der Seite für die Überschrift #Umstrukturierung-der-Website in einem 404-Fehler enden.

Daher muss man für die Überschriften den kompletten Artikelpfad inkl. der Lokalisierung angeben. In diesem Beispiel wäre folglich /posts/en/jekyll-polyglot-language-support/#restructuring-the-website der korrekte Interlink.

Hier wird es ein wenig komplizierter. Die _config.yml von Jekyll lässt ohne Weiteres nicht zu, dass mehrere Varianten von ihr existieren. Man benötigt für sprachsensitive Parameter wie site.title oder site.description in der config daher die Möglichkeit, die Standardwerte zu überschreiben. Meine Methode das zu lösen war, im _data-Ordner eine Datei mit Namen l10n.yml anzulegen, in der dann diese Parameter abgelegt sind. Um sie dann auch korrekt anzuzeigen, sind die html-Dateien im _includes-Ordner so anzupassen, dass Parameter dieser Datei statt der config eingelesen und durch die Templatesprache Liquid dann in html umgesetzt werden. Beispiel: {{ site.data.ui-text[site.data.l10n.locale].follow_label | remove: ":" | default: "Follow" }}. Hier wird dann wie im Bild gezeigt dann in der deutschen Version FOLGEN: angezeigt und in der englischen FOLLOW:.

Sprachauswahl

Natürlich möchte ich die Möglichkeit geben, die Sprache der Website selbst zu wählen. Ich habe mich hier für das Sprachkürzel sowie die entsprechende Flagge entschieden, welche im unteren Bereich einer jeden Seite eingeblendet werden. Klickt man hier drauf, so wird die Seite in der entsprechenden Sprache neu geladen. Dafür war es notwendig, einen “language-switcher” in Liquid zu schreiben.

// _includes/language-switcher.html
{% raw %}
{% for lang in site.languages %}
 {% assign url_parts = page.url | split: "/" %}
 {% assign lang_code = lang %}

 {% assign collection_name = url_parts[1] %}
 {% assign post_url = url_parts | last %}

 {% if lang == site.default_lang %}
 {% if collection_name == post_url %}
 {% assign lang_url = "/" | append: post_url %}
 {% else %}
 {% assign lang_url = "/" | append: collection_name | append: "/" | append: post_url %}
 {% endif %}
 {% else if url_parts.size > 2 %}
 {% assign lang_url = "/" | append: lang_code | append: "/" %}
 {% if collection_name == post_url %}
 {% assign lang_url = lang_url | append: post_url %} 
 {% else %}
 {% assign lang_url = lang_url | append: collection_name | append: lang_url | append: post_url %}
 {% endif %}
 {% endif %}
 <a href=" {{ lang_url }}">{{ site.data[lang].l10n.lang_name }}</a>
{% endfor %}
{% endraw %}

Hierfür wird die aktuelle url am Slash in Einzelteile zerlegt. Anschließend der letzte Teil der url als Artikelname post_url gesetzt und angenommen, dass der erste Teil der URL der collection entspricht, z.B. posts-hardware. Die anschließende Logik setzt die Sprachkürzel je nach Bedarf in die url ein, sodass je nach Verwendung einer collection oder ohne die entsprechende Zielurl korrekt erzeugt wird.

Veröffentlichung

Ich war echt stolz auf diesen Umbau. Ich finde, dass sich alles gut einfügt und ich mit der Zweisprachigkeit meinen Nutzerkreis gut erweitern kann. Der Nachteil für mich ist die zusätzliche Übersetzungsarbeit, die von nun an bei jedem Artikel auf mich zukommt.

Als ich diese Seite das erste mal auf die Github Page hochlud, merkte ich, dass das so überhaupt nicht funktioniert. Github Pages unterstützt Polyglot nämlich nicht, sodass plötzlich alle Artikel unabhängig von ihrer Sprache auf einmal auf meiner Website erscheinen.

Nun blieben mir nur zwei Möglichkeiten: Eigene Github Actions für das Deployment aufzusetzen - oder ein Umzug auf einen eigenen Server. Ich habe mich für Letzteres entschieden, da die Github-Server für diese Seite meines Wissens nach in UK stehen und und ich mit einem Server in Deutschland lieber auf der sicheren Seite wäre.

Der eigentliche Umbau ist aber deutlich zu groß, um ihn in diesem Post abzuhandeln - dafür gibt es ein eigenes Softwareprojekt.

Hardware Test

Schallbert — Sun, 23 Apr 2023

Ein neuer Antrieb

Kürzlich habe ich Zerspanobert ein Spindel-Upgrade gegönnt. Ich bin jetzt auf eine Drehstrom-Asynchronmaschine umgestiegen, welche mit einem 24V-Lüfter fremdgekühlt wird. Für den Betrieb im benötigten Drehzahlbereich musste ich in einen Frequenzumrichter investieren, der in meinem Falle wie beim vorigen Fräsmotor auch über ein analoges 0-10V Signal gesteuert wird. Aus Sicht der CNC ist die neue Spindel bis auf eine Ausnahme identisch mit der alten: Der Frequenzumrichter kann nun ein “Not-Aus” Signal erzeugen und an die Steuerung melden, z.B. wenn die Drehzahl ungeplant abfällt, zu lange ein Überlastzustand auftritt etc.

Wie man sich vorstellen kann ist das neue Subsystem rund um die Spindel deutlich komplizierter als das alte.

Warum extra Tests?

Mit höherer Systemkomplexität erhöht sich auch das Risiko für Fehlfunktionen. Es sind eine Menge mehr elektrischer, elektronischer und mechanischer Bauteile verbaut als bei meinem Fräsmotor, die selbst Defekte aufweisen oder bei falscher Verdrahtung selbst in Rauch aufgehen können. Da ich als Systemdesigner selbst nur ein Mensch bin der Fehler macht, wäre es nicht besonders schlau, das System irgendwie zusammenzustecken und dann direkt auszuprobieren.

Während ich die Verdrahtung erstellte, überlegte ich mir also, wie ich das System effizient testen könne, ohne etwas zu zerstören.

Teststrategie

Ich habe die unterschiedlichen Testbereiche von meiner Arbeit in der Softwareindustrie geborgt. Sie passen hier denke ich recht gut hinein:

Unit: Ein Test, der das Verhalten einer Komponente des Systems isoliert überprüft. Alle externen Einflüsse wurden entweder entfernt oder durch Komponenten ersetzt, auf die im Test selbst problemlos zugegriffen werden kann. Beispiel: Prüfe, ob der Lüfter bei Anlegen seiner Betriebsspannung wie erwartet im richtigen Drehsinn anläuft.
Integration: Diese Tests prüfen das Zusammenspiel verschiedener Komponenten, welche gemeinsam eine Funktion abbilden. Beispiel: Überprüfe, ob die Luftkühlung der Spindel auch nach Abschalten derselben für eine bestimmte Zeit nachläuft.
Subsystem: Verifiziert die korrekte Interaktion aller Komponenten eines Subsystems. Beispiel: Die Spindeldrehzahl kann über eine analoge Spannung am Eingang des Frequenzumrichters verändert werden.
System (End2End): Diese Tests werden aus Kundensicht ausgeführt und durchlaufen das komplette System. Beispiel: Wenn ich den Not-Aus an der CNC betätige, muss der Frequenzumrichter die Spindel umgehend sicher zum Stillstand bringen.

Teste früh

Aus meiner Erfahrung macht es Sinn, die Tests zum frühestmöglichen Zeitpunkt durchzuführen. Nachdem die Spindel geliefert worden war, konnte ich auf diese Weise sofort nachvollziehen, ob alle Lager leichtgängig sind, ob der Lüfter funktioniert und ob der elektrische Widerstand der Statorwicklungen im erwarteten Bereich liegt. Alle diese Tests waren durchführbar noch bevor ich mit dem Bau des Schaltschranks überhaupt begonnen hatte.

Your browser does not support the video tag.

Unit test: Lüfter

Die schnell und einfach durchführbaren Unit Tests können einen Haufen Zeit sparen, denn diese Fehlerquellen kann man später bei der Inbetriebnahme direkt ausschließen. Und findet man doch etwas so früh, kann man sich direkt um Ersatz kümmern und hält nicht den Einrichtbetrieb auf.

Teste “von unten nach oben”

Bei den vier Testebenen versuche ich, so viel wie möglich mit einfachen und schnellen Unit Tests abzudecken. Was hier noch nicht geht, wird jeweils auf der nächsthöheren Ebene abgearbeitet und so weiter. Am Ende möchte ich nur ein paar Wenige Tests aus Kundensicht durchführen, da diese meist einen größeren Aufwand für Vor- und Nachbereitung benötigen und außerdem zumeist nicht genau in der Lage sind, den Fehler zu lokalisieren.

Dies deckt sich mit dem Konzept der Testpyramide, welche in der Softwareentwicklung des Öfteren herangezogen wird.

Testplan

Für meine privaten Hobbyprojekte schreibe ich üblicherweise keinen Testplan. Meine Systeme sind meist deutlich einfacher als dieses. Außerdem benötigen nur die wenigsten potentiell gefährliche Niederspannung wie in diesem Fall.

Um das System besser zu visualisieren habe ich mal einen groben Schaltplan mit allen Komponenten sowie relevanten Ein- und Ausgängen gezeichnet.

Von diesem Bild habe ich einen Testplan abgeleitet. Hierbei habe ich versucht, die Interaktionen jeder Komponente mit jeder anderen abzudecken und wenn möglich versucht, dem Komponententest den Vorrang zu geben.

Your browser does not support the video tag.

Unit test: Stromversorgung +24V OK

Hier überprüfe ich die Versorgungsspannung für den 24V-Lüfter

Your browser does not support the video tag.

Unit test: Abfallverzögerung

Mit diesem Test stelle ich sicher, dass die Konfiguration der Anzugs- und Abfallverzögerung wie gewünscht funktioniert. Für den Test habe ich kürzere Zeiten gewählt als später im produktiven Betrieb.

Your browser does not support the video tag.

Integrationstest: FU Inbetriebnahme

Hier prüfe ich, ob der Frequenzumrichter die Spindel mit der korrekten Drehrichtung und mit unterschiedlichen Drehzahlen betreiben kann.

Ausführung der Tests

Es gibt natürlich noch viele weitere hardwarebasierte Tests die ich oben nicht erwähnt habe. Dinge wie “ist die Spindel korrekt mit der Z-Achse ausgerichtet?” “Habe ich alle Schrauben mit dem vorgeschriebenen Drehmoment angezogen?” “Sind alle Stecker angeschlossen und verriegelt?”

Bevor ich nach dem Umbau also das erste mal wieder Späne mache, habe ich den Testplan komplett abgearbeitet und tatsächlich ein Problem auf Systemebene entdeckt: Ich habe den Analogausgang zur Vorgabe der Spindeldrehzahl falsch verdrahtet, sodass andere Pins das Signal führten als geplant. Dies führte dazu, dass sich die Spindel trotz Freigabe nicht starten ließ, obwohl die CNC “Spindel läuft” ausgab.

Dank der vorausgehenden Tests am Frequenzumrichter (“Reacts to speed command”) habe ich nur Minuten benötigt um den Fehler zu finden und zu beheben - denn ich wusste, am FU liegt’s nicht.

Dokumente

Falls Sie planen, eine Frequenzumrichtergesteuerte Motorspindel an Ihrer Maschine einzusetzen, können Sie sich meinen Testplan kostenlos herunterladen. In case you plan on adding a VFD-controlled spindle motor to your machine, please find my full test plan below.

VFD-controlled spindle motor test plan

Aber bitte betrachten Sie diesen Plan mehr als Unterstützung denn als vollumfängliche Prüfung und beachten Sie vor allem die üblichen Warnhinweise:

⚠️ Warnung vor gefährlicher Spannung ⚠️

Dieses System sollte nur von Profis konstruiert, zusammengebaut, angepasst, in Betrieb genommen und schließlich fachgerecht geprüft werden. In diesem Falle meine ich mit “Profi” jemanden, der eine abgeschlossene Berufsausbildung zum Elektriker oder Elektroniker, optimalerweise in der Fachrichtung Anlagenbau/Betriebstechnik sowie Erfahrung im Umgang mit Industrieelektronik vorzuweisen hat. Vermeiden Sie insbesondere, unter Spannung stehende Teile zu berühren oder an einer der Komponenten zu arbeiten, bevor der Frequenzumrichter nach dem Abschalten genügend Zeit hatte, seine Pufferkondensatoren zu entladen.

Github Actions: Fehler beheben

Schallbert — Tue, 14 Feb 2023

Motivation

Warum ich einen Beitrag zu Github Actions schreibe, obwohl es im Internet zahllose Tutorials und Blogeinträge zum Thema gibt? Weil ich für mein letztes Software-Projekt QR-codengrave eine Build Pipeline aufsetzen wollte und sich dies schwieriger gestaltete als angenommen. Sollte ich das an irgend einem Punkt in der Zukunft wiederholen müssen und erinnere mich nicht, wie ich damals in der IDE gebaut, getestet und veröffentlicht habe, kann die Pipeline weiterhelfen.

Ebenso, wenn sich meine IDE ändert oder meine Virtuelle Umgebung defekt ist, die launch.json fehlt oder irgend etwas inkompatibel mit dem von mir verwendeten Compiler/Interpreter wird. Dennoch will ich in der Lage sein, Releases zu veröffentlichen, Bugfixes zu erstellen und Tests zu fahren.

Obwohl das nicht das übliche Argument ist, eine CI/CD Pipeline aufzubauen - normalerweise wird da zuerst die einfachere Zusammenarbeit mehrerer Menschen an einem gemeinsamen Programm(teil) genannt - ist der Anreiz für mich stark genug, mir mal Githubs Automation dafür, bekannt unter dem Namen Github Actions, auszuprobieren.

Meine Software ist zu unbedeutend um “Nightlies” zu bauen oder agil entwickelt zu werden, und daher werde ich die Pipeline auf “build”, “lint/static code checks”, “testing” und “deployment” beschränken und dies auch nur dann automatisch triggern, wenn es Änderungen auf dem Produktionsbranch gibt.

Alles klar, aber warum ein extra Blogeintrag?

Weil es mich so viel Zeit gekostet hat, alles richtig aufzusetzen. Ich habe dafür stundenlang Fehler suchen, oft fluchen und wütend Spaziergänge machen müssen, bevor ich meine in der IDE bereits getestete und lauffähige Software auch mit Github vereinen zu können.

Wäre ich klüger gewesen, hätte ich gleich zu Anfang nach Tools dafür recherchiert wie dieses hier, sodass Github Actions auch lokal ausgeführt werden kann. Dies hätte mir die ständigen Pushes und Wartezeiten auf den nächsten, immer noch fehlerhaften Build ersparen können.

Das Script

Github Actions benutzt YAML um Befehle der Nutzer zu interpretieren. Die Verwendung ist sehr gut dokumentiert und stellt einige plug-and-play Beispiele bereit, die in vielen Szenarien und für die meisten Programmiersprachen direkt passen.

Die sogenannte “Workflowdatei” sieht so aus:

# This workflow will install Python dependencies, run tests and lint with a single version of Python
# For more information see: https://docs.github.com/en/actions/automating-builds-and-tests/building-and-testing-python

name: python_integrate

on:
 push:
 branches: [ "master" ]
 pull_request:
 branches: [ "master" ]

permissions:
 contents: read

jobs:
 build:

 runs-on: ubuntu-latest

 steps:
 - uses: actions/checkout@v3
 - name: Set up Python 3.10
 uses: actions/setup-python@v3
 with:
 python-version: "3.10"
 - name: Install dependencies
 run: |
 python -m pip install --upgrade pip
 pip install flake8 pytest
 pip install qrcodegen # Dependency install of qrcodegen
 if [ -f requirements.txt ]; then pip install -r requirements.txt; fi
 - name: Lint with flake8
 run: |
 # stop the build if there are Python syntax errors or undefined names
 flake8 . --count --select=E9,F63,F7,F82 --show-source --statistics
 # exit-zero treats all errors as warnings. The GitHub editor is 127 chars wide
 flake8 . --count --exit-zero --max-complexity=10 --max-line-length=127 --statistics
 - name: Test with pytest
 uses: GabrielBB/xvfb-action@v1  # Diverts tkinter GUI to a virtual frame buffer (VFB)
 with:
 run: |
 pytest

Dieses sieht nicht einmal groß anders aus als die Vorlage mit der ich gestartet bin. Die einzigen Anpassungen waren der nun vorhandene pytest Aufruf sowie das Hinzufügen eines virtuellen Bildpuffers um Darstellungsprobleme meiner GUI zu lösen. Meine Tests schlugen nämlich fehl sobald die GUI gestartet wurde, da auf den Github Servern gar kein Display zur Verfügung steht.

Github Action runner Fehlermeldungen

Die folgende Liste enthält die Fehler (und zugehörige Lösungen) mit denen ich konfrontiert wurde, bevor ich eine stabile CI aufsetzen konnte - erst nach fast 50 Durchläufen.

Ordner nicht vorhanden?

Output:

/opt/hostedtoolcache/Python/3.10.9/x64/lib/python3.10/importlib/__init__.py:126: in import_module
 return _bootstrap._gcd_import(name[level:], package, level)
test/test_machinify_vector.py:4: in <module>
 from bin.platform.machinify_vector import MachinifyVector, Tool, EngraveParams
E ModuleNotFoundError: No module named 'bin'

Hintergrund: Ich habe meine Quelldateien unter /bin abgelegt und meiner lokalen Instanz von Pyinstaller (das Werkzeug, was ich auswählte, um aus den Skripten eine ausführbare Datei zu erzeugen) zur Verfügung gestellt. Beim Upload konnte Github Actions die Pfade nicht auflösen und zeigte diesen Fehler an.

Lösung: Eine leere Datei mit Namen __init__.py im /bin Ordner ablegen. Dies zeigt alle im Ordner befindlichen Dateien als Package an, die so für Github Actions verfügbar werden. Die IDE hatte dieses Problem nicht, weil sie alle im Projektordner befindlichen Dateien automatisch indiziert.

YAML Syntaxfehler

Diese Fehler entstanden, weil ich versucht hatte, mehrere Workflows in eine Datei zu schreiben. Github Actions scheint nur einen Workflow pro Datei zu akzeptieren.

Fehler: Pfad-nicht-gefunden

Ich hatte lange Probleme mit solchen Fehlern bedingt durch meine Ordnerstruktur:

- assets  # images, persistence file, etc.
- src  # source files
- test  # pytest files for unit and integration testing
- dist  # build artifacts
- build  # build process files

Ich fand die echt schön aufgeräumt. Aber meine lokale IDE, PyInstaller und Github Actions bzw. dessen worker für Pyinstaller waren sich nicht einig, wie sow etwas aussehen soll. Immer würde sich eine der beteiligten Parteien beschweren, dass ein Pfad nicht existiere oder die Datei soundso nicht gelesen werden könne. Daher habe ich am Ende die Verwendung relativer Pfade verworfen und stattdessen pythons importlib_resources verwendet.

Aber auch hier gab es Probleme mit Pyinstaller auf Github.

Letztendlich konnte ich das Problem erst lösen, als ich den Ordner für assets in src integrierte. Auf diese weise kann der ./ Operator nicht falsch verstanden werden. Obwohl ich dieses Konstrukt nicht so schön finde, war ich immer weniger bereit, noch mehr Zeit dort hinein zu buttern. (Wenn Sie wissen, wie sich das Pfadhandling sowohl lokal als auch remote mit Eleganz lösen lässt, freue ich mich sehr über Ihren Beitrag auf meiner Dissussionsseite).

Tkinter headless

Spät im Entwicklungsprozess habe ich meinen Unit Tests ein paar Integrationstests zur Seite gestellt. So wollte ich sicherstellen, dass Popups die erforderlichen Callbacks an Main machen würden und umgekehrt Daten ausgetauscht werden können, sodass z.B. eine Werkzeugliste an das Konfigfenster übergeben werden kann.

Diese Tests liefen lokal zwar, aber mit einem Nachteil: Wenn ich einen Fehler oder eine Warnung erzeugte, ließ sich das messageBox-Popup nicht automatisiert schließen. Es wollte unbedingt vom Nutzer selbst per Mausklick geschlossen werden. Dies ließ sich auch nicht durch einen Overlay oder Invoke der Click-Aktion umgehen.

Was also in der IDE nervig war, würde auf dem Server in der Automation zu Testabbrüchen führen. Also habe ich die bittere Pille geschluckt und eine Wrapperklasse um tkinters messageBox geschrieben, sodass ich dort ein Mock injizieren konnte was dann wiederum nicht das echte Popup triggern würde.

Ausschnitt:

class MsgBox:
 """Re-implementation due to testing purposes: With this trick, we are able to mock these windows
 so we do not have to wait for users to manually close the dialog, unblocking the application again."""
 def showinfo(self, title, message):
 showinfo(title=title, message=message)

 def error(self, title, message):
 showerror(title=title, message=message)

Als das funktionierte, habe ich die Änderungen voller Hoffnung nach Github gepusht. Und erhielt folgenden, wunderschönen Fehler:

_tkinter.TclError: no display name and no $DISPLAY environment variable

Das war zum Glück leicht zu verstehen - Tkinter wusste nicht, wo es die Fenster hinzeichnen sollte. Erscheint logisch, da der Server headless betrieben wird.

Also durchsuchte ich Foren und wurde mit nur einer Zeile Code belohnt, die dieses Problem sofort behob:

uses: GabrielBB/xvfb-action@v1 # Diverts tkinter GUI to a virtual frame buffer (VFB)

Seitdem führt Github Actions bei Pull request auf main alle tests aus und endlich ergießt sich ein langersehnter Regen grüner Häkchen kühlend auf meine heißgelaufenen Hirnwindungen. Was für ein schönes Gefühl.

Jekyll `-incremental` Option

Schallbert — Thu, 03 Jun 2021

die Kategorie “Neueste Beiträge”

Ich habe den Grund herausgefunden, warum mein letzter Artikel auf der Landing Page auf meinem lokalen Rechner nicht angezeigt wurde, aber auf dem Server problemlos funktionierte. Es liegt daran, dass ich lokal den Befehl $ bundle exec jekyll serve --incremental mit der aktiven --incremental build Option verwende, um die Rebuilds für schnellere Testläufe zu beschleunigen. Aber das Problem liegt hier:

Bei einer inkrementellen Ausgabe scheint Jekyll den Ordner _posts nicht nach neuen Einträgen zu durchsuchen, da die Seite, auf der sie erscheinen, nicht geändert sondern neu angelegt wurde. Mein Fazit ist, dass ich die Option --incremental in Zukunft mit Vorsicht und nur für Änderungen bereits bestehender Artikel verwenden werde.

Die Bilder

Ich habe an meinen Bildern unter assets/images gearbeitet. Sie benötigen recht viel Speicherplatz, so dass die Ladezeiten der Seite zu lang werden. Ich benutze paint.net, um sie auf eine Größe zu schrumpfen, die ich für vertretbar halte, und speichere sie als .jpg mit maximaler Kompression und einigen Kompromissen bei der Bildqualität. Auf diese Weise benötigen die meisten meiner Bilder weniger als 10% der ursprünglichen Größe in kB.

GoogleTest Demo

Schallbert — Mon, 01 Jan 0001

Projekt-Steckbrief

Schwierigkeitsgrad: Mittel 3/5
Kosten: 0€
Zeitaufwand: ~2h

Motivation

Es ist schön, bei der Entwicklung komplexerer Projekte ein leistungsfähiges Unit-Test-Framework zur Hand zu haben, das viel Zeit bei der Fehlersuche spart (vor allem das On-Target-Debugging in der Embedded-Welt kann sehr zeitaufwendig sein), die Codequalität verbessert und möglicherweise den Einblick in APIs und Architektur für andere verbessert.

Die Welt der “embedded controller”

Traditionell waren Mikrocontroller auf der Speicherseite begrenzt. In der Vergangenheit hatten sie weder viel RAM noch PROGMEM, also war mein meist in schlankem C geschrieben und die Konfiguration fand in Listen von #define statt, die nicht viel Rechenzeit kosten, weil der Präprozessor die Arbeit machen würde und nicht der µC zur Laufzeit. Meine Unit-Tests waren immer an die Hardware gebunden, auf der sie liefen - nehmen Sie Unity als bekanntes Beispiel - aber jetzt wollte ich etwas Neues ausprobieren: Code objektorientiert schreiben und die Geschäftslogik unabhängig von der Hardware testen lassen. Ich wählte das GoogleTest-Framework und wollte eine nahtlose Integration in meinen Workflow mit VScode und dessen Erweiterung PlatformIO erreichen.

Hierfür blieb bis vor kurzem nur der Weg, GoogleTest per GNU Compiler Collection parallel zu betreiben und durch PlatformIO ansteuern zu lassen. Neuerdings allerdings lässt sich GoogleTest als PlatformIO Library direkt nutzen. Daher gehe ich hier auf beide Wege ein.

GoogleTest direkt in PlatformIO verwenden

Hier gestaltet sich die Installation besonders einfach:

Mein Github-Repository PlatformIO-gTestgMock klonen.
Im Repository-Ordner ein Konsolenfenster öffnen und per git checkout googletest-native auf den entsprechenden Branch wechseln.
Den Anweisungen in der README-Datei des Repository folgen und das Setup ausprobieren.

So sieht es aus, wenn die Tests erfolgreich durchgeführt wurden:

GoogleTest per GCC einsetzen

Die benötigte Software kann man selbst (auch auf einem Windows¹ Rechner) installieren, um mit GoogleTest starten zu können.

MinGW herunterladen und installieren

Siehe diesen Thread im Forum von PlatformIO, wenn es Fragen zu den folgenden Schritten gibt.

Unix-Benutzer: bis hier die Schritte überspringen, denn wahrscheinlich werden nur die libpthreadgc-Bibliotheken zusätzlich benötigt. Prüfen Sie das Vorhandensein aller Bibliotheken (aber lassen Sie das Präfix mingw32- weg) und installieren ggf. fehlende nach. Stellen Sie sicher, dass die PATH-Variable korrekt gesetzt ist.
Windows-Benutzer:

Laden Sie MinGW herunter, z.B. von Sourceforge
Installieren Sie durch Ausführen von mingw-get-setup.exe. Wenn Sie grafische Benutzeroberflächen mögen, lassen Sie das entsprechende Kästchen angekreuzt. Ich empfehle nicht, das Installationsverzeichnis zu ändern. Wenn Sie das doch tun, müssen Sie sich sich den neuen Pfad merken.

MinGW konfigurieren

Damit GoogleTest läuft, müssen zusätzliche Pakete installiert werden:
- mingw32-gcc-g++
- mingw32-libmingwex
- mingw32-libmingwex-dll
- mingw32-libmingwex-dev
- mingw32-libpthreadgc-dll
- mingw32-libpthreadgc-dev
Um diese zu installieren,
- Wenn Sie die GUI verwenden: Suchen Sie die Bibliotheken unter “MinGW Standard Libraries” und fügen Sie sie nacheinander hinzu/aktivieren/installieren Sie sie.
- Benutzer des Kommandozeilen-Interpreters: Geben Sie mingw-get install ein und fügen Sie dann den Paketnamen hinzu. Wenn Sie eine Fehlermeldung erhalten, die besagt, dass einige der Pakete bereits existieren, umso besser.
Jetzt müssen Sie den Ordner “bin” von MinGW zu Ihren Systempfadvariablen hinzufügen, damit PlatformIO sie später finden kann. Wenn Sie ihn nicht von Hand modifiziert haben, sollte er C:\MinGW\bin lauten.
- GUI-Fans: folgen Sie dieser Anleitung
- CLI: Geben Sie set PATH=%PATH%;C:\MinGW\bin ein und überprüfen Sie, ob es mit echo %PATH:;=&echo.% funktioniert.

Glückwunsch! Sie haben MinGW installiert, die Umgebungsvariablen so gesetzt, dass es von Drittanwendungen leichter gefunden wird, und es für die Zusammenarbeit mit GoogleTest konfiguriert.

PlatformIO konfigurieren

Nachdem die Variable PATH gesetzt ist, muss VScode neu gestartet werden.
Damit PlatformIO korrekt mit dem gerade installierten Compiler verbunden wird, muss die native Umgebung verwendet werden. Dort befindet sich der Compiler mit allen benötigten Umgebungsvariablen. Öffnen Sie ein PlatformIO-Terminal in einem Ihrer Projekte und geben Sie pio platform install native ein.
Zwei Möglichkeiten:

A) Befolgen dieser Anleitung unter Verwendung meines Beispielprojektes wie unten beschrieben. Dann kann der nächste Abschnitt getrost übersprungen werden, da dieses Projekt vorkonfiguriert ist. Sie können nach Belieben damit herumspielen denn Sie verfügen von Anfang an über grundlegende Hardware-Abstraktionsschnittstellen.
B) Nehmen Sie Ihr eigenes Projekt und ändern Sie dessen Platformio.ini so, dass GoogleTest ausgeführt werden kann.

Dies sollten Sie zu Ihrer Platformio.ini hinzufügen:

[env:desktop]
platform = native
build_flags = 
	-std=gnu++11 # use installed GNU C++11 compiler.
	-pthread # found in gtest documentation
lib_deps = 
	googletest # Will automatically load latest googletest lib
lib_ignore = 
 src # most main.cpp's directly access the hardware. 
 # Can be removed if your project is different.
 #
 # PLUS: Any files that contain bare-metal hardware commands 
 # (e.g. digitalWrite), g++ won't have the headers or specialized compiler knowledge!
lib_compat_mode = off # Must-have for external stuff like gtest!

Erklärung: Für die Umgebung Desktop (= Computer ohne Microcontroller) wird der native Compiler verwendet, d.h. GCC/G++, der oben in der Anleitung installiert und für den die PATH-Variable festgelegt wurde. GoogleTest verwendet den C++11-Standard und Threading, der zu den Build-Flags hinzugefügt werden muss. Der Build von der googletest Bibliothek ab. Es werden alle Dateien/Ordner ignoriert, die Quell- oder Headerdateien mit hardwarebezogenen Befehlen oder Headern enthalten. Der Bibliothekskompatibilitätsmodus muss ausgeschaltet sein, damit der Library Dependency Finder googletest einbeziehen kann.

(Optional) Falls Sie lieber GUI-Schaltflächen verwenden als eine Zeile in die Konsole zu tippen um die Tests zu starten, erstellen Sie eine benutzerdefinierte Konfiguration.

Tests ausführen

Für einen schnelleren Einstieg kann mein Beispiel-Repository geklont werden (den main branch verwenden). Es enthält alle notwendigen Elemente, um zu prüfen, ob gTest und gMock korrekt funktionieren. So kann man direkt nachvollziehen, ob die Installation erfolgreich war.

Entpacken Sie die Zip-Datei bzw. verwenden Sie SSH, um das Repository zu klonen.
Öffnen Sie die Startseite der PlatformIO-Erweiterung, klicken Sie auf “Open Project”, und wählen Sie den Ordner aus.
Um die Unittests auszuführen, öffnen Sie ein PlatformIO-Terminal und geben Sie pio test -vvv -e desktop -f test_desktop ein. (-vvv = wortreich -e = Umgebung, -f = Filter). Die Parameter sind erforderlich, weil die Tests nur auf der “Desktop”-Umgebung lauffähig sind, nicht aber auf dem Microcontroller.
Nach einiger Zeit sollte die unten dargestellte Meldung angezeigt werden.

Super! Unit-Tests innerhalb von PlatformIO wurden gebaut und ausgeführt!

Tipps und Tricks

Zu beachten ist, dass der Ordner PlatformIO_gTestgMock/.pio/build/desktop nun eine ausführbare Datei namens program.exe enthält. Wird sie über die Kommandozeile ausgeführt, sollte das selbe Ergebnis wie in der obigen Abbildung herauskommen. Dies kann nützlich sein, wenn Tests nicht nur fehlschlagen, sondern das ganze Programm bei der Ausführung abstürzt. Zum Debuggen der Tests ist das auch hilfreich, da die CLI von PlatformIO dazu neigt, sich aufzuhängen. Man hat hier auch leichten Zugang zum Stracktrace - das sprengt den Rahmen dieser Übung aber bei Weitem.

Ab diesem Punkt

können Sie weiterlesen, um den Inhalt des Repositorys und die Funktionsweise von GoogleTest besser zu verstehen
Sie könnten das Schreiben von Tests üben, indem Sie weitere Fälle hinzufügen, z. B. um zu überprüfen, ob der Zustand “LOW” korrekt durchlaufen wird.
Sie könnten auch die Interfaces dieser Grundbausteine verbessern, z. B. durch Hinzufügen der Funktion analogRead() zur Hardware-Abstraktionsschicht
Sie könnten Ihr eigenes Projekt darauf aufbauen, die Hardware-Abhängigkeiten sauber ausschalten und es so einfach auf verschiedene Hardware-Geräte und Hersteller portieren
Oder Sie beschäftigen sich weiter mit diesen anderen genialen Dingen, die Sie in die Tat umsetzen wollten, bevor Sie von diesem Tutorial abgelenkt wurden.

Repository-Inhalte erklärt

Die folgenden Abschnitte behandeln die meisten Dateien im Repository und erklären, was sie im Detail tun. Die implementierte Geschäftslogik ist minimal und sollte als Beispielcode betrachtet werden. Ein reales Projekt, das alle auf dieser Seite dargestellten Muster verwendet, ist auf meiner Tonuino-Seite zu finden.

Schnittstelle der Hardware-Abstraktionsschicht

Schauen wir uns das Interface und seine Struktur genauer an.

// hal_if.h
namespace hardwareAbstraction {

// Hardware Abstraction Layer Interface class
class Hal_IF
{
public:
 virtual ~Hal_IF() = default;

 virtual bool digitalRead(uint8_t pinId) const = 0;
 virtual void digitalWrite(uint8_t pinId, bool value) const = 0;
};

} // hardwareAbstraction

Die Klasse Hal_IF hat zwei Methoden, die beide virtuell sind. Das bedeutet, dass eine Client-Klasse, die diese Schnittstelle verwendet, die Methode aufrufen kann und somit “automatisch” an die konkrete Implementierung der Methode weitergeleitet wird. Das = 0; macht diese Methoden rein virtuell, so dass das Überschreiben dieser Methoden durch eine abgeleitete Klasse nicht optional sondern vorgeschrieben ist. Das ist genau das, was wir hier wollen, denn wenn diese Methode nicht überschrieben würde, hätte sie kein Verhalten. Zu beachten ist, dass der Destruktor einer Schnittstellenklasse fast immer virtuell sein sollte.

LoopInOut

Die zu testende Logik. Sie greift nicht direkt auf die Ein-/Ausgabe-Hardware des µC zu, sondern auf die Variable m_hal, die eine Implementierung der Schnittstelle Hal_IF ist. Sie wird bei der Objekterzeugung per Referenz (gekennzeichnet durch das & bei der Typdeklaration) an die Klasse übergeben².

// loopInToOut.h

class LoopInToOut
{
public:
 LoopInToOut(hardwareAbstraction::Hal_IF& hal): m_hal(hal){};
 ~LoopInToOut() = default;

 bool loopThrough(uint8_t inPin, uint8_t outPin);

private:
 hardwareAbstraction::Hal_IF& m_hal;
};

Dies ermöglicht die eigentliche Magie von gMock: Da der Client-Code mit einer Schnittstelle arbeitet, kann ich die “echte” Implementierung (des Hardware-Zugriffs) zur µC-Laufzeit übergeben, aber für den Test kann ich eine “Modell”-Implementierung übergeben, über die ich zum Zeitpunkt der Ausführung des Tests die Kontrolle habe.

// loopInToOut.cpp

bool LoopInToOut::loopThrough(uint8_t inPin, uint8_t outPin)
{
 bool input = m_hal.digitalRead(inPin);

 m_hal.digitalWrite(outPin, input);
 return input;
}

loopThrough() ist wiederum sehr einfach. Sie liest den Zustand des Eingangspins und ordnet ihn dem Ausgangspin zu. Sie gibt den Zustand des Eingangspins an den Aufrufer zurück.

Modellierte Hardwareabstraktion (mock hal)

GoogleTest verwendet Makros, um Verhalten zu definieren. Die Mock-Klasse leitet sich ebenfalls von der Schnittstelle ab und stellt lediglich die Deklarationen der Schnittstellenmethoden bereit, die sie überschreibt. Es ist noch kein Verhalten festgelegt.

// hal_mock.h

class Hal_mock : public hardwareAbstraction::Hal_IF
{
public:
 MOCK_METHOD(bool, digitalRead, (uint8_t pinId), (const, override));
 MOCK_METHOD(void, digitalWrite, (uint8_t pinId, bool value), (const, override));
};

Die Testvorrichtung (test fixture)

Die Testvorrichtung enthält gemeinsame Daten und Verhaltensweisen für alle Testfälle innerhalb einer Testsuite. Name der Testsuite = Klassenname. Genau dieser Name muss in den Tests, die zu dieser Suite gehören sollen, wiederverwendet werden.

// unittest_loopInToOut.cpp
class loopInToOut_Test : public ::testing::Test
{
protected:
 virtual void SetUp()
 {
 m_loopInToOut = new LoopInToOut(hal_mock);
 }

 virtual void TearDown()
 {
 delete m_loopInToOut;
 }

 NiceMock<Hal_mock> hal_mock{};
 LoopInToOut* m_loopInToOut{nullptr};
};

Jeder Test verfügt also über einige vorbereitete Daten, die er verwenden kann: Die zu testende Klasse wird als Zeiger mit einer modellierten (Mock) Implementierung ihrer Abhängigkeit eingerichtet.

Der eigentliche Test

Der Test wird durch das Makro TEST_F definiert, was soviel bedeutet wie “Test mit Fixture”, das eine Testsuite und Testnamen erwartet. Das Makro ON_CALL ist ein Befehl an gMock, der der modellierten Klasse vorgibt, wie sie sich zu verhalten hat, wenn digitalRead(_) mit einer beliebigen Eingabe (Unterstrich = beliebig) aufgerufen wird: die Methode soll standardmäßig true zurückgeben.

// unittest_loopInToOut.cpp

TEST_F(loopInToOut_Test, loop_inputHigh_writesCorrectOutputHigh)
{
 ON_CALL(hal_mock, digitalRead(_)).WillByDefault(Return(true));

 EXPECT_CALL(hal_mock, digitalWrite(2, true));

 m_loopInToOut->loopThrough(1, 2);
}

Dann wird eine “Erwartung” an die nachgebildete Klasse formuliert, die besagt, dass digitalWrite mit Eingabewerten von (2, true) aufgerufen wird, die ebenfalls auf Korrektheit geprüft werden.

Die letzte Anweisung ruft die echte Implementierung auf, so dass die Erwartungen überprüft werden können.

Implementierung des Hardwareverhaltens

Da main.cpp auf die Hardware zugreift, muss es dafür eine Art Schnittstellenimplementierung geben.

// hal.h
class Hal : public Hal_IF
{
public:
 Hal() = default;
 ~Hal() = default;

 bool digitalRead(uint8_t pinId) const override;
 void digitalWrite(uint8_t pinId, bool value) const override;
};

Hier leitet Hal sich von Hal_IF ab und überschreibt alle seine Methoden.

// hal.cpp
#include "Arduino.h"

#include "hal.h"

namespace hardwareAbstraction{

bool Hal::digitalRead(uint8_t pinId) const
{
 return digitalRead(pinId);
}

void Hal::digitalWrite(uint8_t pinId, bool value) const
{
 digitalWrite(pinId, value);
}

Man erkennt, dass nur diese Quelldatei tatsächlich die Arduino.h für den Zugriff auf die Hardware einbindet. Die Abhängigkeit von den Hardware-Funktionen ist also sehr begrenzt und in Schnittstellen-Implementierungen gekapselt, die durch die Programmstruktur ausgewählt werden können. Während die main.cpp für das Zielgerät also ein Objekt der obigen Implementierung erzeugt, wird der Test stattdessen ein Mock übergeben.

Gtest Schlüsselkonzepte

Googles offizielle Webseite über Googletest kann sehr helfen, nicht nur für den Einstieg³. Das gmock Cookbook ist ein hervorragender Leitfaden, den ich im Laufe der Monate benutzt habe, als meine Tests immer komplexer und schwieriger zu schreiben wurden, und das gmock Cheat Sheet hilft, wenn man den Überblick verloren hat, wie ein Test für dieses oder jenes spezielle Problem zu schreiben ist.

Dependency Injection

Dependency Injection ist die grundlegende Mechanik, verstanden werden muss, damit man gMock erfolgreich anwenden kann. Ich versuche es mal mit einem Bild zu verdeutlichen.

Kurzgesagt ist die Schnittstelle lediglich ein Platzhalter für die Implementierung der Abhängigkeit der Client-Klassen.

Zur Laufzeit, z.B. wenn der Host das Client-Objekt erzeugt, wird er die Implementierung der Abhängigkeit an den Client übergeben (d.h. injizieren), der dann jede seiner Methoden aufrufen kann, da ihre Signaturen zur Kompilierzeit aufgrund der vom Client verwendeten Schnittstelle bekannt sind.

Das Mock ist nun lediglich eine Implementierung der Schnittstelle, die für die Tests spezialisiert ist.
Die eigentliche Implementierung wird in allen anderen Kontexten verwendet, sie zeigt das “echte” Verhalten dieser Klasse.

Hardware-Abstraktionsschicht

Dies ist vielleicht einer der kniffligen Punkte bei der Arbeit mit eingebetteter Software. Irgendwann geht es um die Interaktion mit der Außenwelt, sei es mit GPIO-Pins (General Purpose Input Output), den Zugriff auf eines der unzähligen Hardware-Bussysteme wie I2C, UART, SPI, CAN zur Steuerung externer Hardware oder einfach die Nutzung von Systeminterna wie dem EEPROM - da fangen die Probleme an.

Gtest läuft auf dem GCC/G++ Compiler, der einfach nichts von dem weiß, was der spezialisierte Compiler des jeweiligen Chips weiß. Er würde nicht einmal die Header-Dateien verstehen. Nun gibt es zwei Möglichkeiten, dieses Problem zu umgehen:

“Fake Header” für jede µC-spezifische Implementierung schreiben, die von GCC/G++ verwendet werden können
Eine Schnittstelle für jede µC-spezifische Implementierung unter Verwendung einer (Hardware-)Abstraktionsschicht programmieren, so dass Ihre Produktionsumgebung die Chip-Hardware wie gewohnt verwendet, die Testumgebung aber stattdessen Mocks benutzt.

Der zweite Ansatz hat eine Reihe von Vorteilen:

Er ist sauber. Er zwingt einen dazu, keine Abstraktionsschichten zu zusammenzufassen die getrennt gehören.
Er ist einfach. Man kann die Geschäftslogik testen, ohne den µC zu programmieren! Es müssen nur die Eingänge gemockt und die Ausgänge abgefangen werden.
Er ist portabel. Wenn man die Implementierung Abstraktionsschicht austauscht, kann man sie auf einer anderen Controller-Familie oder sogar auf Chips eines anderen Herstellers auszuführen.

Nachteile

Hmm, wo Licht ist, muss es doch irgendwo auch Schatten geben. Meiner Meinung nach sind die Nachteile, wenn man alles ohne angeschlossene Hardware testen will:

Speicher. Sowohl ROM als auch RAM werden schneller voll, wenn eine große Anzahl von Klassen und vtables existieren.
Besitz. Die Injektion von Abhängigkeiten trennt den Besitz von der Nutzung eines Objekts, und man muss sich entscheiden, wie beides organisiert werden soll.
Bibliotheken von Drittanbietern können nicht einfach verwendet werden sondern benötigen Anpassung. Ein Interface-Header, eine Adapter-Implementierung und ein Mock für jede Bibliothek, die “chip-internals” verwendet, sind zu erstellen.
Komplexität. Da Objekte über eine Schnittstelle injiziert werden, muss jetzt Call-by-Reference oder Übergabe per Zeiger durchgeführt werden 😨. Ersteres ist zusätzlich eingeschränkt, da es nur für Konstruktorinjektion funktioniert, nicht für andere Arten (Methodeninjektion, Setterinjektion usw.).

Einige weitere Tipps

Alles “hinter” der Abstraktionsschicht sollte so einfach wie möglich gehalten werden: Diese Dinge können nur auf dem Zielgerät getestet und ausgeführt werden. Beispiel: Jede Methode führt nur einen Befehl aus (wie in meinem Beispielcode).
Verwendung einer Loader-Klasse oder eines Dependency Injection Container (Nicolas Croad) erleichtert die Arbeit, denn er enthält alle zu injizierenden Objekte und kann sie auf Anfrage übergeben.
Die oben genannten Nachteile sollten im Blick behalten werden. Bei kleineren Projekten lohnt sich dieser Aufwand wahrscheinlich nicht.
Manchmal macht es sogar Sinn, mehrere Ebenen Schnittstellen zu haben. Dieses Muster kann nicht nur für die direkte Interaktion mit der Hardware zu verwendet werden, sondern auch zwischen Softwaremodulen, die dann in einer höheren Granularität getestet werden können. Dies kann sogar schneller sein als ein großen Haufen Klassen zu haben, die nur über Mocks in der Hardware-Abstraktionsschicht kontrolliert werden können.

Schwieriges Thema!

Sie haben sich jetzt eine Pause verdient. Das waren viele Informationen, die Sie verarbeiten mussten. Nehmen Sie sich Zeit. Kontaktieren Sie mich gern auf der discussions Seite zu diesem Thema, wenn Sie das Gefühl haben, dass etwas fehlt, nicht korrekt dargestellt ist, verbessert werden sollte oder einfach genau das ist, was Sie jetzt brauchten.

Die Installation unter Linux ist einfacher, da gcc und g++ bereits vorinstalliert sind. Selbst wenn sie noch nicht die richtigen Pakete zur Unterstützung von GoogleTest enthalten, sind ihr Fehlermeldungen viel aussagekräftiger als die unter Windows, z.B. wenn Bibliotheken fehlen. 🙃 ↩︎
Dies wird auch Constructor Injection genannt, eine Unterart der Dependency Injection, die ein Mittel zur Erreichung der Inversion Of Control ist. Ich habe einige Links zu weiteren Informationen vorbereitet. Dies ist ein umfangreiches Thema, über das ganze Bücher geschrieben worden sind. ↩︎
Übrigens: die googletest-Seite ist auch statisch wie meine und verwendet ebenfalls Jekyll 👋 …gefällt sie Ihnen? Ich würde gern Ihre Meinung dazu auf meiner Diskussionsseite erfahren. ↩︎

Umzug von Github Pages

Schallbert — Mon, 01 Jan 0001

Projekt-Steckbrief

Schwierigkeitsgrad: Mittel 3/5
Kosten: 5-50€/Monat
Zeitaufwand: ~10h

Motivation

Ich habe mich entschieden, meine Website von Github-Pages auf meinen eigenen Server umzuziehen. Dies geschieht aus zwei Gründen: Zum einen möchte ich den Server in Deutschland stehen haben (Datenschutz) und zum anderen bietet mir Github Pages keine einfach zu handhabende Möglichkeit, meine Site zweisprachig anzubieten.

Zusätzlich kann ich ebenfalls ein paar lang gehegte Wünsche realisieren: Ein eigener mini-Dateiserver und eine Webseite für meinen kleinen Nebenerwerb werden jetzt möglich. Aufsetzen werde ich sie allerdings in einem späteren Schritt.

Überblick

In diesem Projekt werde ich einen virtuellen Server anmieten und dort per SSH das Container-Managementsystem Docker installieren.

In einem Container soll eine Instanz von gitea laufen, welche das Versionsmanagement für mich übernehmen und über sogenannte Actions eine CI/CD-Pipeline¹ bereitstellen wird.

Durch die Automation mit Gitea Actions möchte ich dann in der Lage sein, die von Jekyll per Workflow-Datei gebaute Site auf einem caddy-Server zu veröffentlichen, also in “Produktion” zu geben.

caddy stellt hier nicht nur den Server, sondern auch einen Reverse Proxy zur Verfügung, welcher mir Portmapping und die Adresszuordnung abnehmen kann. Ganz nebenbei kümmert sich caddy noch vollautomatisiert um die Zertifikatsverwaltung für https über Let’s Encrypt.

Da auch caddy in Docker laufen wird, müssen virtuelle Netzwerke angelegt und korrekt konfiguriert werden, sodass die Container miteinander “reden” können.

Schreiten wir zur Tat - aber immer Schritt für Schritt.

Konfiguration meines Servers

Die folgenden Abschnitte beschreiben Schritt für Schritt, wie ich vorgegangen bin, meinen Cloud-Server einzurichten und für das Veröffentlichen dieses Blogs vorzubereiten.

SSH auf dem Server einrichten

Direkt nachdem ich den sogenannten “Cloud-Server” angemietet hatte, habe ich den Zugriff per SSH konfiguriert und damit den Passwort-Login deaktiviert. Dafür prüfe ich zuerst, ob mein ssh-agent bereits läuft bzw. starte ihn direkt mit dem Befehl eval ssh-agent.

Sodann erstelle ich mir ein neues Schlüsselpaar per Befehl

ssh-keygen -t ed25519 -C "your_email@example.com" -f "~/.ssh/mein-cloud-server"

Dieses Beispiel erzeugt Schlüsseldateien mit dem Verfahren (-t) ed25519, welche per Kommentar (-C) eine Mailadresse enthalten und unter dem Dateinamen (-f) mein-cloud-server gespeichert werden.

Den öffentlichen Schlüssel mein-cloud-server.pub habe ich dann im Webportal meines Servers unter “Security” eingegeben und den dann erhaltenen Fingerprint verifiziert mittels

ssh-keygen -lf <fingerprint_from_server> "~/.ssh/mein-cloud-server"

Anschließend habe ich die config-Datei im .ssh-Verzeichnis so angepasst, dass ich nur noch ssh server statt der IP-Adresse eingeben muss, um mich drauf zu verbinden - Faulheit siegt 😀

#.ssh/config
Host server
 User root
 Hostname ip_address_of_server
 PreferredAuthentications publickey
 IdentityFile ~/.ssh/mein-cloud-server

Gebe ich nun ssh server in die Konsole ein, so erscheint beim ersten Mal die Meldung, dass der Verbindungsaufbau zu einem unbekannten Partner mit Fingerprint soundso stattfinden wird und bittet um explizite Zustimmung. Nun kann der Fingerprint mit dem des Servers (auf der Webseite des Anbieters) abgeglichen und somit sichergestellt werden, dass man auch wirklich zu dem angestrebten, eigenen Server verbindet und nicht zu einem Dritten, der die Anfragen lediglich transparent weiterleitet. Stimmt man mit yes zu, so wird der Fingerprint der known_hosts-Datei hinzugefügt und das Zielsystem in Zukunft als bekannt angesehen.

Docker installieren 🐳

Auf meinem Server läuft ein Standard-Ubuntu, für die die von Docker bereitgestellte Anleitung zur Installation des Docker-Repository per apt reibungslos funktioniert. Einfach per SSH drauf einwählen und die entsprechenden Befehle ausführen - fertig. Dabei wird der von mir benutzte Dienst docker-compose gleich mit installiert, welcher Konfigurationsdateien für die Zielcontainer interpretieren und die Container mit den entsprechenden Parametern gleich richtig hoch- und herunterfahren kann.

caddy installieren 🛒

Zuerst lege ich den Ordner per mkdir caddy2 im Stammverzeichnis meines Servers an - soviel Zeit muss sein. Um caddy im Docker laufen lassen zu können, habe ich in diesem Ordner die folgende docker-compose.yml erstellt:

#caddy2/docker-compose.yml

version: '3'
services:
 caddy:
 image: caddy:latest
 container_name: caddy
 ports:
 - "80:80"
 - "443:443"
 environment:
 - ACME_AGREE=true
 restart: unless-stopped
 volumes:
 - ./Caddyfile:/etc/caddy/Caddyfile
 - ./caddy_data:/data
 - ./caddy_config:/config
 - ./www:/www
 networks:
 - caddy-proxy

networks:
 caddy-proxy:
 external: true

Diese Datei sagt Docker, dass es für den Service das aktuellste Image von caddy verwenden und dem Container den Namen caddy geben soll. Des Weiteren sollen die Ports 80 (http) sowie 443 (https) verfügbar gemacht und die Zertifikatsverwaltung per ACME_AGREE zugelassen werden. Der Container bindet die von Caddy benötigten Dateien (Caddyfile, data, config) ein und kann ebenso auf die von mir unter /www abgelegten Dateien zum späteren Veröffentlichen meiner Website zugreifen. Der Container befindet sich im Netzwerk caddy-proxy und durch external: true weiß der Container, dass dieses Netzwerk unabhängig von diesem Container bereits besteht.

Damit wir den caddy-Container korrekt aufsetzen können, müssen wir also das Docker-Netzwerk vorher per docker network create caddy-proxy erstellen. Mit docker network ls kann man nun prüfen, ob das Netzwerk korrekt angelegt wurde.

NETWORK ID NAME DRIVER SCOPE
<redacted> bridge bridge local
<redacted> caddy2_default bridge local
<redacted> caddy-proxy bridge local

Sieht gut aus!

Anschließend erstelle ich eine Caddyfile zur Konfiguration von Caddy:

# caddy2/Caddyfile
blog.schallbert.de {
 root * /www/blog
 encode gzip
 file_server
}

Dieser Eintrag sagt caddy, dass der Inhalt des Ordners /www/blog als Dateiserver, der die gzip-Komprimierung unterstützt, unter blog.schallbert.de verfügbar machen soll.

Test-Website erstellen 🧪

Ach ja, was auch noch wichtig ist, bevor wir den Container starten: Der DNS² sollte die Adresse auch auflösen können. Dafür logge ich mich in meinem DNS-Manager ein und ordne der Subdomain die feste IP-Adresse meines Servers zu:

TYPE NAME VALUE TTL
A blog.schallbert.de <redacted> 86400

Schlussendlich soll der Server ja auch etwas anzeigen können. Eine Testseite genügt ja schon. Also ganz fix:

mkdir ~/caddy2/www/blog
cd ~/caddy2/www/blog
nano index.html

Und dort dann ein unverkennbares Hello World eintragen:

<!-- blog/index.html -->
<h1>ALL YOUR BASE ARE BELONG TO US</h1>

Speichern, fertig.

Das Stammverzeichnis von caddy sieht nun so aus:

*caddy_config* *caddy_data* Caddyfile docker-compose.yml *www*

Jetzt endlich kann der Container erstellt und caddy darin hochgefahren werden:

docker compose up -d

Die Option -d bedeutet “detach”, also wird der Container hochgefahren und von der Konsole abgekoppelt, sodass sie nicht blockiert wird.

[+] Running 1/1
 ✔ Container caddy Started

Super, das sieht auch gut aus. Jetzt schnell mal auf die Seite navigieren:

Gitea installieren 🍵

Wie oben kurz angerissen, benötige ich Gitea für zwei Zwecke: Erstens möchte ich für meine Dateien wie von Github gewohnt ein Versionsmanagement haben und zweitens möchte ich meine Seite mit Hilfe von Gitea über Jekyll bauen und dann auf den Server schieben.

Wie schon bei caddy, beginnt alles in einem entsprechenden Ordner:

cd ~
mkdir gitea
cd gitea
nano docker-compose.yml

Die docker-compose.yml für Gitea habe ich mir aus verschiedenen Beispielen zusammengebastelt. Hier ist sie:

# gitea/docker-compose.yml
version: "3"

networks:
 gitea:
 external: false
 caddy-proxy:
 external: true
 name: caddy-proxy

services:
 gitea:
 image: gitea/gitea:latest
 container_name: gitea
 restart: always
 environment:
 - USER_UID=1000
 - USER_GID=1000
 - SSH_DOMAIN=git.schallbert.de
 - GITEA_HOSTNAME=git.schallbert.de
 networks:
 - gitea
 - caddy-proxy
 volumes:
 - ./gitea:/data
 - ./log:/app/gitea/log
 - /etc/timezone:/etc/timezone:ro
 - /etc/localtime:/etc/localtime:ro
 ports:
 - "127.0.0.1:3000:3000"
 - "222:22"
 runner:
 image: gitea/act_runner:nightly
 environment:
 - CONFIG_FILE=/config.yml
 - GITEA_INSTANCE_URL=https://git.schallbert.de
 - GITEA_RUNNER_NAME=ichlaufe
 - GITEA_RUNNER_REGISTRATION_TOKEN=
 volumes:
 - ./runner/config.yml:/config.yml
 - ./runner/data:/data
 - /var/run/docker.sock:/var/run/docker.sock

Die Bedeutung ist in etwa wie folgt: gitea ist Teil der Docker-Netzwerke gitea sowie caddy-proxy. Der Container, in dem der Service läuft, heißt gitea und wird bei Absturz stets automatisch neu gestartet. Die User-ID wird mit 1000 in einem Wertebereich gesetzt, welcher weder für Administratoren noch andere besondere Benutzer reserviert ist. Per SSH und http ist gitea unter git.schallbert.de erreichbar, und zwar auf Ports 22 bzw. 3000 - dort aber nur per localhost, also nicht “von außen”.

Gitea hat Zugriff auf Zeitzone und Lokalzeit des Servers, außerdem legt es Logs unter /log und Dateien unter /data ab. Gitea verfügt über einen action runner, der auf der gitea-Instanz läuft, ichlaufe heißt und dessen Konfiguration in der config.yml zu finden ist. Der Runner kann im Docker über dessen Standard-Socket Aktionen ausführen, z.B. ubuntu-latest installieren und darauf Jekyll zum Laufen bringen. Die Basiskonfiguration des Runners habe ich dem offiziellen Repository entnommen.

Gitea akzeptiert nur Runner, deren Token unter GITEA_RUNNER_REGISTRATION_TOKEN registriert sind - Dies holen wir zu einem späteren Zeitpunkt nach.

Nun starten wir Gitea mal, sodass wir die erforderlichen Ordner zur Konfiguration erstellt bekommen.

docker compose up

So sieht die Konsolenausgabe bei mir aus:

[+] Running 4/2
 ✔ Network gitea_default Created 0.0s 
 ✔ Network gitea_gitea Created 0.1s 
 ✔ Container gitea Created 0.1s 
 ✔ Container gitea-runner-1 Created 0.0s 
Attaching to gitea, gitea-runner-1
gitea | Server listening on :: port 22.
gitea | Server listening on 0.0.0.0 port 22.
gitea | 2023/11/18 17:19:52 cmd/web.go:242:runWeb() [I] Starting Gitea on PID: 15
gitea | 2023/11/18 17:19:52 cmd/web.go:111:showWebStartupMessage() [I] Gitea version: 1.21.0 built with GNU Make 4.4.1, go1.21.4 : bindata, timetzdata, sqlite, sqlite_unlock_notify
gitea | 2023/11/18 17:19:52 cmd/web.go:112:showWebStartupMessage() [I] * RunMode: prod
gitea | 2023/11/18 17:19:52 cmd/web.go:113:showWebStartupMessage() [I] * AppPath: /usr/local/bin/gitea
gitea | 2023/11/18 17:19:52 cmd/web.go:114:showWebStartupMessage() [I] * WorkPath: /data/gitea
gitea | 2023/11/18 17:19:52 cmd/web.go:115:showWebStartupMessage() [I] * CustomPath: /data/gitea
gitea | 2023/11/18 17:19:52 cmd/web.go:116:showWebStartupMessage() [I] * ConfigFile: /data/gitea/conf/app.ini
gitea | 2023/11/18 17:19:52 cmd/web.go:117:showWebStartupMessage() [I] Prepare to run web server

Webzugriff einrichten

Nun gehe ich erneut in meinen DNS-Manager und setze die Adresse für den Webzugriff:

TYPE NAME VALUE TTL
A git.schallbert.de <redacted> 86400

Außerdem muss die Caddyfile angepasst werden, damit Anfragen aus dem Web auch richtig weitergeleitet werden können. Also zurück in den caddy2 Ordner und mit nano Caddyfile folgenden Abschnitt hinzufügen:

# caddy2/Caddyfile
git.schallbert.de {
 reverse_proxy * http://gitea:3000
}

Nun werden Anfragen nach git.schallbert.de auf den im Docker geöffneten Port 3000 des Gitea-Containers weitergeleitet.

Gitea per Web-Oberfläche konfigurieren

Navigiere ich im Browser jetzt auf die entsprechende Adresse, so bekomme ich ein Login-Fenster angezeigt - genau wie in dieser Demo.

Nun denke ich mir ein schönes Passwort aus, klicke auf Register und bekomme hernach die Möglichkeit, Gitea per Weboberfläche zu konfigurieren. Dies tue ich aber nur rudimentär, denn ich möchte am Ende ja meine eigene Konfiguration verwenden.

Anschließend erstelle ich wie im Kapitel SSH einrichten oben beschrieben ein weiteres SSH-Schlüsselpaar per ssh-keygen und passendem Dateinamen -f ~/.ssh/gitea. Diesen lade ich dann auf Gitea unter Settings->SSH/GPG Keys hoch und verifiziere ihn.

Nun kann ich auf meinem Rechner erneut in der config-Datei des .ssh-Verzeichnisses den Abschnitt zum Login auf Gitea erstellen:

# .ssh/config
Host gitea
 User schallbert
 Hostname git.schallbert.de
 PreferredAuthentications publickey
 Identityfile ~/.ssh/schallbert_gitea

Jetzt schnell prüfen, ob auch alles funktioniert:

ssh gitea
Host 'git.schallbert.de' is known and matches the ED25519 host key.
debug1: Found key in /home/schallbert/.ssh/known_hosts

Perfekt.

Gitea-Konfiguration per `app.ini` fertigstellen

Da die Konfiguration aber noch nicht abgeschlossen ist, fahre ich den Container nun wieder herunter:

docker compose down

und navigiere nach /gitea/gitea/conf. Dort öffne ich die app.ini und modifiziere sie wie folgt:

# conf/app.ini
APP_NAME = Gitea: Git with a cup of tea
RUN_MODE = prod
RUN_USER = git
WORK_PATH = /data/gitea

[repository]
ROOT = /data/git/repositories
DEFAULT_BRANCH = main

[repository.local]
LOCAL_COPY_PATH = /data/gitea/tmp/local-repo

[repository.upload]
TEMP_PATH = /data/gitea/uploads

[server]
APP_DATA_PATH = /data/gitea
DOMAIN = git.schallbert.de
SSH_DOMAIN = git.schallbert.de
HTTP_PORT = 3000
ROOT_URL = https://git.schallbert.de/
DISABLE_SSH = false
SSH_PORT = 222
SSH_LISTEN_PORT = 22
LFS_START_SERVER = true
LFS_JWT_SECRET = <redacted>
OFFLINE_MODE = false

[database]
PATH = /data/gitea/gitea.db
DB_TYPE = sqlite3
HOST = localhost:3306
NAME = gitea
USER = root
PASSWD =
LOG_SQL = false
SCHEMA =
SSL_MODE = disable

[indexer]
ISSUE_INDEXER_PATH = /data/gitea/indexers/issues.bleve

[session]
PROVIDER_CONFIG = /data/gitea/sessions
PROVIDER = file

[picture]
AVATAR_UPLOAD_PATH = /data/gitea/avatars
REPOSITORY_AVATAR_UPLOAD_PATH = /data/gitea/repo-avatars

[attachment]
PATH = /data/gitea/attachments

[log]
MODE = file
LEVEL = info
ROOT_PATH = /data/gitea/log

[security]
INSTALL_LOCK = true
SECRET_KEY =
REVERSE_PROXY_LIMIT = 1
REVERSE_PROXY_TRUSTED_PROXIES = *
INTERNAL_TOKEN = <redacted>
PASSWORD_HASH_ALGO = pbkdf2

[service]
DISABLE_REGISTRATION = true
REQUIRE_SIGNIN_VIEW = false
REGISTER_EMAIL_CONFIRM = false
ENABLE_NOTIFY_MAIL = false
ALLOW_ONLY_EXTERNAL_REGISTRATION = false
ENABLE_CAPTCHA = false
DEFAULT_KEEP_EMAIL_PRIVATE = false
DEFAULT_ALLOW_CREATE_ORGANIZATION = false
DEFAULT_ENABLE_TIMETRACKING = true
NO_REPLY_ADDRESS = noreply.localhost

[lfs]
PATH = /data/git/lfs

[mailer]
ENABLED = false

[openid]
ENABLE_OPENID_SIGNIN = true
ENABLE_OPENID_SIGNUP = true

[cron.update_checker]
ENABLED = false

[repository.pull-request]
DEFAULT_MERGE_STYLE = merge

[repository.signing]
DEFAULT_TRUST_MODEL = committer

[oauth2]
JWT_SECRET = <redacted>

[actions]
ENABLED = true

Hier ist wichtig zu sicherzustellen, dass ROOT_URL und die Portkonfiguration mit jener der docker-compose.yml übereinstimmt. Die Datenbank (sqlite3) wird konfiguriert und gitea zugänglich gemacht. Außerdem deaktiviere ich aus Sicherheitsgründen die Registrierungsmöglichkeit neuer Benutzer DISABLE_REGISTRATION = true sowie jene per Openid ENABLE_OPENID_SIGNIN = false ENABLE_OPENID_SIGNUP = false und schalte Gitea Actions per ENABLED = true ein.

Nun kann der Container neu gestartet werden:

[+] Running 4/4
 ✔ Network gitea_default Created 0.1s 
 ✔ Network gitea_gitea Created 0.0s 
 ✔ Container gitea Started 0.0s 
 x Container gitea-runner-1 Error 0.1s

Gut, Gitea läuft schonmal. In einem letzten Schritt kümmere ich mich nun um den Action Runner.

Action Runner einrichten 🏃

Für die ersten Schritte hilft die offizielle Anleitung weiter.

Ich logge mich erneut auf der Weboberfläche über git.schallbert.de ein. Die Aktivierung von Actions in der app.ini im vorigen Abschnitt lässt jetzt bei Settings->Actions ein neues Menü erscheinen. Hier klicke ich nun auf Create new Runner und kopiere mir das REGISTRATION TOKEN.

Anschließend öffne ich die docker-compose.yml im Gitea-Stammverzeichnis erneut und füge wie hier vorgeschlagen Folgendes ein:

# gitea/docker-compose.yml
# [...]
runner:
 image: gitea/act_runner:nightly
 environment:
 - CONFIG_FILE=/config.yml
 - GITEA_INSTANCE_URL=https://git.schallbert.de
 - GITEA_RUNNER_NAME=ichlaufe
 - GITEA_RUNNER_REGISTRATION_TOKEN= <redacted>

Nach einem Neustart des Containers mit docker compose down && docker compose up -d erscheint nun der Runner als “gestartet” im Log:

✔ Network gitea_default Created 0.1s 
✔ Network gitea_gitea Created 0.0s 
✔ Container gitea Started 0.0s 
✔ Container gitea-runner-1 Started 0.1s

Hervorragend, jetzt schauen wir auf der Weboberfläche nach und siehe da:

Fehlt noch der Beweis, dass der Runner auch wirklich arbeitet.

Funktionsprüfung Runner

Für die Prüfung des Action Runner nehme ich erneut die Dokumentation von Gitea zur Hilfe. Ich erstelle ein neues Repository auf der Gitea-Weboberfläche mit Namen runner-test und füge den Inhalt der oben verlinkten Datei im Verzeichnis /.gitea/workflows/01-test.yml hinzu.

Commit, push, und - nichts.

Ah, der Workflow startet nur on: [push]. Er kann also gar nicht starten, wenn er gerade selbst erst auf den Server geladen wurde.

Gut, erstelle ich halt noch eine Datei, commit, push. Ergebnis:

Wahnsinn! 🥳

Zwischenfazit

Ich habe hier so getan, als wäre der Weg in einer geraden Linie verlaufen und als hätte alles reibungslos geklappt. Leider traf das so nicht zu. Es war zwar überraschend einfach, die Programme in Docker zum Laufen zu bringen, doch miteinander reden wollten sie lange nicht. Ich hatte zudem ziemliche Probleme mit der Caddyfile So einfach sie auch erscheinen mag, lange wollte so gar nichts in meinem Browser erscheinen - weder Gitea noch die blog-Testseite. Ein Ping an die Seite vom Terminal des Servers aus funktionierte aber, also konnte ich den Fehler schnell auf die Konfiguration von caddy zurückführen.

Die Ursache: Da caddy im Docker läuft, muss die Caddyfile als Volume eingebunden werden. Im Caddyfile selber muss der Ordner vom Root des Volumes aus, also mit führendem /, angegeben werden.

Auf der anderen Seite hat die Konfiguration von Gitea viel reibungsloser geklappt, als ich dachte. Sogar das aufwendige Freischalten des Runners, welcher auch im Docker nochmal extra geroutet werden muss, war weniger schlimm als ich dachte.

Mit diesem Grundgerüst habe ich jetzt einen flinken Server, welcher meinen Blog später bestimmt reibungslos hosten kann.

Die nächsten Schritte - das Aufsetzen des Bauprozesses für meine Website - werden in diesem Artikel hier und dann auch in Jekyll nativ hier abgehandelt.

Am Ende möchte ich schließlich wieder dahin zurückkehren, Inhalte zu erzeugen. Und mich nicht mehr als nötig mit dem Drumherum beschäftigen.

CI/CD steht für “Continuous Integration / Continuous deployment” und bedeutet, dass das System bei Update der verwalteten Dateien automatisch die Website neu baut, testet und veröffentlicht. ↩︎
DNS steht für Domain Name System, ein verteiltes hierarchisches System zur Namensauflösung von Websites. Hintergrund ist, dass es viel schwieriger ist, sich eine IPV6-Adresse wie 2a02:ec80:300:ed1a:0:0:0:1 zu merken statt en.wikipedia.org in die Adresszeile eines Browsers einzugeben. ↩︎

CI/CD on Schallberts Blog

Giteas act_runner rootless: Startprobleme

Das Fehlerbild

Issue-Ticket bei Gitea

Problem mit Kernel-Berechtigungen?

Warum Container keine Container starten dürfen

Auswirkungen, falls trotz DinD etwas schief geht

Einfache Lösung: DinD-Container privileged starten

Sackgasse: Nur unbedingt benötigte Rechte vergeben

Zukünftige Lösung: Virtualisierung oder Daemonless

Linux Security Modules (seccomp, AppArmor, SELinux)

Apparmor

Einfache Lösung: Komplett abstellen

Richtige Lösung: Für jede Anwendung justieren

Jekyll-dockerimage: Bundler und Gemfile

Was ist bundler?

bundler in der CI-Pipeline

Keine Schreibrechte

Spezifikationsdatei für bundler

Fehlerbehebung

Gemfile.lock für verschiedene Umgebungen optimieren

Giteas act_runner: Startprobleme

Das Problem

Die kurzfristige Lösung

Ursachenforschung

Lösung: Abhängigkeiten abbilden

depends_on

Healthcheck

Fehler-Logdateien versenden

Worum geht es hier?

Verifikation und Überwachung

Was zeichnet ein gutes Monitoring für mich aus?

Methoden automatischer Berichterstattung

Mail per Konsole - curl

Mail per Konsole - mail, mailx, mailutils, swaks

RSS Feed erzeugen

borgmatic

fail2ban

Gitea

Server

Die Auswahl des Berichtsprogramms

Berichtsprogramm

Kommunikationsweg

Logging

Wann sollen Logs gesendet werden?

Was gehört für mich in einen Bericht?

Rohfassung eines Berichts

Durchführung

borgmatic

Server

Server-Konfiguration

Gitea

Ergebnis

Server-Konfiguration ausrollen

Worum geht es hier?

Wege und Möglichkeiten

Automatisierungsdienste Ansible, cdist, Kubernetes

Mein Weg

Risiko Zirkelbezug

Vorbereitung: Ordnersystem und Skripte erstellen

Durchführung: Shell-Script zum Abhandeln des Updates

Erster Test und Einhängen in den “Autostart”

Sicherungskopie

Zustand und Daten einfrieren

Borgmatic: Trigger-Handler Mechanismus #2 und #3

Das Backup anlegen

Zweiter Test zum Anlegen des Backups

Fehlerbehebung für “failed to acquire the lock”

Übertragen der Konfiguration

Umstieg auf rsync

Alle Anwendungen neu starten

Die fertige Automation

Server-Konfiguration mit Git

Worum geht es?

Hintergrund

Vorüberlegungen

1. Hardlink

2. Repo und auto-deploy auf den Server

Probleme

Auswahl meiner Lösung

Einfache Lösung: DinD-Container `privileged` starten

`Gemfile.lock` für verschiedene Umgebungen optimieren

Secrets in `docker-compose.yml`

Secrets in Giteas `app.ini`

act_runner: Kein Schreibzugriff auf `Gemfile.lock`

Abhängigkeiten: `sass-embedded`

Docker volumes für `act_runner` können Artefakte nicht verteilen

Aber man kann doch `upload-artifact` verwenden!

Auch Docker `cp` funktioniert in diesem Falle nicht