Coding on Schallberts Blog

Docker-Images automatisch updaten

Schallbert — Sun, 01 Nov 2026

Wozu automatische Updates?

Software altert bzw. die Zeit streicht an ihr vorbei, sodass sie gewartet und auf Stand gehalten werden muss.

“Software ist kein Vermögenswert, sondern eine Verbindlichkeit.” - Cory Doctorow, Jan-2026

In meinem Blog habe ich schon mehrfach von Problemen wie kritischen Schwachstellen in Gitea oder in PHP berichtet, Systemabstürze beseitigt und unabsichtlich veröffentlichten Seiten wieder eingefangen, deren Ursachen allesamt durch Updates oder Rekonfiguration behoben werden konnten.

Das Betriebssystem meines Servers und die wichtigsten darauf laufenden Programme erhalten bereits automatische Updates wie in meinem server-auto-upgrade Artikel beschrieben.

Trotzdem bin ich mit dem Thema noch nicht ganz fertig.

Docker image update mit Watchtower

Um meine Docker-Images kümmerte sich bis Dato das Programm Watchtower. Es gibt jedoch mehrere Gründe gegen seinen Einsatz:

Es wird nicht mehr aktiv gewartet und befindet sich im Archivzustand. Allerdings gibt es Forks, die weitergeführt werden.
Um zu funktionieren, benötigt es Zugriff auf den Docker Daemon per docker.sock. Dies ist gleichbedeutend mit Root-Zugriff des Containers auf mein System. Das will ich in Zukunft unbedingt vermeiden.

1:1-Ersatz für Watchtower benötigt? Linuxhandbook hat hier ein paar Lösungen aufgelistet. Allen gemein ist allerdings, dass sie entweder nur über vorhandene Updates informieren und sie nicht ausrollen, oder dass sie selbst ebenfalls den docker.sock als Volume benötigen.

Lösung per Skript

Auf der Suche nach einem Weg ohne das Sicherheitsrisiko docker.sock komme ich schnell zur Idee, täglich ein Skript per cron ausführen zu lassen. Dies geschieht mit root-Rechten und kann daher direkt Docker-Befehle ausführen.

Kompliziert: `docker pull`, Abgleich mit vorhandenen Images, bei Bedarf einspielen

Mein erstes Skript hat 164loc (Zeilen) und tut folgendes:

Prüfen, ob benötigte Werkzeuge curl, docker, docker compose, docker-comppose.yml installiert sind und funktionieren
Die aktuellen image digests der in der docker-compose.yml definierten Services herausfinden
Die Registry für jeden Service per docker compose pull aktualisieren
Per docker image inspect die “neuen” mit den “alten” image digests vergleichen
Die neuen Images per docker compose up starten, Logs wegspeichern
Bericht per ntfy an mich, falls Updates erfolgt sind.

Doch dieser Weg ist viel zu kompliziert gedacht. Das von mir verwendete Werkzeug docker compose bringt die benötigte Option direkt mit: docker compose up --pull always.

Einfach: Alles in einem Kommando per Option mitgeben

Der Kern meines neuen Skriptes (61loc) sieht wie folgt aus:

compose=(docker compose --progress plain -f "$COMPOSE_FILE")

before=$("${compose[@]}" ps --all --quiet | sort)

if output=$("${compose[@]}" up -d --pull always --quiet-pull --wait \
 --wait-timeout "$WAIT_TIMEOUT" 2>&1); then
 status=0
else
 status=$?
fi

printf '[%s] docker compose up (exit %s)\n%s\n\n' \
 "$(date -Is)" "$status" "$output" >> "$CHANGELOG"

if (( status != 0 )); then
 report_failure "WARNING: Docker update failed" "warning" "$output"
 exit "$status"
fi

after=$("${compose[@]}" ps --all --quiet | sort)
if [[ "$before" != "$after" ]]; then
 notify "INFO: Docker containers updated" "white_check_mark" "$output"
fi

Im Skript erhebe ich einen Status vor dem Update, indem alle in der Compose-Datei spezifizierten Services aufliste und in einer Variable zwischenparke. Anschließend führe ich wie üblich docker compose up -d durch, allerdings nicht ohne die Flags --pull always sowie --wait wait-timeout <time[s]> zu setzen.

Mit der Pull-Option prüft Docker die Registry auf neue Images, welche gegebenenfalls heruntergeladen und gestartet werden. Der Timeout gibt dem Befehl eine bestimmte Zeit zur Ausführung bevor es mit einer Fehlermeldung abbricht, damit sich das Skript nicht aufhängen kann.

Was folgt ist nur noch Dokumentation und Monitoring: Die Ausgabe des Befehls wird in das Changelog geschrieben, im Falle eines Fehlschlags bekomme ich eine Information per Notify wie in meinem Server-Logging Post beschrieben. Hier wird der before-Status wichtig: Ich eine Benachrichtigung nur bei Fehler oder Update.

Anschließend muss ich das Skript nur noch ausführbar machen chmod + x docker-image-update.sh und an root übergeben: chown root root docker-image-update.sh.

Eintrag für cron

Nach einem manuellen Test des Skripts ./docker-image-update.sh, Prüfung seiner Ausgabe, des Changelogs und den neuen Containerversionen, lasse ich das Skript täglich durch den Cron-Daemon aufrufen:

schallbert@machine: crontab -e
[...]
0 2 * * * /path/to/docker-image-update.sh

Welche Version wurde installiert?

Statt mit Versionsbezeichnungen der Services arbeitet Docker mit Image digests. Dieser sha256-hash ist für jedes Image einzigartig, aber nicht besonders leserfreundlich:

sha256:94a00394bc5a8ef503fb59db0a7d0ae9e1110866e8aee8ba40cd864cea69ea1a # example Image digest

Doch Service-Versionsbezeichnungen wie Gitea v28.2.1 werden in den Image-Metadaten nicht standardmäßig unterstützt. Daher habe ich erstmal noch keine Lösung für die Ausgabe einer Version. Die Digests lasse ich in der Ausgabe weg.

Meldung bei Update

Die Meldung ist verbesserungsfähig: Ich benötige eigentlich nur die Namen der Container Updates und die Bestätigung, dass alle Images danach wieder “healthy” sind. Zusätzlich erhalte ich aber die Zustände der Container, aus denen ich die benötigten Informationen erst extrahieren muss. Der Mehrwert einer Filterung erscheint mir aber derzeit zu gering, als dass ich meine Zeit in die Erweiterung des Skriptes stecken würde. Schließlich zeigt mir Recreate bereits an, welcher Container auf Stand gebracht wurde.

Ich bin zufrieden. Ich konnte vom Host aus mit wenigen Zeilen Code, aus Bordmitteln, und nur mit cron als zusätzlicher Abhängigkeit mein Updateproblem für die per Docker Compose verwalteten Container lösen.

Werkzeugvermessung automatisieren

Schallbert — Tue, 10 Feb 2026

Mich erreichen immer wieder Fragen zu meinem Post über CNC-Makros. In diesem Beitrag möchte ich ein paar Antworten geben und Details zur Vermessung und Kompensation verschiedener Werkzeuglängen teilen.

Frage: Wie berechnet das Makro die Werkzeuglänge?

Im Abschnitt Werkzeuglänge Vermessen steht folgender Code:

1 G53 G00 Z[zSafety] ; # Go to safety height (machine coordinates)
2 G53 G00 X[xPosTls] Y[xPosTls] ; # Go to tool length sensor
3 G53 G00 Z[zSpindleTip + toolLengthEst + 10] ;# Move Z down to 10mm above estimated tool tip

Was passiert in den Zeilen 1-3? Wenn Z=0 im Maschinenkoordinatensystem (G53) die höchste Position ist, sind zSpindleTip und toolLengthEst dann negative Werte?

Antwort:

Diese Zeile fährt die Maschine zum in Variable #4506 hinterlegten Wert. Bei mir ist er 0, also maximale Z-Höhe. Dieser Wert bleibt permanent gespeichert (siehe hier) und man muss ihn vorher im Makro-Setup-Dialog festlegen.
Führt eine Bewegung zum Werkzeuglängensensor (WZLS) im Maschinenkoordinatensystem aus. Dafür habe ich meinen Sensor an einem festen Punkt auf der Maschine platziert.
Mit zSpindleTip (Variable #4509) ist die Höhe auf der Z-Achse gemeint, in der die Spindelnase den Werkzeuglängensensor freitastet. Dieser Wert ist negativ. Weshalb? Der größte Wert der Z-Achse ist Null, wenn sie sich ganz am oberen Anschlag der Maschine befindet. Senkt man dia Achse von hier aus zum WZLS ab, bewegt man sie in negative Z-Richtung. Addiert man die geschätzte Werkzeuglänge toolLengthEst sowie eine Sicherheitshöhe von 10mm dazu (falls man sich bei der Werkzeuglängenschätzung vertan hat), bleibt aber unter dem mechanischen Anschlag der Z-Achse, so ist der Wert noch immer negativ. Die Spindelnase hat nun aber genügend Luft zum WZLS, weil jetzt virtuell Werkzeug und Sicherheitshöhe hinzuaddiert wurden.

Pro Tipp: Im “Variables” Tab von EdingCNC kann man sich Werte von Variablengruppen anzeigen lassen. Man gibt eine Gruppe ein, z.B. #4500 und erhält die Live-Werte aller zehn Variablen.

Um das gut nachvollziehen zu können bietet sich an, die CNC-Software zum Ausprobieren nebenbei im Simulationsmodus laufen zu lassen. Konkretes Beispiel:

zSafety = 0 ;# machine coordinates, Z-axis at top notch
zSpindleTip = -86.43 ;# machine coordinates, where empty spindle collet touches TLS
toolLengthEst = 35 ;# the length the tool is protruding from spindle collet

G53 G00 Z[-86.43 + 35 +10] # = -41.32mm, so below max Z height

Die Benennung der Variablen habe ich in meinem Makro-Repository auf Github abgelegt.

Frage: Wie berechne ich die Werkstückhöhe nach einer Werkzeugvermessung?

Folgendes Szenario: Man vermisst das Werkzeug und bestimmt anschließend per Makro die Werkstückhöhe. Wenn ich nun die Werkzeuglänge verändere ohne das Werkzeugwechselmakro aufzurufen, stimmt der Werkstücknullpunkt ja nicht mehr. Mit einem kürzeren Werkzeug liegt der Nullpunkt “zu tief”, bei einem Längeren “zu hoch”.

Wie kann man dieses Problem lösen?

Antwort: Mehrere Lösungswege

Aus meiner Sicht gibt es hier drei Lösungswege.

Werkzeuglängenänderung immer über das Werkzeugwechselmakro laufen lassen. Man kann dort ja dieselbe Werkzeugnummer erneut eingeben.
Den Z-Nullpunkt über die Werkstückvermessung neu setzen (nicht empfohlen¹)
Ohne Makro: Per Kommando G92 das Z-Koordinatensystem verschieben. Beispiel folgt.

Lösung #3: Koordinatensystem verschieben

Man kann das Werkstückkoordinatensystem mit den Befehl G92 Coordinate System Offset verschieben. Führt man ihn aus, so wird die ihm übergebene Zahl der angewählten Achse als neuer Wert im Koordinatensystem übernommen.

In diesem Fall wollen wir ja nur die relative Position verschieben und damit den Unterschied der Werkzeuglängen zueinander ausgleichen. Machen wir es mal konkret:

Nehmen wir an, das alte Werkzeug T17 hat eine freie Länge von 32mm und das neue Werkzeug (wieder T17, denn wir spannen in diesem Beispiel nur um oder setzen ein Schlichtwerkzeug mit gleichen Schnittdaten ein) eine freie Länge von 24mm. Der neue Wert ist kürzer, und daher muss der Nullpunkt um 8mm nach unten wandern. “Nach unten” ist im Koordinatensystem der Z-Achse ein negativer Wert.

;# Pseudocode
;# (CamelCaseWord steht für eine Variablennummer wie #5003):
G92 Z[AktuelleZPosition + (AlteWerkzeuglänge - NeueWerkzeuglänge)]
;# 20mm + (32mm - 24mm ) = 20mm + 8mm = 28mm

Verschiebung Werkstücknullpunkt vs. Werkstückkoordinatensystem

Diese Rechnung mag erst einmal verwirren, versetzt sie das Koordinatensystem doch nach oben. Aber genau das ist erforderlich, damit der Werkstücknullpunkt relativ zur Werkzeugspitze erhalten bleibt: Das Werkzeug ist 8mm kürzer. Da wir den Werkstücknullpunkt nicht nach unten schieben, muss das Koordinatensystem halt nach oben versetzt werden. So wird die nun längere Strecke zwischen Werkzeugspitze und Werkstück kompensiert.

Coordinate System	Tool tip position Z [mm]	Workpiece position Z [mm]	Tool top position Z [mm]	Workpiece position Z [mm]
	Before shift	Before shift	After shift	After shift
Workpiece	20	0	28	0
Machine	-41.42	-61,42	-41.42	-69,42

Man sieht hier, dass sich durch das Versetzen des Koordinatensystems die Position der Werkzeugspitze im Werkstückkoordinatensystem verändert. Die Z-Achse wird dabei nicht bewegt. Das Maschinenkoordinatensystem bleibt von dieser Änderung unberührt. Da die Z-Achse nun aber einen weiteren Weg zum Werkstück zurücklegen muss, liegt seine Position im Maschinenkoordinatensystem jetzt um -8mm unter dem vorigen Wert.

Rahmenbedingungen

Die Makros funktionieren nur unter bestimmten Voraussetzungen:

Die Werkzeuglänge wurde zuvor gemessen bzw. Werkzeugwechsel werden stets per Makro gesteuert und nicht ohne “Wissen” der Maschine
Der Werkstücknullpunkt wird bei bereits bekannter Werkzeuglänge ermittelt.
Es gab keinen Not-Aus oder einen anderen kritischen Fehler. Dies würde den flüchtigen Speicher für die relevanten Variablen löschen.

Nach einem Werkzeugwechsel die Werkstückhöhe in Z erneut einzumessen verschiebt meiner Ansicht nach den falschen Parameter. In Wirklichkeit hat sich doch nicht die Höhe des Werkstückes geändert, sondern die Position der Werkzeugspitze. Daher würde ich stets vorziehen, den sich ändernden Parameter anzupassen. ↩︎

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.

Den Server absichern

Schallbert — Fri, 12 Jan 2024

Motivation

OK. Nun läuft mein Server, baut automatisch meinen Blog und zeigt ihn auch problemlos an. So ganz fertig bin ich aber noch nicht. Denn ich könnte mehr für die Sicherheit des Servers tun, als überall Passwort-Logins zu deaktivieren.

Außerdem habe ich noch keine Backups. Und das ist ja nie gut. Also, packen wir’s an!

Unerwünschte Besucher aussperren

Ich bekomme in meinem SSH-Log im Root-Account des Servers einen Haufen Verbindungsversuche, die nicht von mir kommen:

[...]
Jan 11 00:19:29 sshd[93842]: Invalid user admin from 41.207.248.204 port 37194
Jan 11 00:19:29 sshd[93842]: pam_unix(sshd:auth): check pass; user unknown
Jan 11 00:19:29 sshd[93842]: pam_unix(sshd:auth): authentication failure; logname= uid=0 euid=0 tty=ssh ru>
Jan 11 00:19:31 sshd[93842]: Failed password for invalid user admin from 41.207.248.204 port 37194 ssh2
Jan 11 00:19:32 sshd[93842]: Connection closed by invalid user admin 41.207.248.204 port 37194 [preauth]
Jan 11 00:20:14 sshd[93886]: Invalid user svn from 84.108.40.27 port 44968
Jan 11 00:20:14 sshd[93886]: pam_unix(sshd:auth): check pass; user unknown
Jan 11 00:20:14 sshd[93886]: pam_unix(sshd:auth): authentication failure; logname= uid=0 euid=0 tty=ssh ru>
Jan 11 00:20:16 sshd[93886]: Failed password for invalid user svn from 84.108.40.27 port 44968 ssh2
Jan 11 00:20:16 sshd[93886]: Received disconnect from 84.108.40.27 port 44968:11: Bye Bye [preauth]
Jan 11 00:20:16 sshd[93886]: Disconnected from invalid user svn 84.108.40.27 port 44968 [preauth]
[...]

Wenn ich nicht wüsste, dass dies das inzwischen übliche “Rauschen” im Internet ist, würde es mich schon etwas beunruhigen. Ist ja fast so, als würde alle paar Sekunden jemand mit bösen Absichten versuchen, irgendeinen Schlüssel an meiner Haustür auszuprobieren. Was kann man dagegen also tun? Wegschicken!

fail2ban

Genau dies soll die Software fail2ban für mich übernehmen.

 __ _ _ ___ _ 
 / _|__ _(_) |_ ) |__ __ _ _ _ 
 | _/ _` | | |/ /| '_ \/ _` | ' \ 
 |_| \__,_|_|_/___|_.__/\__,_|_||_|
 v1.1.0.dev1 20??/??/??

Vereinfacht gesagt durchforstet fail2ban Zugriffslogs¹ nach IP-Adressen, für die fehlgeschlagene Anmeldeversuche registriert wurden, und “bannt” sie bei Überschreiten einer benutzerdefinierten Anzahl Versuche innerhalb einer bestimmten Zeit für einen gewünschten Zeitraum.

Wie dieser Bannspruch umgesetzt wird? Fail2ban modifiziert die iptables, greift also auf Paketfilterregeln zu (Stichwort Firewall), welche sich unten auf der Netzwerkschicht befinden. So werden hereinkommende Anfragen bereits geblockter Adressen gar nicht erst bis zu meinen Applikationen durchkommen².

fail2ban installieren

fail2ban scheint so etwas wie Industriestandard bei der Abwehr unerwünschter Zugriffsversuche auf Linux zu sein. Jedem Hobby- und Profiadmin den ich kenne war das Programm geläufig. Ich erntete für meine Unwissenheit des Öfteren ein müdes Lächeln.

Zu Installation und Konfiguration gibt es bereits einen Haufen Anleitungen da draußen plus der (sehr gut geschriebenen), die im Repo von Fail2ban gleich mitgeliefert wird. Daher gehe ich nicht besonders tief hierauf ein.

Ich entschied mich für die Installation im Docker-Container, damit ich die üblichen Abhängigkeiten gleich mitgeliefert bekomme. Dafür verwende ich die open-source Distribution von linuxserver und verfasse die folgende docker-compose.yml:

# /fail2ban/docker-compose.yml
version: "2.1"
services:
 fail2ban:
 image: lscr.io/linuxserver/fail2ban:latest
 container_name: fail2ban
 cap_add:
 - NET_ADMIN
 - NET_RAW
 network_mode: host
 environment:
 - PUID=1000
 - PGID=1000
 - TZ=Etc/UTC
 - VERBOSITY=-vv #optional
 volumes:
 - ./config:/config
 - /var/log/auth.log:/var/log/auth.log:ro # host ssh
 - /var/log/caddy2:/var/log/caddy2:ro  # gitea via caddy, caddyserver
 restart: unless-stopped

Das Einzige, was hier zu beachten gilt: fail2ban benötigt die Access logs per Volume zur Verfügung gestellt (oben als :ro nur mit Lesezugriff angegeben). Eine Menge Filterregeln liegen bereits vorkonfiguriert im config-Ordner, daher muss ich nur die jail.local nach linuxserver/fail2ban-confs sowie filter.d für Caddy nach muetsch.io anpassen und schon habe ich einen automatischen Türwächter.

fail2ban Beispiel

So sieht ein fail2ban-Log nun für meinen SSH-Daemon aus:

# schallbert:/opt/fail2ban/config/log/fail2ban# grep "220.124.89.47" fail2ban.log 
 2024-01-11 17:12:20,600 7FBB3630BB38 INFO [sshd] Found 220.124.89.47 - 2024-01-11 17:12:20
 2024-01-11 17:12:23,003 7FBB3630BB38 INFO [sshd] Found 220.124.89.47 - 2024-01-11 17:12:22
 2024-01-11 17:12:25,205 7FBB3630BB38 INFO [sshd] Found 220.124.89.47 - 2024-01-11 17:12:24
 2024-01-11 17:12:27,206 7FBB3630BB38 INFO [sshd] Found 220.124.89.47 - 2024-01-11 17:12:26
 2024-01-11 17:12:32,610 7FBB3630BB38 INFO [sshd] Found 220.124.89.47 - 2024-01-11 17:12:32
 2024-01-11 17:12:33,045 7FBB36104B38 NOTIC [sshd] Ban 220.124.89.47

Und tschüss!

Was (noch) nicht funktioniert: Gitea & fail2ban

Ich bekomme auch auf meiner Gitea-Instanz ssh-Anfragen rein, die ich ebenfalls gern wegblocken möchte. Allerdings kann ich Gitea bis jetzt partout nicht dazu bekommen, die Logs dafür auch in eine Datei zu schreiben. Bis jetzt werden die stets an die Konsole geschickt, wo ich sie fail2ban natürlich nicht zuführen kann und möchte. Tatsächlich wird die Verbindung zu Gitea per SSH zum Glück bereits gesichert, da sie über denselben sshd geht wie der Shell-Zugriff auf meinen Server selbst.

Was mir noch fehlt sind nur die Überwachung fehlgeschlagener Logins auf dem Web-Frontend.

Dabei sieht Giteas app.ini für mich sauber aus:

# gitea/conf/app.ini
#[...]
[log]
MODE = file
LEVEL = warn
ROOT_PATH = /data/gitea/log
ENABLE_ACCESS_LOGS = true
ENABLE_SSH_LOG = true
logger.access.MODE = access-file

[log.access-file]
MODE = file
ACCESS = file
LEVEL = info
FILE_NAME = access.log
[...]

Ich habe sowohl die Access-Logs aktiviert ENABLE_ACCESS_LOGS und den Access-Logger in eine Datei schreiben lassen. Die Logs werden auch erstellt, nur sind da keine Zugriffe drin aufgelistet - diese gehen nach wie vor in die Konsole des Containers. Ich bin mir aber noch unsicher, ob der Reverse-Proxy von Caddy hier vielleicht einen Einfluss hat und er zum Beispiel die Zugriffe vor Gitea bereits abfängt. Aber das finde ich schon irgendwann noch heraus.

im Docker-Container eine beliebige IP sperren (docker exec -it fail2ban sh): fail2ban-client set sshd banip 111.111.111.111
In den iptables nachsehen, ob diese IP dort auftaucht: iptables -n -L --line-numbers
In meinem Falle: freuen, denn sie ist da: 1 REJECT all -- 111.111.111.111
Die IP wieder entsperren fail2ban-client set sshd unbanip 111.111.111.111

Schutz vor Brute-Force Angriffen per ssh wie oben beschrieben
Schutz vor Überlast mittels Rate Limiter
Schutz vor Angriffen auf die APIs (404/403 Attacken) mittels caddy-status Konfiguration für fail2ban, Logs in JSON

# /config/fail2ban/filter.d/caddy-status.conf

# this regex works for caddy with json-style logs
failregex = "client_ip":"<HOST>"(.*)"status":(400|401|403|404|500)
datepattern = \d+
ignoreregex =

Regelmäßige Backups

Ein wichtiger Aspekt für mich ist die Möglichkeit, den Server wiederherstellen zu können. Sollten unvorhergesehene Ereignisse eintreten wie ein Update einer Komponente welches die Funktion anderer Programme beeinträchtigt, der Ausfall des Servers, oder sogar der Zugriff fremder Personen auf selbigen - in jedem Falle könnte ich mit einem Backup recht schnell eine neue Instanz des Servers erzeugen, konfigurieren und die Website wieder zum Laufen bringen.

Diese Updates möchte ich aber ungern selbst von Hand aus meinen Ordnern erzeugen, komprimieren und per SCP / SFTP herunterladen. Besser soll das vollautomatisch vonstatten gehen, und das im Optimalfall noch kostenfrei. Nach einer kurzen Recherche stellen sich für meine Zwecke die quelloffenen Werkzeuge borgmatic und restic als geeignet heraus.

Ich entscheide mich willkürlich für Borgmatic.

Borgmatic in Docker installieren

Wie bei allen anderen Komponenten auch, möchte ich Borgmatic in einem Container laufen lassen. Glücklicherweise gibt es da bereits eine fertige Lösung, die ich nur noch ein wenig konfigurieren muss.

Mein docker-compose File für Borgmatic sieht wie folgt aus:

# /borgmatic/docker-compose.yml
version: '3'
services:
 borgmatic:
 image: ghcr.io/borgmatic-collective/borgmatic
 container_name: borgmatic
 volumes:
 - ${VOLUME_SOURCE}:/mnt/source:ro  # backup source
 - ${VOLUME_TARGET}:/mnt/repository  # backup target
 - ${VOLUME_ETC_BORGMATIC}:/etc/borgmatic.d/  # borgmatic config file(s) + crontab.txt
 - ${VOLUME_BORG_CONFIG}:/root/.config/borg  # config and keyfiles
 - ${VOLUME_SSH}:/root/.ssh  # ssh key for remote repositories
 - ${VOLUME_BORG_CACHE}:/root/.cache/borg  # checksums used for deduplication
 # - /var/run/docker.sock:/var/run/docker.sock # add docker sock so borgmatic can start/stop containers to be backupped
 environment:
 - TZ=${TZ}
 - BORG_PASSPHRASE=${BORG_PASSPHRASE}
 restart: always

Als Inspiration hierfür habe ich reichlich in der Dokumentation auf Github gestöbert.

Borgmatic konfigurieren

Alle konkreten Daten (die Angaben in ${}) habe ich zur besseren Übersichtlichkeit in einer .env-Datei im selben Verzeichnis abgelegt. Ganz nebenbei verhindere ich, aus Versehen Passphrases zu veröffentlichen. Diese Passphrase habe ich mir zusätzlich auf einem Zettel notiert - man weiß ja nie, ob man sie nochmal benötigt.

Ich muss anschließend nur noch die sich in dem Ordner borgmatic.d/ befindliche config.yml leicht verändern, indem ich Backup-Quelle, -Ziel und die von mir gewünschten Zeitintervalle für die Sicherungserstellung eintrug und war quasi schon bereit für einen ersten Test.

Borgmatic Funktionstest

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

Mit diesem Befehl führe ich über Docker im Container borgmatic den Befehl zum Anlegen einer Sicherung an, um die Funktion von Borgmatic zu verifizieren.

Hier kam dann direkt eine Fehlermeldung à la repository does not exist zurück. Also existiert das Backup-Ziel noch gar nicht. Ein kurzer Blick in die Dokumentation zeigt, dass das Repository erst initialisiert werden muss.

Dies hole ich mit dem Kommando

docker exec borgmatic bash -c \
"borgmatic init --encryption repokey-blake2"

nach, was mit ein “leeres”, verschlüsseltes Repository anlegt. Versuche ich erneut, ein Backup zu erzeugen, läuft Borgmatic nun durch und erzeugt mir das Backup im Repository.

Ein Backup ist nur ein Backup…

…wenn man es einspielen kann, sagt mein Kumpel.

Er hat Recht, aber so richtig traue ich mich nicht, über meine funktionierende Serverkonfiguration drüberzubügeln. Also erstelle ich mir eine docker-compose.restore.yml Datei nach Vorbild auf dem Repository und ziehe modem7s Anleitung zum Thema hinzu.

Tatsächlich kann ich durch Ausführen der docker-compose.restore.yml dann in der Container-Shell folgende Kommandos ausführen:

mkdir backuprestoremount
borg mount /mnt/repository /backuprestoremount

mkdir backuprestore
borgmatic extract --archive latest --destination /backuprestore

Hier erstelle ich den Ordner backuprestoremount und lasse ihn von borg auf mein Backup zeigen. Anschließend extrahiere ich das Backup in den ebenfalls neu erstellten Ordner backuprestore.

Nun prüfe ich, ob auch “alles da ist”:

# cd /mnt/backuprestore
# /restore/mnt/source ls
borgmatic caddy2 containerd fail2ban gitea hostedtoolcache watchtower

Yeah, alle Applikationen sind vorhanden und die enthaltenen Daten sind gesichert! Weiter gehe ich jetzt mal nicht, denn ich bin zu feige (und zu faul), die auf dem Server unter /opt befindlichen Container zu überschreiben.

Was (noch) nicht funktioniert: Borgmatic & docker-compose down

Borgmatic bietet eine einfache Möglichkeit in der Konfigurationsdatei, Aktionen vor- und nach dem Backup auszuführen.

Da ich die Konsistenz der Datenbanken meiner zu sichernden Container sicherstellen möchte, sollten die Container zum Zeitpunkt des Backups heruntergefahren sein. Daher schrieb ich mir ein Skript, was alle Applikationen vor dem Backup per docker compose down stoppt und nach dem Backup wieder hochfährt.

Dies würde auch alles prima funktionieren, wenn Borgmatic nicht selbst in einem Container liefe. Durch die Kapselung bin ich nun nicht in der Lage, die im Stamm-Dateisystem der Maschine befindlichen Skripte auszuführen. Kurzzeitig dachte ich, dass ich dies mittels Durchreichung von var/run/docker.sock in den Borgmatic-Container umgehen könne, scheiterte dann aber an der Ankopplung an Docker compose.

Ich bin mir sicher, dass das zu lösen ist. Allerdings habe ich gerade dringendere Themen. Daher begnüge ich mich mit der Annahme, dass schon nichts passiert, wenn ich das Backup nachts ziehe³.

Auch bei den Auto-Backups scheint es noch zu haken:

/ # borgmatic --stats
Starting a backup job.
Failed to create/acquire the lock /mnt/repository/lock (timeout).
local: Error running actions for repository
Command 'borg create --stats /mnt/repository::{hostname}-{now:%Y-%m-%dT%H:%M:%S.%f} /etc/borgmatic.d/config.yml /mnt/source /root/.borgmatic' returned non-zero exit status 2.
Error while creating a backup.
/etc/borgmatic.d/config.yml: An error occurred

Dies entnehme ich der über Docker aufgerufenen Log-Konsole von Borgmatic. Ich muss also beizeiten nochmal um meine Backups kümmern.

Beim SSH-Daemon meines Servers liegen die Zugriffslogs z.B. in /var/log/auth.log, können aber auch als access.log oder ähnlich abgelegt werden. Auch von mir verwendete Dienste wie Gitea und Caddy legen solche Logdateien an. ↩︎
Was ich allerdings noch nicht verstehe ist, wie fail2ban im Container laufend überhaupt an die iptables herankommt. Ich dachte, dass ein positiver Nebeneffekt der Containerisierung in der Kapselung liegt. Oder ist sie nur bei “rootless”-Containern zu erreichen? ↩︎
Hintergrund: Ich bin zur Zeit der Einzige, der Inhalte auf gitea hochlädt. Meine Webseite ist statisch. Auf dem Webserver caddy ändern sich also nur dann Dateien, wenn ich sie über Gitea hochlade. Programmupdates über watchtower und unattended-upgrades (Thema eines weiteren Artikels) habe ich so gelegt, dass sie nicht während des Durchlaufs von borgmatic stattfindet. Einzig die Logs, welche bei fail2ban aufschlagen, werden auch zur Zeit der Erstellung des Backups geschrieben. Das Risiko des Datenverlustes gehe ich an der Stelle bewusst aber ein, da die Paketfilterung für geblockte IP-Adressen durch fail2ban nach einer von mir bestimmten Zeit sowieso wieder aufgehoben wird. ↩︎

🗸 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.

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.

Steckbrett-Lagerfeuer

Schallbert — Sat, 10 Dec 2022

Materialliste

Gegenstand	Menge	~Preis [€]
LED: Warmweiß, z.B. Ifwd=30mA, 3lm	5	1,50
LED: Gelb, z.B. Ifwd=35mA, 1lm	2	0,60
LED: Rot, z.B. Ifwd=35mA, 0.4lm	1	0,30
Arduino Nano Atmega328	1	18
Steckbrett klein, z.B. 170 pins	1	0,70
Brückendrähte, pin-pin, z.B. 5cm	10	3,30

Dazu: Ein paar weitere Drähte, Mini USB-Kabel, Powerbank / USB-Ladegerät

Werkzeuge

Optional: Heißklebepistole
Optional: Lötkolben

Aufbau

LED aus der Nähe betrachtet ^[1]

Die rechte Pin-Seite des Arduino Nano mit der linken Seite des Steckbretts verbinden. Dabei darauf achten, dass alle Pins auf gleicher Höhe sind und möglichst nicht mit den Fingern zu berühren, da die Gefahr einer elektrostatischen Entladung besteht, die zu Beschädigung führen könnte.
Die Anoden (+) der LEDs mit den Ausgängen D2 bis D9 auf dem Steckbrett verbinden. Die Anode ist meistens der Pin der LED, der nicht mit der Lichtquelle belegt ist (im Bild oben wäre das links).
Die Kathoden (-) der LEDs auf der rechten Seite des Steckbretts auf gleicher Höhe einstecken.
Alle Kathoden mit Hilfe von Überbrückungsdrähten verbinden. Alternativ können die Kathoden auch gleich zusammen gelötet oder mittels einer Verteilerbrücke, wie in meinem Beispiel oben verwendet, durchverbunden werden.
Verbinden Sie die “gemeinsame Kathode” mit Hilfe eines Brückendrahtes mit einem der “GND”-Pins der Mikrocontroller-Platine.
Die Anoden der LEDs sollten sich nicht berühren. Das kann man einfach sicherstellen, indem sie mit etwas Heißkleber fixiert werden.

Programmierung

Der Code ist so einfach, dass ich ihn hier in Gänze herunterschreiben kann kann. Kopieren Sie ihn in Ihre Lieblings-IDE, programmieren Sie Ihr Board und schon sind Sie fertig!

Disclaimer: Dieser Code ist “quick’n’dirty” und hat viel Potential für Refactoring. Zum Beispiel sind die Pin-IDs hartkodiert, ich verwende nicht die tollen und einfachen Features von C++11 wie Range-based for loop und der Geschwindigkeitsalgorithmus wird ziemlich oft die untere Grenze erreichen und kein zufälliges Verhalten zeigen. Ich freue mich über Ihre Verbesserungsvorschläge auf meiner Github discussions Seite.

#include <Arduino.h>

#define MAXLONG 0xFFFFFFFF
#define SPEED_HIGHLIMIT 1000 // 500Hz
#define SPEED_LOWLIMIT 0x1FFF // 20Hz

void calcFlicker(uint32_t randomFlicker);
void writeLed(uint8_t columnCode, uint16_t speed);
uint32_t iRNG = 1;

void setup() 
{
 randomSeed(analogRead(0));
 pinMode(2, OUTPUT);
 pinMode(3, OUTPUT);
 pinMode(4, OUTPUT);
 pinMode(5, OUTPUT);
 pinMode(6, OUTPUT);
 pinMode(7, OUTPUT);
 pinMode(8, OUTPUT);
 pinMode(9, OUTPUT);
 iRNG = 1;
}

void loop() 
{
 iRNG = (iRNG >> 1) ^ (-(iRNG & 1u) & 0xd0000001u);
 calcFlicker(iRNG);
}

/*
 This function takes a 32bit random value,
 and moves this value along a window of an 8bit 
 flicker output value.
*/
void calcFlicker(uint32_t randomFlicker)
{
 uint8_t currentFlicker = (uint8_t)(randomFlicker & 0xFF);
 uint16_t randomSpeed = min(SPEED_LOWLIMIT, (uint16_t)(randomFlicker & SPEED_HIGHLIMIT));
 for(uint8_t i = 0; i < 24; ++i) // 24 because of 32bit length of random, may not run empty
 {
 writeLed(currentFlicker, randomSpeed);
 randomFlicker = randomFlicker >> 1;
 } 
}

/*
 this function outputs a code to an LED column of 8 LEDs
 connected to arduino's pins with a selectable delay.
*/
void writeLed(uint8_t columnCode, uint16_t speed)
{
 digitalWrite(2, columnCode & 0x01);
 digitalWrite(3, columnCode & 0x02);
 digitalWrite(4, columnCode & 0x04);
 digitalWrite(5, columnCode & 0x08);
 digitalWrite(6, columnCode & 0x10);
 digitalWrite(7, columnCode & 0x20);
 digitalWrite(8, columnCode & 0x40);
 digitalWrite(9, columnCode & 0x80);
 delayMicroseconds(speed);
}

Testen

Sobald Sie das Gerät über USB einschalten, sollte die LED-Flackersequenz beginnen. Es sollte sich ein ruhiges Flackern einstellen. Wenn man im Regal einen leeren Platz findet und ein paar Zweige zur Hand hat, könnte das doch ganz schön aussehen, oder? Mit einer Powerbank kann man dieses Lagerfeuer auf dem Steckbrett sogar überall hin mitnehmen. Das war’s, viel Spaß damit!

Zur Hauptseite des Projektes

CNC Teil5 - Makros

Schallbert — Wed, 11 May 2022

Dies ist der fünfte Teil meiner Serie über Portalfräsmaschinen. Er befasst sich mit praktischem Zubehör, welches das Leben als CNC-Bediener erleichtert und zu schnelleren und genaueren Fräsergebnissen führen kann.

Übersicht

In diesem Artikel geht es um Makros für die CNC, mit deren Hilfe sich wiederholende Vorgänge automatisiert werden können. Ich decke sowohl grundlegende als auch anspruchsvollere Makros für mehrere Zwecke wie automatische Z-Nullstellung, Werkzeuglängenmessung oder Werkzeugwechsel ab. Ich führe ein paar G-Code Befehle ein. Die Beschäftigung damit half mir dabei, ein tieferes Verständnis der Funktionsweise zu erarbeiten und damit “Vertrauen” zu meiner Maschine aufzubauen.

Haftungsausschluss

Die folgenden Subroutinen wurden für den RS274 NGC Interpreter geschrieben. Ich habe sie mit EdingCNC validiert, da dies die von mir verwendete CNC-Software ist. Ich habe einige Aspekte von Makro-Dateien abgeleitet, die sowohl Sorotec als auch Eding zusammen mit ihren Maschinen ausliefern.

⚠️ Ich kann für die Funktion des hier beschriebenen Codes auf anderen Maschinen keine Verantwortung übernehmen. Meine Absicht ist lediglich zu erklären wie die Makros funktionieren.

Was ist ein Makro?

Ein Makro oder Unterprogramm ist eine Sammlung von Anweisungen, die für den CNC-Interpreter geschrieben wurden, um Aktionen auszuführen. Sie werden oft verwendet, um wiederkehrende Vorgänge zu automatisieren. Auf meiner Maschine beginnt ein solches Makro mit einem SUB-Befehl und endet mit einem ENDSUB. Makros enthalten oft Verzweigungslogik und G-Code-Befehle, beispielsweise um die Maschine Bewegungen ausführen zu lassen, Parameter abzuspeichern oder Benutzerdialoge anzuzeigen.

Auf meiner Maschine befinden sich alle Makros in einer einzigen Datei namens macro.cnc, die von meiner CNC-Software beim Start eingelesen wird. Einige “Soft-Buttons” der Software rufen direkt Makros aus dieser Datei auf, z.B. für die Referenzfahrt.

Als kleine Einführung öffne ich das Dokument macro.cnc mit einem Texteditor. Ich suche nach Sub user_9 (es sollte eine Routine sein, die nichts Relevantes tut), entferne ihren Inhalt und füge stattdessen MSG "hello world!" ein. Abspeichern, CNC-Software öffnen, die Taste 9 im user menu drücken und Voilà!

Ein einfaches Makro zur Erkennung des Status des Werkzeuglängensensors

Legen wir los und verbinden das neu erworbene Wissen über Makros mit einem nützlichen Beispiel.

Der Werkzeuglängensensor

Ein Werkzeuglängensensor (im Folgenden WZLS) ist ein Zubehörteil, das an einen Eingang der CNC-Maschine angeschlossen wird und bei Berührung (z.B. durch eine Werkzeugspitze) auslöst. Es gibt viele verschiedene Ausführungen, von einem einfachen Mikroschalter mit Gehäuse und Tastmechanismus bis hin zu hochpräzisen induktiven Sensoren aus feingedrehtem Edelstahl mit automatischer Luftspülung um sicherzustellen, dass die Oberfläche des Sensors sauber ist.

Der Werkzeuglängensensor wird entweder am Maschinenbett, auf dem Ablagetisch oder einfach an einer anderen festen Position an der Maschine angebracht. Meiner ist ein sehr einfacher Schalter. Seine Wiederholgenauigkeit ist mit 10µm angegeben.

Makro-Aufgabe

Das Makro soll vor der Messung prüfen, ob der WZLS betriebsbereit ist. Ich teste also, ob der Sensorschalter den Status “nicht ausgelöst” hat. Seine Verdrahtung ist als “normally closed” (NC) ausgeführt. Falls er doch ausgelöst ist (seine Kontakte also offen sind), könnte das Folgendes bedeuten:

Der Sensor klemmt in der ausgelösten Position
Kabelbruch in der Zuleitung zum WZLS
Sensor ist nicht mit der Maschine verbunden

Code: Prüfe Betriebsbereitschaft WZLS

SUB is_sensor_ok
 IF [sensorStatus == triggered] ;# 5068 == 0 (normally closed)
 DLGMSG "Tool length sensor not connected or already triggered - please check"
 IF [dialogButton == 1]
 IF [sensorStatus == triggered]
 ERRMSG "Tool length sensor input still unexpected - aborting"
 ENDIF
 ELSE
 ERRMSG "User abort."
 ENDIF
 ENDIF
ENDSUB

Der Name des Makros lautet is_sensor_ok. Ich prüfe den Sensorstatus und zeige eine Dialogmeldung an, falls hier etwas nicht stimmt. Sobald auf “OK” gedrückt wird, gehe ich davon aus, dass das Problem behoben wurde und versuche es erneut. Wenn er immer noch ausgelöst ist, breche ich die Routine ab.

Dieses Prüf-Makro ist in allen folgenden Abschnitten zu finden.

Benennung von Variablen

Die RS274/NGC-Sprache ist alt. Wirklich alt. Ihre erste Version wurde in den späten 1950er Jahren veröffentlicht. Kein Wunder, dass die Parameter (#1 - #5399 ist der erlaubte Bereich) alle numerisch sind. Sowohl in der Benennung als auch in den Werten, die sie speichern können. Es gibt kein Typsystem (wie Strings, int usw.) und keine praktischen Aliase oder menschenlesbare Namen, die das Verständnis eines Parameters wie sensorStatus erleichtert.

Im Makro auf der Maschine wird stattdessen #5068 erscheinen man muss sich selbst daran erinnern, dass der Hersteller der CNC-Software such auf diese Variable festgelegt hat, um den Status des Werkzeuglängensensors zu kennzeichnen. Und dass sie vom Typ boolean ist mit 0 = nicht ausgelöst und 1 = ausgelöst.

Um den Makrocode so lesbar und verständlich wie möglich zu gestalten, verzichte ich in diesem Artikel auf die Verwendung von numerischen Parameternamen. Eine Übersetzungstabelle ist ganz unten zu finden.

Verwendung des Werkzeuglängensensors zur Ermittlung der Werkstückhöhe (Z=0)

Hiermit kann die Werkstückhöhe automatisch eingemessen und auf der Obefläche abgenullt werden. So entfallen das manuelle Absenken der Z-Achse bis das Werkzeug die Oberfläche leicht ankratzt und dann das Festlegen der Werkstückkoordinaten.

Sobald das Makro programmiert und eingerichtet ist, wird der WZLS möglichst mittig auf dem Werkstück platziert und die Spindel der Maschine mit ein paar Millimeter Luft direkt über diesem in Position gebracht. Dann wird das Makro gestartet. Die Maschine wird nun automatisch ihre Z-Achse langsam absenken, bis der Sensor schaltet. Dann fährt sie sehr langsam zurück, bis der Sensorkontakt wieder geschlossen ist. Dieser Punkt wird dann zur Bestimmung von Z0 herangezogen, welcher dann automatisch gesetzt wird.

Voraussetzungen

Bevor wir das Makro schreiben können, benötigen wir die Z-Position des Werkzeuglängensensors “zTls” zum Zeitpunkt des Umschaltens von “ausgelöst” auf “nicht ausgelöst”. Ich habe meine vorerst (denn das ist nicht sehr genau) mit einem Messschieber gemessen und notiert. Wir brauchen diesen Wert, damit die Maschine ihn beim Ansetzen von der Z-Höhe abziehen kann, um die Position der Werkstückoberfläche zu ermitteln.

Wie man die Messung des Auslösepunktes präziser hinbekommt soll Gegenstand eines eigenen Artikels werden.

Außerdem ist es wichtig zu wissen, wie der Schalter mit der Maschine verbunden ist. Die bevorzugte Art ist “NC”, d.h. der Schalter öffnet sich, wenn er ausgelöst wird: “Ausgelöst = 0”.

Schließlich müssen wir den Vorwärts- und Rückwärtsvorschub des Messtasters festlegen, z.B. Absenken = 100mm/min, Anheben = 10mm/min.

Das Makro enthält auch einen etwas aufwendigeren Teil: Wenn Z0 gemessen werden soll, obwohl die aktuell Werkzeuglänge noch unbekannt ist, macht das keinen Sinn: Bei einem Werkzeugwechsel wäre sie nicht in der Lage, den Nullabgleich auszuführen.

Daher wird in diesem Fall die Werkzeugvermessung zwischengeschoben: die Maschine speichert die aktuelle Position posX, posY vor der Fahrt zum Werkzeuglängensensor in Hilfsvariablen zwischen und führt direkt das Makro get_tool_length aus. Anschließend fährt sie wieder in die Ausgangsposition zurück, um die Vermessung von Z0 nachzuholen.

Das Unterprogramm “Z0 bestimmen”

Nach dem Ausschalten der Spindel senkt das Programm mit dem Befehl G38.2 die Z-Achse der Maschine ab, bis der Fräser Werkzeuglängensensor auslöst (oder bis sie ohne eingelegtes Werkzeug so weit nach unten gefahren ist, dass die Spindelnase den Sensor fast berührt, wo das Makro dann wiederum abbrechen würde, weil es den Sensor nicht gefunden hat). Sobald der Sensor ausgelöst, fährt die Maschine vorsichtig die Z-Achse wieder hoch. Der Punkt der erneuten Freigabe des Sensors durch das Werkzeug wird dann als Koordinaten-Offset für die Z-Achse mit dem Befehl G92 gespeichert.

Code: Werkstücknullpunkt bestimmen

Bevor wir beginnen stellen wir sicher, dass alle Vorbedingungen erfüllt sind:

Die Werkzeuglänge ist bekannt
Der WZLS ist korrekt angeschlossen

SUB measure_workpiece_z0
 IF ![toolLengthStat]
 DLGMSG "WARNING - Please first measure tool length!"
 IF [dialogButton == 1]
 xPosReposition = xPos
 yPosReposition = yPos
 repositionTo = 1
 GOSUB get_tool_length
 ENDIF
 ENDIF

 GOSUB is_sensor_ok ;# Check if tool length sensor status is OK

Programmieren wir nun die eigentliche Routine, indem wir abfragen, ob der Z-Nullabgleich jetzt durchgeführt werden soll. Wenn die CNC im Simulationsmodus läuft (ohne angeschlossene Hardware), wird der Z-Nullabgleich nicht funktionieren. Also müssen wir auch dies überprüfen und den Schritt gegebenenfalls überspringen.

 DLGMSG "Start Z-Zeroing?"
 IF [dialogButton == 1] AND [operatingMode != simulator]
 M5 ;#Switch spindle off
 M9 ;#Switch coolant off
 G53 G38.2 Z[zSpindleTip + 5] F[touch] 
 ;# G38.2 = touch toward probe, stop on contact, flag error on fail
 ;# fail = 5mm before touching spindle tip
 IF [probeOk == 1] ;# #5067 == 1 : G38.2 command success
 G38.2 G91 Z20 F[rev] ;# now reverse slowly to find untrigger point (max. 20mm up)
 G90 ;# back to absolute coordinates
 IF [probeOk == 1] 
 G00 Z[zTouched] ;# #5063 Go to Z-axis's probe point	
 G92 Z[zTls] ;# Set Z-axis's coordinate offset (0) to tool length sensor's height
 G00 Z[zTls + 5] ;# clear sensor
 ELSE
 ERRMSG "Could not locate sensor untrigger point."
 ENDIF 
 ELSE
 DLGMSG "Could not locate sensor trigger point. Retry?" 
 IF [dialogButton == 1] 				
 GOSUB measure_workpiece_z0
 ELSE
 ERRMSG "User abort."
 ENDIF
 ENDIF
ENDSUB

Your browser does not support the video tag.

Ausführen des Makros Z-Nullabgleich auf Zerspanobert

Messung der Werkzeuglänge

Wenn die Maschine die Werkzeuglänge kennt, bevor sie den Z-Nullpunkt misst, muss der Z-Nullpunkt bei anstehenden Werkzeugwechseln während des Auftrags nicht erneut bestimmt werden. Das passende Makro beschreibe ich im Folgenden.

Vorbereitung

Die meisten CNCs leiten ihre aktuellen Positionsdaten durch Zählen der Motorschritte ab, die sie nach Abschluss der Referenzfahrt ausgeführt hat. Um nun die Werkzeuglänge zu vermessen, benötigt sie ein paar einprogrammierte Parameter:

Z-Position der Spindelnase zSpindleTip (berührt Werkzeuglängensensor ohne eingelegtes Werkzeug) damit berechnet werden kann, wie weit das Werkzeug aus der Spindel herausragt
X-Position xPosTls des Werkzeuglängensensors beim Werkzeugwechsel
Y-Position yPosTls des Werkzeuglängensensors bei Werkzeugwechseln
Sicherheitshöhe zSafety (stellt sicher, dass die Spindel auf ihrem Weg zum Werkzeugwechselbereich nicht auf ein Hindernis stößt)
Tastvorschub vorwärts und rückwärts. Wir können ihn aus dem Makro für den Werkstücknullpunkt wiederverwenden.

Die Unterroutine “Werkzeuglänge messen”

Legen wir zunächst fest, was diese Unterroutine tun soll:

Spindel, Kühlmittel etc. anhalten.
Dialog: Bediener soll geschätzte Werkzeuglänge eingeben
Eilgang Z auf Sicherheitshöhe, dann XY zur Position des Werkzeugsensors
Werkzeuglängensensor antasten, ähnlich wie bei der Werkstücknullpunktbestimmung
Werkzeuglänge berechnen
Berechnung der Differenz zwischen der letzten und der aktuellen Werkzeuglänge
Z-Nullpunkt entsprechend aktualisieren
Z im Eilgang wieder auf Sicherheitshöhe bringen

Code: Werkzeug vermessen

SUB get_tool_length
 GOSUB is_sensor_ok ;# Check if tool length sensor status is OK

 DLGMSG "Start tool length measurement? Please enter estimated tool length: " [toolLengthEst]
 IF [dialogButton == 1] AND [operatingMode != simulator]
 IF [toolLengthEst < 0]
 ERRMSG "Error: tool length cannot be negative."
 ENDIF

 IF [zSpindleTip+ toolLengthEst + 10] > [zSafety]
 ERRMSG "Error: tool too long - could collide with sensor."
 ENDIF

 M5 ;# Switch spindle off
 M9 ;# Switch coolant off
 G53 G00 Z[zSafety] ;# Go to safety height (machine coordinates)
 G53 G00 X[xPosTls] Y[xPosTls] ;# Go to tool length sensor
 G53 G00 Z[zSpindleTip + toolLengthEst + 10] ;# Move Z down to 10mm above estimated tool tip

 ;# measure tool length, save results, apply Z-offset if needed
 G53 G38.2 Z[zSpindleTip] F[touch] ;# probe sensor, latest stop point is spindle tip
 IF [probeOk == 1] ;# #5067 == 1 : G38.2 command success
 G38.2 G91 Z20 F[rev] ;# now reverse slowly to find untrigger point
 G90 ;# back to absolute coordinates
 IF [probeOk == 1] 
 toolLength = [zTouched - sTip]
 MSG "Tool length = " toolLength

 IF [toolLengthStat == 1] ;# defaults to 0 on startup
 lastToolLength = currToolLength ;# save last tool's length
 currToolLength = toolLength ;# save current tool's length
 toolLengthDiff = [currToolLength - lastToolLength]	
 G92 Z[zPos - toolLengthDiff] ;# Set Z-axis's coordinate offset (0)
 ELSE
 currToolLength = toolLength ;# save current tool's length
 ENDIF
 toolLengthStat = 1
 GOSUB reposition_spindle
 ELSE
 ERRMSG "Could not locate sensor untrigger point."
 ENDIF
 ELSE
 ERRMSG "Could not locate sensor trigger point."
 ENDIF
 ENDIF
ENDSUB

Your browser does not support the video tag.

Werkzeuglängenmakro auf meiner Maschine

In diesem Video ist die Maschine so konfiguriert, dass sie zum XY-Nullpunkt zurückkehrt, wenn die Werkzeugmessung abgeschlossen ist.

Werkzeugwechsel

Wenn es kein Makro für den Werkzeugwechsel gibt, hält die Maschine ihren Auftrag an. Sobald die Z0-Position des Werkstücks erneut ermittelt wurde (denn die Werkzeuglänge hat sich ja wahrscheinlich geändert), kann der Auftrag fortgesetzt werden.

Diese Aufgabe kann automatisiert werden, indem der Z-Nullpunkt durch Bestimmen der neuen Werkzeuglänge gegenüber der alten neu kalibriert wird.

Voraussetzungen

Ein optionales Flag getToolLength kann das Verhalten des Werkzeugwechsel-Makros konfigurieren - ob die Länge jedes Werkzeugs nach einem Werkzeugwechsel gemessen werden soll oder nicht. Wenn Sie einen automatischen Werkzeugwechsler haben, brauchen Sie dies wahrscheinlich nicht: In diesem Falle ist die Werkzeuglänge in einer Tabelle festgehalten und die Längenkompensation erfolgt ohne Vermessung.

Die folgenden zusätzlichen Parameter werden ebenfalls benötigt:

X-Position xToolChg wo der Werkzeugwechsel stattfindet (bei mir ist es xToolChg = xPosTls)
Y-Position yToolChg, wo der Werkzeugwechsel stattfindet (bei mir ist es yToolChg = yPosTls)
Wiederverwendung von zSafety aus get_tool_length Makro
newToolNumber zur Angabe des angeforderten Werkzeugs aus dem G-Code (oder bei manueller Eingabe)
currToolNumber zur Angabe des “alten” Werkzeugs, das ersetzt werden soll
ToolChangeDone-Hilfsflag, um anzuzeigen, ob ein Werkzeugwechsel bereits stattgefunden hat

Das Makro “Werkzeugwechsel”

Die folgenden Schritte werden von dem Makro ausgeführt, wenn ein Werkzeugwechsel entweder durch den Befehl M06 “Werkzeugwechsel” in der G-Code-Datei eines Jobs oder manuell durch Benutzer ausgelöst wird:

Spindel, Kühlmittel etc. anhalten.
Wenn das angeforderte Werkzeug das aktuelle Werkzeug ist, erscheint ein Dialog mit der Frage, ob es trotzdem gewechselt werden soll.
Z im Eilgang nach oben (zSafety), dann XY auf die Werkzeugwechselposition fahren
Dialog: Angabe des aktuellen Werkzeugs a und Aufforderung, das gewünschte Werkzeug b einzusetzen
Prüfen, ob die Werkzeugwechselkonfiguration die Bestimmung der Werkzeuglänge impliziert. Wenn ja, Makro “get_tool_length” aufrufen.

Code

SUB change_tool
 toolChangeDone = 0
 M5 ;# Switch spindle off
 M9 ;# Switch coolant off

 IF [operatingMode != simulator]
 TCAGuard off ;# tool change area guard: off for tool change

 ;# handle case that tool is already in place
 IF [newToolNumber == currToolNumber]
 DLGMSG "Tool already mounted. Change anyways?"
 IF [dialogButton == 1]
 toolChangeDone = 0
 ELSE
 toolChangeDone = 1
 ENDIF
 ENDIF

 ;# go to tool change position and prompt to change tool
 IF [toolChangeDone == 0]
 G53 G00 Z[zSafety] ;# Go to safety height (machine coordinates)
 G53 G00 X[xToolChg] Y[yToolChg] ;# Go to tool change position
 DLGMSG "Please mount tool now. Old tool number: " [currToolNumber] 
 " New tool number: " [newToolNumber]
 IF [dialogButton == 1]
 IF [newToolNumber > 99] OR [newToolNumber < 0]
 TCAGuard on ;# tool change area guard: on for normal job
 ERRMSG "New tool number implausible."
 ENDIF
 toolChangeDone = 1
 ELSE
 ERRMSG "Tool change aborted."
 ENDIF
 ENDIF

 ;# prompt when complete and optionally call tool length measurement
 IF [toolChangeDone == 1] 
 MSG "Tool change from " [currToolNumber] " to " [newToolNumber] " complete."
 M6 T[newToolNumber]				 ;# set new tool number

 IF [getToolLength == 1] ;# config flag 0 = no, 1 = yes
 GOSUB get_tool_length ;# Measure tool length. Careful: To be called after M6 T !
 ELSE
 GOSUB reposition_spindle
 ENDIF
 ENDIF

 TCAGuard on ;# tool change area guard: on for normal job
 ENDIF
ENDSUB

Repositionieren (auf gespeicherte Koordinaten)

Dieses kurze Makro wird von anderen Unterprogrammen aufgerufen, um die Maschine entweder zu einer gewünschten Position oder zum XY-Werkstücknullpunkt zu fahren. Es kann mit mehreren repositionTo-Flag-Werten erweitert werden, z.B.

0 = keine_Neupositionierung, 1 = benutzerdefinierte_Position, 2 = Werkstücknullpunkt, 3 = Maschinennullpunkt ...

Code

SUB reposition_spindle
 G53 G00 Z[zSafety] ;# Go to safety height (machine coordinates)
 IF [repositionTo == 1]
 G00 X[xPosReposition] Y[yPosReposition] ;# Move back to where requested before
 repositionTo = 0 ;# reset reposition flag and values
 xPosReposition = 0
 yPosReposition = 0
 ELSE
 G00 X0 Y0 ;# Move back to XY zero (workpiece coordinates)
 ENDIF
ENDSUB

Tabelle der Variablen

Typ-Erläuterungen:

protected: Parameter gehört zu festen Befehlen oder Zuständen, die schreibgeschützt sind
reserved : Parameter hat eine feste Verwendung innerhalb meiner CNC-Software
free : Parameter kann frei durch den Programmierer verwendet werden (Ist nach Not-Aus oder Neustart aber zurückgesetzt!)
persisted: Parameter wird im nicht-flüchtigen Speicher abgelegt

Systemparameter

Variable name	Parameter nr.	Type	Comment
xPos	#5001	protected	current CNC position
yPos	#5002	protected	current CNC position
zPos	#5003	protected	current CNC position
currToolNumber	#5008	protected	[1…99]
newToolNumber	#5011	protected	[1…99]
zTouched	#5063	protected	Z where sensor touched
probeOk	#5067	protected	1 = OK
sensorStatus	#5068	protected	1 = triggered
operatingMode	#5397	reserved	1 = simulator
dialogButton	#5398	reserved	1 = OK

Konfig-Parameter

Config-Parameter sind die Parameter, die einmal eingestellt und dann konstant gehalten werden, da sie an die CNC und ihre Geometrie gebunden sind.

Die Volatilität der Parameter hängt stark von der CNC-Softwarelösung ab, die Sie verwenden, und die Anzahl der freien Parameter kann unterschiedlich sein. In meiner Software werden die Variablen im Bereich “#4000 - #4999” beibehalten, während alle anderen freien und reservierten Parameter flüchtig und/oder skaliert sind.

Variable name	Parameter nr.	Type	Comment
triggered	#4400	free, persisted	1 = normally open
currToolLength	#4501	free, persisted	[mm]
lastToolLength	#4502	free, persisted	[mm]
zSafety	#4506	free, persisted	Z position for move
xPosTls	#4507	free, persisted	tls position
xPosTls	#4508	free, persisted	tls position
zSpindleTip	#4509	free, persisted	Z zpindle on tls
zTls	#4510	free, persisted	TLS height [mm]
toolLengthEst	#4511	free, persisted	[mm]
touch	#4512	free, persisted	touch feed [mm/min]
rev	#4513	free, persisted	reverse feed [mm/min]
getToolLength	#4520	free, persisted	Flag, 1 = Yes
xToolChg	#4521	free, persisted	tool change position
yToolChg	#4522	free, persisted	tool change position

Flag-Parameter

Freie Parameter können nach Belieben verwendet werden. Es muss jedoch darauf geachtet werden, dass nicht versehentlich eine bestehende Systemvariable wiederverwendet oder überschrieben wird.

Variable name	Parameter nr.	Type	Comment
toolLengthStat	#3501	free	1 = measured
toolLengthDiff	#3502	free	[mm]
toolChangeDone	#5015	free	1 = Yes
repositionTo	#5020	free	Flag, 1 = Yes
xPosReposition	#5021	free	reposition flag
yPosReposition	#5022	free	reposition flag
toolLength	#5024	free	[mm]

PS: Damit die obigen Code-Beispiele ordentlich angezeigt werden, habe ich fürs Markup die Sprachinterpretation ruby verwendet. Hier kommt die farbige Syntax-Markierung am besten überein mit der Logik des NGC-interpreters.

Tonuino - alternative Firmware

Schallbert — Mon, 01 Jan 0001

Projekt-Steckbrief

Difficulty: Experte 5/5
Kosten: 0€
Zeitaufwand: ~400h

Galerie

Die alternative Tonuino-Firmware im Einsatz.

NFC-Tags sind Vögel, die zum Abspielen ins Häuschen gesetzt werden

Anwendungsbeispiel mit Microcontroller unter Verwendung meiner ClickEncoder-Bibliothek

Anwendungsbeispiel mit Arduino in einem Gitarrenverstärker

Gesteuert wird der Player in diesem Fall mit drei Tasten.

In disem Projekt entstand eine Software für eine NFC-Tag gesteuerte Jukebox. Sie ist für das Arduino-Framework optimiert und verbindet die Hardware eines Mp3-Players (mit SD-Karte), ein NFC-Tag-Lesegerät und ein paar Bedienelemente.

Ein NFC-Tag wird mit einem Ordner auf der SD-Karte verknüpft, welcher Audiodateien enthält. Das Tag speichert auch Informationen über den gewünschten Wiedergabemodus für dieses Album, z. B. “Zufällig”. Sobald ein verknüpfter Tag in die Nähe der Jukebox gebracht wird, wird der konfigurierte Ordner im entsprechenden Wiedergabemodus abgespielt. Mit den Bedienelementen kann der Titel ausgewählt, die Lautstärke geändert und sogar durch ein Sprachmenü navigiert werden, was das Löschen, Verknüpfen und Konfigurieren eines Tags sowie Sperren/Entsperren der Eingabetasten ermöglicht.

Motivation

Idee und fantastische Umsetzung hatte ich auf Thorsten Voß’ blog gesehen. Es begann mit der Funktionalität (encoder support), die ich hinzufügen wollte. Leider war der ursprüngliche Code ein zusammenhängender Block mit mehreren tausend Zeilen Code und für mich schlechter Lesbarkeit, so dass es mir schwer fiel, meine Änderungen einzubringen.

Also habe ich den Code von Grund auf neu geschrieben, um eine bessere Struktur, Lesbarkeit, Wartbarkeit und Erweiterbarkeit zu erreichen. Parallel dazu las ich einige Bücher über objektorientiertes Design in C++, Clean Code und Software Design Patterns und wandte einige davon dort an, wo ich sie für geeignet hielt. Auf diese Weise konnte ich sowohl die Modularität als auch die Lesbarkeit des Codes verbessern und habe außerdem gelernt, wie man Code in einem “größeren” Projekt schreibt.

Schwierigkeiten

Dies war mein erstes eigenes C++-Projekt, und vielleicht war es für den Anfang ein wenig zu groß. All die für mich neuen Konzepte, das Schreiben an eine Schnittstelle, die erstmalige Verwendung von Platformio als IDE, die Verwendung des googletest unit test framework, die Einsatz von Coding Patterns wie [factory](https://www. oodesign.com/factory-pattern.html) oder Dependency Injection kostete mich Abend um Abend über fast ein Jahr, bis ich dieses Projekt schließlich fertigstellen konnte. Und es gibt immer noch etwas zu überarbeiten und zu verbessern.

Übersicht

Unit-Test-Suite mit über 250 Testfällen
Serielle Debug-Ausgabe konfigurierbar
Lose gekoppelte, objektorientierte Architektur in C++
Einzelne Module mit klaren Aufgaben, skalierbar und leicht zugänglich für zukünftige Funktionen
benutzerdefinierte Hardware-Abstraktionsschicht; der größte Teil des Codes sollte ohne Änderungen auf andere MCUs portierbar sein
eigenes Dependency Injection Framework (Loader Klasse)

Funktionen

Konfigurierbare Benutzereingabe (Tasten oder Encoder)
Auto-Poweroff, wenn für eine konfigurierbare Zeit keine Taste gedrückt wird
Einschalten durch Drücken der “Play”-Taste
Autoplay-Funktion
Status-Led-Funktion
Sperren/Entsperren der Benutzereingabe
Mehrere Wiedergabemodi [Album, Zufall, Speichern des Titelfortschritts, Nur ein Titel] pro Nfc-Tag verfügbar
Sprachmenüs zum Verknüpfen oder Löschen von Nfc-Tags
Optimiert für Batterieanwendungen (z.B. Powerbank) unter Verwendung von Ruhezuständen
Niedriger Stromverbrauch @5V: ~40mA im Leerlauf, ~75mA bei mittlerer Lautstärke
Konfigurationsdatei für Startlautstärke, Einschlaf-Timer etc.
Automatische Wiederherstellung bei Eingabeaufforderung, die niemand bedient
Sprachansagen für die häufigsten Fehlermeldungen

Nicht enthaltene Funktionen

Keine Erkennung des Ladezustands der Powerbank
Kein Konfigurationsmenü (Startlautstärke, Dauer des Einschlaf-Timers, Standby-Dauer usw.)
…

Dokumentation

Das Projekt ist für das Arduino Framework erstellt - getestet auf einem Arduino nano Board - unter Verwendung der PlatformIO IDE. Die folgenden Abschnitte zeigen das Design.

Projekt Modulübersicht

Ordnername in `/lib`	Zweck
Arduino	minimalistische hardwarenahe Implementierungen, nicht Unit-testbar
Arduino_HardwareAbstraction	Hardware-Abstraktion, um Portabilität und Testen zu ermöglichen
Config	Systemkonfigurationsparameter
Folder	Geschäftslogik für Wiedergabeliste und Wiedergabemodus
Loader	Dependency Injection Framework
MessageHandler	Systemnachrichten und Debug-Framework
Mp3	Mp3-Steuerung (Status, Ordner, Sprachausgabe, Anzeigen)
Nfc	Tag-Steuerung (Status, Lesen, Schreiben, Löschen)
PowerManager	Steuerung von Status-LED und Ruhezustand abhängig vom Systemstatus
Tonuino	Haupt-Task-Scheduler
UserInput	Verarbeitung von Tasten- oder Encoder-Eingaben
Utilities	Timer, Led-Steuerung, Pin-Steuerung
VoiceMenu	Geschäftslogik für das Menü Link / Löschen / Konfiguration

Verwendete externe Bibliotheken

Automatische Installation durch Platformios “Library Dependency Finder” beim erstem Kompiliervorgang

Klassendiagramme

Klassendiagramme wären zu viel nicht-automatisierte Arbeit gewesen. Stattdessen habe ich das hier vorbereitet:

Software-Modulübersicht

Sie sollte ein genaues Verständnis dafür vermitteln, wie die Softwaremodule zusammenwirken und welche APIs die Module anbieten.

Los geht’s!

Zuerst muss mein repository, geklont werden - entweder per git clone, Download als zip-Datei oder per https. Das README.md Dokument bietet einen leichten Einstieg. Ich empfehle die Verwendung von PlatformIO für dieses Projekt. In den folgenden Abschnitten sind die Teilfunktionen des Programms erläutert, und wie deren korrekte Funktion sichergestellt wird.

Testen

Unit-Tests

Unit-Tests wurden mit dem gtest C++ Unit-Test-Framework geschrieben. Sie befinden sich im Ordner test/desktop. Zu beachten ist, dass googletest die Installation von gcc mit einigen Bibliotheken voraussetzt. Die Anleitung dazu findet man in einem meiner anderen Projekte. Sobald diese Voraussetzungen erfüllt sind und ein einfacher ASSERT_TRUE(false);-Test mit der gtest-Umgebung erwartungsgemäß fehlschlägt, können die Unit-Tests des Projekts erstellt und mit pio test -e desktop -f desktop, in der PlatformIO CLI (Terminal) ausgeführt werden.

Akzeptanztests

Obwohl diese Tests automatisiert werden könnten, ist es viel einfacher, diese Tests von Hand durchzuführen, nachdem der Mikrocontroller programmiert und alle elektronischen Komponenten zusammengesteckt wurden. Jede Zeile in den folgenden Tabellen ist ein eigenständiger Testfall. Die Testsuiten (“Überschrift Name”) haben eine System Pre: Eigenschaft, die vor der Ausführung der einzelnen Testfälle wiederhergestellt werden muss. Wenn die Erwartungsklausel erfüllt ist, ist der Test BESTANDEN. Ich habe die Tests auf Englisch belassen, weil sie recht eng mit dem Code korrespondieren.

Switching ON

System Pre: System is OFF

Action	Expectation
press Play/Pause button	LED flashes slowly?
press Play/pause button	Welcome prompt plays?

Switching OFF

System Pre: System is ON

Action	Expectation
Playback on pause, no button input	System switches off after a time?
System shutdown	Farewell prompt plays?
System shutdown	LED switched off?

Play Help Prompt

System Pre: System is ON

Action	Expectation
Long press Play/Pause button	Help prompt plays?
Help prompt playing	Can be interrupted with any button press?

Behavior without Tag

System Pre: System is ON, no Tag present

Action	Expectation
press Play/Pause button	prompts “couldn’t find track” error?
press Next button	prompts “couldn’t find track” error?
press Prev button	prompts “couldn’t find track” error?
doubleclick Play/Pause button	Delete Menu prompt played?

Behavior with Tag

System Pre: System is ON, linked Tag available

Precondition	Action	Expectation
no Tag placed	place known Tag	starts Playback of correct Folder?
active playback	press Next button	plays next track?
active playback	press Next button	next track in accordance with selected playMode of Folder?
active playback	long press Next button	increases volume?
active playback	press Prev button	plays previous track?
active playback	press Prev button	previous track in accordance with selected playMode of Folder?
active playback	long press Prev button	decreases volume?
active playback	press Play/Pause button	pauses track?
paused playback	press Play/Pause button	resumes track?
active playback	doubleclick Play/Pause button	Lock prompt played?
active playback	doubleclick Play/Pause button	Playback resumes after Lock prompt played?
active playback	doubleclick Play/Pause button	locks button input?
locked button input	doubleclick Play/Pause button	Unlock prompt played?
locked button input	doubleclick Play/Pause button	Playback resumes after Unlock prompt played?
locked button input	doubleclick Play/Pause button	unlocks button input?
paused playback	doubleclick Play/Pause button	Playback resumes after Lock prompt played?

Behavior with unlinked Tag

System Pre: System is ON

Action	Expectation
place unlinked Tag	plays LinkMenu Prompt?
navigate through LinkMenu	plays Configuration Success Prompt?
place Tag again	plays linked folder?

Hardware

Materialliste

Ich habe versucht mit möglichst wenigen Einzelteilen auszukommen. Für ein Projekt dieser Größe ist die Liste denke ich recht kurz geblieben.

Menge	Artikel	Zweck
1	Arduino (z.B. Nano)	Gehirn
1	Dfplayer Mini Mp3 Player	Mund
1	Micro SD Karte	Speicher
1	MFRC522 Nfc-Leser	Psi-Sense
1	Bistabiles Relais 5V, z.B. HFE20	Kaffee - kein Schlaf
2	Dioden z.B. 1n4007	Venenklappe
1	PNP-Transistor z. B. BC327	Kaffeemaschinenschalter
2	Widerstände 1k	Blutstromaufbereiter
1	Widerstand 220	Blinkstärke dimmen
1	LED, Farbe nach Wahl	blinken
1	Powerbank/ 5V Versorgung	Lebensmittel
3	Drucktasten, z.B. Cherry MX Tasten	Drucksensoren
1	Lautsprecher, z.B. 5W@4Ohms	Stimmbänder
1	USB-A-Stecker	Strohhalm
1	Gehäuse	Körper

Zusätzliche Bauteile und Tipps

Überbrückungsdrähte, Platine, Buchsen und Verbrauchsmaterial nach eigenem Ermessen Wie beim “Original”-Projekt; alternativ einen Drehgeber anstelle der Drucktasten kaufen und das Projekt so konfigurieren, dass er statt der Taster ausgelesen wird. Da das System für den Batteriebetrieb optimiert ist, nehmen Sie ein bi-stabiles Relais oder einen JFET-Transistor (mit niedriger Gate-Spannung und niedrigem Source-Drain-Spannungsabfall) für die KeepAlive-Funktionalität, die den zusätzlichen Strom durch die ständig eingeschalteten Relaisspulen vermeidet. Eine billige Powerbank reicht für viele Stunden Betrieb. Alternativ können z.B. 3xAA-Batterien verwendet werden - allerdings macht der Dfmini-Player ordentlich Lärm, wenn die Spannung zu sehr einbricht. Er kann sogar bei wiederholten Neustarts durch Stromstöße zerstört werden, also Vorsicht bei nachlassender Akkuladung.

Coding on Schallberts Blog

Docker-Images automatisch updaten

Wozu automatische Updates?

Docker image update mit Watchtower

Lösung per Skript

Kompliziert: docker pull, Abgleich mit vorhandenen Images, bei Bedarf einspielen

Einfach: Alles in einem Kommando per Option mitgeben

Eintrag für cron

Welche Version wurde installiert?

Meldung bei Update

Werkzeugvermessung automatisieren

Frage: Wie berechnet das Makro die Werkzeuglänge?

Antwort:

Frage: Wie berechne ich die Werkstückhöhe nach einer Werkzeugvermessung?

Antwort: Mehrere Lösungswege

Lösung #3: Koordinatensystem verschieben

Verschiebung Werkstücknullpunkt vs. Werkstückkoordinatensystem

Rahmenbedingungen

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

Den Server absichern

Motivation

Unerwünschte Besucher aussperren

fail2ban

fail2ban installieren

fail2ban Beispiel

Was (noch) nicht funktioniert: Gitea & fail2ban

Regelmäßige Backups

Borgmatic in Docker installieren

Borgmatic konfigurieren

Borgmatic Funktionstest

Ein Backup ist nur ein Backup…

Was (noch) nicht funktioniert: Borgmatic & docker-compose down

🗸 Gitea Actions Teil2 - Jekyll-Dockerimage

Die Vorgeschichte

“Set up job”

bundle install

act_runner: Kein Schreibzugriff auf Gemfile.lock

Kompliziert: `docker pull`, Abgleich mit vorhandenen Images, bei Bedarf einspielen

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