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

PHP2shell: Kritische Sicherheitslücken

Schallbert — Wed, 21 Oct 2026

Schritt 1 Erkennen: Wir haben ein Problem.

TLDR: PHP hat ganz aktuell zwei kritische Schwachstellen, die Remote Code Execution ermöglichen. Ihre IDs: CVE-2026-109618 und CVE-2026-109619. Da ihre Ursachen nicht im Frontend sondern in der Engine stecken, hilft nur ein Update auf PHP 8.5.12, 8.4.27, 8.3.36, oder 8.2.35.

“PHP nutze ich nicht auf meiner Website”, denke ich, als ich heute Vormittag die folgende Nachricht erhalte:

“Hi, kurzer Hinweis: Gegebenenfalls […] alles was php nutzt, erstmal abklemmen, […] Patch kommt später heute.”

Oder bin ich doch betroffen…? Immerhin nutze ich eine managed Nextcloud-Instanz, und Nextcloud ist doch u.A. in PHP geschrieben…? Während ich diese Zeilen schreibe, wird ein Fix für Nextcloud verfügbar. Alles muss also sehr schnell gehen. Heute werden unter Garantie viele Überstunden gemacht.

Status 21.10.2026, 10:30 MESZ

Spulen wir zehn Stunden zurück. Es gibt noch keinen Fix. Die Information über die CVEs wurde geleakt und ist jetzt selbst bereits ein paar Stunden alt. Laut Wikipedia nutzen 69% aller Websites PHP. Das Ausnutzen einer so hochkritischen Lücke (Score 9.2) bei einer derart weitverbreiteten Technologie hat erwartbar massive Auswirkungen. Entsprechend nervös ist “das Internet”.

“[…] organisations should consider isolating internet-facing applications from public networks until a fix is applied and verified. CERT-EU, pulled 21.10.2026, 10:40

Interessant, die Empfehlung ist also ernsthaft “erstmal vom Netz nehmen”.

Schritt 2 Sofortmaßnahmen: Nextcloud vom Netz trennen

Um einem möglichen Angriff zuvor zu kommen versuche ich folglich, meine Instanz vom Netz zu nehmen. Dafür logge ich mich bei meinem Hoster ein, wechsle auf das Tab “Einstellungen”, und klicke auf den Reiter ownCloud Console. Dies ist Nextclouds command-line interface.

Dort muss ich feststellen, dass kein Befehl zum Abschalten oder de-publishing zur Verfügung steht. Also wähle ich den Nächstbesten:

occ maintenance:mode --on

Ich versetze meine Instanz also in den Wartungsmodus. Dies verhindert neue Logins und friert die Datenbank ein. Anschließend lese ich mich ein wenig in die CVEs ein um herauszufinden, ob mein Schritt genügt.

Tut er wohl nicht.

In verschiedenen Foren und auf HackerNews erfahre ich, dass eine nicht authentisierte Anfrage bereits den Angriff auslösen kann, bevor überhaupt PHP-Code auf der Serverseite ausgeführt wird.

Es ist also egal, in welchen Zustand ich meine Instanz versetze - solange sie am Netz ist, bleibt sie angreifbar.

Schritt 3 Vorläufige Eindämmung: Nextcloud-Instanz deaktivieren lassen

Ich finde auch mit Hilfe diverser Online-Suchanfragen keinen Weg, meine mangaged-Instanz abzuschalten. Ich überlege kurz, die Namensauflösung und das DNS-Routing zu killen. Mir wird aber schnell klar: Bis sich das durchpropagiert, ist der Fix längst draußen.

Status 21.10.2026 11:43 MESZ

Ich schreibe also ein Support-Ticket an meinen Hoster mit der Bitte um Hilfe beim Herunternehmen meiner Instanz.

Status 21.10.2026 12:01 MESZ

Ich erhalte eine Mail vom Hoster!

Tatsache, ich kann die Instanz nicht mehr erreichen und erhalte eine ERR_CERT_COMMON_NAME_INVALID-Meldung. Klicke ich diese weg, erscheint REQUESTED PAGE LOCKED. Gute Arbeit. Die Reaktionszeit meines Anbieters inlusive Rückmeldung an den Kunden betrug 18min.

Nun wechsle ich den Modus vom Akteur zum Beobachter. Ich sehe erste Exploit-Versuche (oder zumindest Beteuerungen davon) im Web und muss an eine Folie eines Vortrages denken (Zeitstempel 11:24), den ich vor kurzem gesehen habe: Security in the LLM age.

Dort zeigt ein Linux-Kernel Sachverständiger, dass wir in 2026 im Schnitt sieben Tage vor einem Patch in betroffener Software bereits Exploits in freier Wildbahn sehen.

discover --> disclose --> patch --> deploy

Diese traditionelle Ereigniskette funktioniert nur bei “langsamen” Angreifern gut. Wir benötigen etwas, um wieder vor die Lage zu kommen.

Schritt 4 Beobachten der Situation: Verfügbarkeit des Patches, Einspielen erster Betreiber

Laut Hackernews wird der Patch um etwa 16:00 MESZ verfügbar. Ich besorge mir den RSS-Feed meines Hosters und warte auf Meldung.

Status 21.10.2026 14:20 MESZ

Auch das Bundesamt für Sicherheit in der Informationstechnik hat einen BSI-IT-Sicherheitshinweis herausgegeben, wo mit der “Kritikalität 3/Orange” vor der Lücke gewarnt und folgendes angemerkt wird:

“Der Patch für die Schwachstelle ist heute 16 Uhr deutscher Zeit (14:00 UTC) angekündigt und sollte unverzüglich zu diesem Zeitpunkt installiert werden.” - BSI, 21.10.2026

Status 21.10.2026 16:34 MESZ

Mein Hoster meldet, dass die Patches nun verfügbar seien und mit der Implementierung begonnen würde. Betroffen sind nicht nur die Nextcloud-Instanzen, sondern auch seine komplette Administrationsoberfläche sowie sein Webmailer.

Status 21.10.2026 19:52 MESZ

Mein Hoster meldet Vollzug für die von ihm betriebenen Webhosting-Angebote und Managed Servers.

Status 21.10.2026 22:40 MESZ

Die Hetzner-Anwendung KonsoleH, über die ich meine Nextcloud-Instanz verwalte, ist down.

Status 21.10.2026 23:00 MESZ

KonsoleH ist wieder live (und gepatcht).

Schritt 5 Erkenntnis und Schlussfolgerung

Was lerne ich aus den Ereignissen dieses turbulenten Tages? Wie gehe ich in Zukunft mit Sicherheitslücken um? Und wie erkenne ich überhaupt, dass ein Problem vorliegt?

Nicht nur der Service als Ganzes ist angreifbar sondern auch seine Komponenten. –> Kenne alle Komponenten und achte auf Schwachstellen und Patches!
Die Gegenspieler sind (durch LLMs) unglaublich schnell geworden. –> Rechne mit Exploit vor Patch-Verfügbarkeit!

Eine Liste geeigneter Quellen für Verwundbarkeiten, Neuigkeiten und Patches stelle ich mir gerade zusammen. Sobald die Liste stabil ist, werde ich darüber berichten.

Schritt 6 Aktionen

Sensible Daten wenn möglich aus dem Netz nehmen. Gedankengang: Was wäre, wenn das weg kommt? Reicht Verfügbarkeit im LAN/Intranet?
Besseres Monitoring und Abuse detection sind nur konsequent: Früh erkennen, früh sperren, früh melden, früh abschalten, sofort patchen.
Standardbezugsquellen für Informationen zu verwendeter Software besorgen. CVE-List-Scanner bauen? HackerNews-Filter?

Nachtrag: 22.10.2026 09:30 MESZ

Der Hoster hat meine Nextcloud-Instanz gepatcht und wieder online genommen. Alle Systeme normal. Es gibt nun auch einen Wikipedia-Eintrag zum Thema, der sehr aktuell gehalten wird.

Schritt 7 Erste Reflektion

Nun sind ein paar Tage ins Land gegangen, seitdem die beiden Sicherheitslücken öffentlichkeiswirksam bekanntgemacht und Patches bereitgestellt wurden. Werfen wir mal einen Blick in die Netzlandschaft.

Status 24.10.2026 16:30 MESZ

Es gibt inzwischen viele, viele Machbarkeitsnachweise (PoC, Proof of Concept) für und über die Ausnutzung der PHP-Sicherheitslücken, allem voran auf der Plattform Github.

Ich selbst bin leider auf dem Themenfeld nicht sachkundig und muss mich auf die Einschätzung anderer verlassen, was Qualität dieser PoCs angeht, wie die es um die Ausnutzbarkeit in der freien Wildbahn wirklich bestellt ist und was die Hintergründe dazu betrifft, dass ausgerechnet diese Lücke medial so starke Resonanz zu erfahren scheint.

Im Allgemeinen gilt selbstverständlich “Erst patchen, dann nachfragen”. So habe ich es ja auch gemacht. Wenn ich noch einmal Felix von Leitner zitieren darf:

“Eine der Lektionen aus 20 Jahren Arbeit im Security-Umfeld ist, dass wenn einer behauptet, es gibt einen Bug, und der andere behauptet, der sei aber nicht exploitbar, dass sich dann im Nachhinein so gut wie immer raustellt, dass der doch exploitbar war.” - Feliks von Leitner aka Fefe, 12.April 2014, abgerufen am 24.10.2026

Zur Ausnutzbarkeit schreibt die sich selbst als Bedrohungsaufklärungsseite “Threat intelligence” bezeichnende flare.io, dass die meisten PoCs für PHP2shell nur in der Laborumgebung funktionierten. Auf echte Ziele seien sie kaum anwendbar - endweder, weil Betriebsinterna über die angegriffene Systeme erforderlich seien, weil sie andere Schwachstellen wie die Abschaltung von Speicherrandomisierung voraussetzen, oder weil die PoCs selbst “AI-Slop” darstellten: schlecht oder kaum validierte, mieserabel geschriebene Software, die mehr verspreche als sie halte.

Ähnlich äußert sich eliastaylor:

“There isn’t an easy exploit for this PHP vulnerability.” - https://eliastaylor.com/noexploit/, abgerufen am 24.10.2026

Sein Argument ist knapp zehn Stunden nach Veröffentlichung von Angriffsvektor und Patch, dass

keiner der Exploit-PoCs funktioniert, nicht einmal bei einer Standardinstallation und -Konfiguration von Pre-Patch-PHP
die beiden CVEs weit weniger kritisch sind als andere Sicherheitslücken der Geschichte (Heartbleed bei Open SSL wird exemplarisch genannt)
die Exploits alle nicht von echten Leuten handgeschrieben, sondern mit Hilfe von LLMs generiert seien

Der Kern der Argumentation geht dahin, dass Leute ihre Denkarbeit an Sprachmodelle abgäben und selbst gar nicht mehr prüften, ob das System tut was es sagt; geschweige denn den vom System geschriebenen Code läsen, verstünden und verbesserten. Bösartige Botnets würden noch immer von Menschen handgeschrieben, und das brauche seine Zeit, wenn die Lücken nicht offensichtlich und trivial auszunutzen seien.

Als kleine Übung für eine eigene Einschätzung der Lage empfehle ich die Lektüre der “Issue”-Diskussionen, die bei vielen PHP2Shell-PoCs auf Github öffentlich bereitstehen.

Das Große Medienecho hat aber auch etwas Gutes: Die Welt patcht anscheinend schnell. Ich habe mir die Resonanz auf diversen Foren, deutschen und internationalen, überflogen: Überall treiben Menschen ihre Hoster mit Patches vor sich her, diskutieren miteinander die Auswirkungen und welche betroffenen Anbieter bereits Updates herausgebacht haben.

Bleibt die Frage offen, wem das Ganze nützt. Ich habe schon ein paar Vermutungen. Für Schlussfolgerungen und meine Urteilsbildung ist es allderings noch zu früh.

Status 27.10.2026 17:00 MESZ

Die Sicherheitslücke gilt offiziell bestätigt als ausgenutzt.

Schritt 8 Beobachtungen analysieren und Informationskanäle justieren

Ich lege den Fokus nun auf Berichte zur Ausnutzung der Sicherheitslücken. Die Menge an POCs ist für Einzelpersonen unüberschaubar geworden. Erste Privatpersonen und Firmen wie Cloudflare haben begonnen, ein Capture The Flag auszuloben: Sie stellen absichtlich angreifbare PHP-Instanzen online und fordern auf, sie zu knacken und dies zu beweisen.

Ein sehr kluger Schritt, um die Spreu vom Weizen zu trennen. Auf diese Weise müssen die Leute ihre POCs gegen Sparringspartner ins Feld führen, die ihren Stack nicht offenlegen. Als zusätzliche Schwierigkeit fordern einige Anbieter auf, dass vorher außerdem andere ihrer Standard-Abwehrmechanismen wie Web Application Firewalls überwunden werden müssen. Schafft es ein POC hindurch, kann er als als unter realistischen Bedingungen durchgeführte Schwachstellenausnutzung gelten.

Den POC verstehen

Ich habe (dank an eliastaylor) den POC gefunden, welcher die “StealMyBitcoin” PHP2Shell-CTF gelöst hat. Interessant sind sowohl die Kommentare in der Python-Datei über den Mechanismus des Exploits als auch die Diskussion auf Github zu Modellvariante, Prompt und Konfiguration des verwendeten LLM.

Ich verstehe die Quellen und Kommentare rund um diesen POC so, dass er die Probleme der vorigen Versuche elegant löst:

PHP beim Multipart-Upload effektiv in die Speicherklemme bringen: Anstatt tausende Anfragen in kürzester Zeit zu senden (und zu hoffen, dass er den “richtigen” Worker-Thread trifft), verwendet diese Attacke “deeply nested field names”¹, welche die Payload gering, jedoch den Speicheraufwand mit nur einer Anfrage serverseitig explodieren lassen.

Dies geht gegen die Lücke CVE-2026-109618 “out-of-memory handling can interrupt PHP while internal request data is only partially initialized. Request cleanup may then treat the invalid data as valid”. Ziel des heap_consumer ist es nun, die herumliegenden, durch den Speicherüberlauf abgelaufene Daten zu manipulieren.

ASLR, randomisiertes Ablegen im Speicher umgehen: Anstatt ASLR im Feld zu ignorieren (oder in der Laborumgebung schlicht abzuschalten) müssen Speicherüberlauf, Manipulation und erneute Anfrage zum Einlesen der manipulierten Daten zwingend in derselben Session und auf demselben, überlasteten Worker geschehen². Ansonsten ist der betroffene Speicherbereich kaum wiederzufinden und wird irgendwann durch das System, welches den gestoppten Worker entdeckt, zurückgesetzt. Daher muss der Exploit den Schadcode bereits platziert haben, wenn PHP den zugehörigen Destruktor aufruft und damit schließlich die RCE ausführt.

Dies geht dann gegen die Zweite CVE im Bunde: CVE-2026-109619 “request-owned internal state can survive after its backing memory has been freed. A later request handled by the same worker may use that stale state before normal initialization resets it.”

Wäre jetzt cool hierzu mal eine PHP-Engine-Sachverständige zu hören :)

Damit steht auch der dunklen Seite in der Breite ein Exploit zur Verfügung, der bei “einfachen Zielen” ohne Härtung eine (automatisierte) Ausnutzung machbar erscheinen lässt.

Härtung

Lösen kann das Problem nur der Patch. Folgende Härtungsmaßnahmen können gegen diesen speziellen Angriffsvektor zumindest den Widerstand erhöhen:

Das Kommando PHP_SESSION_UPLOAD_PROGRESS, durch den der Angriff durchgeführt wird, gar nicht erst anbieten oder aber keine Anfragen in sehr kurzer Abfolge, in derselben Session, oder von derselben Maschine zulassen.
Die Anzahl Worker auf Maximum drehen, auch wenn dies auf die Leistung der Maschine geht. Dies macht das Wiedereinfangen und Ausnutzen desjenigen Workers schwieriger, welcher zuvor korrumpiert wurde.

Später am selben Tag

The Hacker News bestätigt die Ausnutzung und zählt betroffene Firmen bzw. Großkonzerne und Lieferanten auf. Der Tenor: Patchen, patchen, patchen!

Status 28.10.2026 21:30 MESZ

Cloudflare hat inzwischen neue Firewall-Regeln für ihre WAF veröffentlicht, die Angreifende schon vor Erreichen der Zielserver abfangen soll. Hackernews berichtet über konkrete Vorfälle mit ersten Schäden. Threat intelligence Firmen bestätigen dies.

Zum Abrunden des Status hier noch eine nette Sammlungsseite mit Informationen über x-2-shell-Schwachstellen.

Passwortmanager mit Security Keys verwenden

Schallbert — Sun, 18 Oct 2026

Der Passwortmanager

Das Netz ist voll mit verschiedenen Lösungen zum Passwortmanagement. Das ist Nachvollziehbar, denn wir haben immer mehr Accounts und niemand merkt sich eine dreistellige Anzahl an Passwörtern freiwillig. Kommen wir also gleich zur Sache:

Ich habe mir aus dem ganzen Wust drei Passwortmanager nach meinen Kriterien (Sicher, komfortabel, quelloffen, selbstverwaltbar) angesehen und wollte hieraus eine Wahl treffen:

Firefox password manager (Online/Offline)
Vaultwarden (Online)
KeePassXC/KeePassDX (Offline)

Kein Firefox Password manager

Firefox schied aus, da ich zum Entsperren meinen Hardware Security Key verwenden und mir kein langes Hauptpasswort merken möchte. Für den Einsatz von Firefox als Passwortmanager sprachen hingegen die sehr einfache Verwendung, das automatische Ausfüllen von Passwortfeldern und die Möglichkeit der Synchronisation, wenn auch über eine fremde Infrastruktur.

Kein Vaultwarden

Vaultwarden hatte ich lange im Visier. Es benötigt für den Betrieb im lokalen Netzwerk viele Vorbedingungen und Software drum herum, Stichworte HTTPS im LAN, ACME-Challenge. Daher ist im LAN ein eigener kleiner Rechner vorzusehen und idealerweise verfügt man sogar über einen virtuellen privaten Server (VPS), der den HTTPS-Verkehr terminieren kann.

Dafür unterstützt Vaultwarden dann sogar die super bequeme Anmeldung per Passkey und kann die Passwortdatenbank zwischen allen Geräten im Netzwerk synchronisieren.

Doch am Ende scheute ich die aufwendige Einrichtung und die neuen Abhängigkeiten und Softwarepakete, die ich alle hätte zusätzlich warten müssen.

KeePassXC

Ich habe mit verschiedenen Varianten von KeePass herumgespielt und mich am Ende für KeePassXC entschieden. Das Gesamtpaket fühlt sich einfach rund und modern an, ich kann die Software betriebssystemunabhängig nutzen und die benötigten Erweiterungen zur Verwendung mit HSKs sind auch gleich dabei.

Einrichtung von KeePassXC mit einem HSK

KeePass verwendet das keyed-hash message authentication code oder HMAC-Verfahren zum Entsperren der Passwortdatenbank unter Verwendung von Hardware Security Keys. Es basiert auf einem gemeinsamen geheimen Schlüssel, der bei beiden Parteien vorliegen muss, aber nicht zwischen den Parteien ausgetauscht wird.

Üblicherweise erstellt man den geheimen Schlüssel auf dem Hardware Security Key und kopiert ihn dann in die Eingabemaske von KeePassXC - aber der Reihe nach, denn der Vorgang hängt ein wenig vom verwendeten HSK ab.

Yubikey

Yubico hat eine Anleitung eigens für die Verwendung mit KeePass vorbereitet. Ein Yubikey hat zwei variabel verwendbare Slots, welche verschiedene kryptografische Funktionen unterstützen. In der Funktionsauswahl ist Challenge-response: program a challenge-response credential anzuwählen. Anschließend erzeugt der Yubikey einen 20-byte HEX code, welcher anschließend nach KeePassXC kopiert werden kann.

Wichtig dabei ist, dass der angezeigte Code später nicht mehr extrahiert werden kann. Soll die Datenbank also einen Zweitschlüssel bekommen (was anzuraten ist), so muss der Code notiert und anschließend ebenfalls im Zweitschlüssel hinterlegt werden.

Ich empfehle beim Yubikey, das Häkchen bei requires touch wegzulassen. Ansonsten muss man bei jeder Verwendung eines Passwortes den Yubikey berühren. Viel nerviger noch ist, dass für das Hinzufügen oder Ändern eines Passworteintrages ebenfalls ein Berühren des Schlüssels notwendig wird.

Nitrokey

Nitrokey sieht die Erzeugung des Geheimnisses als 20-byte base32 code vor. Er kann genau ein HMAC-Geheimnis aufbewahren. Auch Nitrokey hat eine Anleitung zum Hinterlegen des HMAC-Secrets für die Verwendung mit KeePassXC online. Wie bei Yubikey auch basiert diese Anleitung auf der Verwendung der App.

Kompatibilität Yubikey

Idealerweise würde ich nun den auf dem Yubikey erzeugten Schlüssel auf dem Nitrokey hinterlegen oder umgekehrt. So hätte ich einen Zweitschlüssel und könnte mit beiden auf die KeePassXC-Datenbank zugreifen.

Doch oh weh, der Nitrokey akzeptiert das Geheimnis des Yubikey nicht:

Genau so verhält es sich, wenn ich ein mit dem Nitrokey erzeugtes Geheimnis auf dem Yubikey hinterlegen will:

Hierfür benötige ich Abhilfe. Ich erstelle also ganz pragmatisch eine zweite Passwortdatenbank. Beide sollen denselben Inhalt haben, verwenden aber verschiedene Schlüssel zum Öffnen. Später lerne ich, dass das gar nicht nötig ist; dennoch hier erstmal meine provisorischen Lösungen.

Holzweg A: Einträge aus der Datenbank klonen

Ich befülle die erste Datenbank mit Passwörtern, welche ich in Gruppen sortiere. Anschließend klone ich die Gruppe, öffne die zweite Datenbank und ziehe den Klon per drag-and-drop herüber.

Nachteile: Ich muss den Vorgang für jede Gruppe wiederholen, denn drag-und-drop für die root-Gruppe ist nicht vorgesehen. Bei jeder Änderung in Datenbank_yubikey muss ich Datenbank_nitrokey ebenfalls anpassen.

Das ist sehr anstrengend, wenn die Datenbank sich noch im Aufbau befindet.

Holzweg B: Die ganze Datenbank kopieren und HMAC updaten

Hierfür speichert man die HMAC-Secrets der beiden Hardware Security Keys im Passwortmanager ab. Bei einer Änderung der Datenbank fertigt man eine Kopie der Datenbankdatei an, öffnet sie und kopiert sich das Secret des jeweils anderen HSK. Nun klickt man auf Database->Database Security->Change Challenge-Response und gibt das Secret dort ein. Schon funktioniert die Datenbank mit dem anderen Schlüssel.

Nachteil: Manuelle Aktualisierung beider Datenbanken erforderlich. Jedes mal ist challenge-response neu einzurichten.

Lösung: Konvertieren des HMAC-Secrets

Ich fragte mich, ob ich für den Nitrokey zur Speicherung des HMAC-Geheimnisses für meinen Nitrokey auch die Kommandozeile statt der App verwenden kann. Kommanodzeilenanwendungen wie nitropy verfügen meist über mehr Optionen als ihr GUI-App-Pendant. Vielleicht kann ich damit das Kompatibilitätsproblem lösen. Hier der Link zur Installation von nitropy.

Auf der Suche nach einer geeigneten Dokumentation stoße ich auf diesen interessanten Post zum Thema challenge-response. Dort wird mir klar, was softwareaffine Leute schon lange wissen. Zumindest, falls sie entweder mal das Thema Kryptografie gestreift haben oder nahe an der Hardware unterwegs sind:

Daten der Größe von 20 Byte lassen sich in hex mit 40 Zeichen UND in base32 mit 32 Zeichen darstellen.

Folglich lässt sich ein HMAC-Geheimnis konvertieren und damit sowohl auf dem Yubikey als auch auf dem Nitrokey ablegen. Dafür verwende ich das kleine Werkzeug xxd und lasse mir aus dem Hexcode des Yubikey eine base32-Phrase für meinen Nitrokey erzeugen.

# open a new terminal
# make sure the secrets are not saved to history (command for zsh)
history -p 
# c0ffee = secret hex key
# xxd convert input to binary (-r), output as plain hexdump (-p)
# interpret as base32 string
echo -n 'c0ffee' | xxd -r -p | base32
YD764===
# close terminal

Alternativ funktioniert auch der Rückweg:

# open a new terminal
# make sure the secrets are not saved to history (command for zsh)
history -p 
# YD764=== = secret base32 key
echo -n 'YD764===' | base32 -d | xxd -p
c0ffee
# close terminal

KeePassXC: Passwörter schön geordnet hinterlegen

Verzichtet man wie ich auf Dialoge wie “mit Google einloggen” bei Drittanbietern, so sammeln sich im Laufe des Lebens unter Umständen eine Menge Passwörter an. Zum vereinfachten Finden und verwenden der Passwörter sowohl mobil als auch auf dem Desktop bietet es sich an, sinnvolle Gruppen zu erstellen.

Passwortfamilien

Nach ein paar Experimenten hat sich folgendes Schema für Titel bewährt, wenn ich mehrere verwandte Passwörter speichern möchte:

baseapp.attribute.specialization

So würde aus den Zugängen für mein gehärtetes Gitea-setup:

gitea.login.schallbert
gitea.login.testuser
gitea.runner.registration
gitea.recoverykey

Auf diese Weise bleiben verwandte Passwörter schön beisammen.

Gruppierung

Ich halte folgende Gruppen von Passwörtern für sinnvoll:

Group	Description
Devices	Computer, phone, router, keys
Finance	Banks, credit cards, insurances, payment
Identity	Email, identity providers, single sign-in
Shopping	Online stores, streaming, subscriptions
Games	Platforms, launchers, servers
Social	Forums, Messengers, Social networks
Backup	Recovery keys, licenses, passphrases

Dabei achte ich darauf, nicht zu viele Untergruppen zu erstellen. Gerade in der Mobilansicht ist man sonst schnell verwirrt.

Icons 🔑

KeePassXC bietet die wunderbare Möglichkeit, Favicons der Zielwebsite herunterzuladen und als Symbol zu verwenden. Damit gelingt die Navigation im Passwortmanager noch einfacher.

Die Favicons sind allerdings alles Bitmaps. Möchte man hochqualitative Vektorgrafiken verwenden bietet sich an, unter “Choose Icon” den Pfad eines Icon Packs anzugeben. Ich habe mir dafür die Aegis icons heruntergeladen und bin damit sehr zufrieden.

Kritische Schwachstellen bei Gitea (und Forgejo)

Schallbert — Sun, 04 Oct 2026

Gewahrwerdung

Wie so oft beginnt auch diese Geschichte mit einem Netzwerk der menschlichen Kommunikation. Dieser unersetzliche Austausch hat schon viel zur Sicherheit der Software beigetragen, mit der ich diesen Blog betreibe. Nun kann ich eine weitere Sicherheitslücke schließen. Aber der Reihe nach.

Gitea als Angriffsziel

Ich hörte, dass die selbst gehostete Versionsverwaltungslösung Gitea eines meiner Bekannten Ziel einer Attacke geworden ist. Hierbei wurde eine RCE (Remote Code Execution) möglich und tatsächlich auch ausgeführt.

Warum ist Gitea ein attraktives Ziel?

Diebstahl von (Firmen)geheimnissen: Bei Zugriff auf Repositories ist vertraulicher Quellcode gefährdet, offengelegt zu werden.
Abfluss von Zugangsdaten: Wird ein größeres Produkt mit Schnittstellen in Gitea verwaltet, sind API keys, Konten und Passwörter in Gefahr, falls sie unverschlüsselt vorliegen. Abhilfe schaffen Tools wie git-secret; sie werden aber durch Einführen zusätzlicher Komplexität noch nicht flächendeckend eingesetzt.
Klassische Rechteeskalation: Unter Umständen kann man durch Ausbruch aus der Gitea-Software die ganze Maschine übernehmen.
Nutzen des runner: Schafft man es den Runner zu kapern, kann man auch ohne erweiterte Rechte Ressourcen der Hostmaschine in Beschlag nehmen und für eigene Zwecke missbrauchen (Stichwort Cryptominers in CI/CD).

Was ist eine RCE?

Eine Remote Code Execution ist ein erfolgreicher Angriff, bei dem nicht autorisierter Code ohne Zutun von Besitzer oder Administration der befallenen Ressource aus der Ferne über das Netzwerk eingespielt und ausgeführt werden kann.

Das Gitea-Ökosystem

Als Versionsverwaltung und forge gehört zum Basisumfang von Gitea die Möglichkeit, webbasiert und kollaborativ Software zu entwickeln und zu bauen. Daher ist vorgesehen, dass sich Nutzer registrieren und unter Umständen sogar Aktionen ausführen können, damit Software automatisiert gebaut und/oder ausgeliefert werden kann.

Genau dieses automatische Nachladen und Ausführen von Code kann böse Folgen haben, wenn Sicherheitslücken in der Verwaltungssoftware selbst bestehen.

Verwundbarkeit durch offene Registrierung

Lässt man als Betreiberin die Registrierung neuer Accounts (“self-registration”) in Giteas Konfiguration auf dem Standardwert DISABLE_REGISTRATION = false, so können sich Nutzerinnen selbst einschreiben, eigene Repository anlegen, issues aufmachen und alles tun, was ohne Adminrechte möglich ist.

Hat man zusätzlich noch den Standardwert REQUIRE_SIGNIN_VIEW = false gesetzt, können auch unauthentisierte Besucher öffentliche Repositories sehen, die Seiten von Gitea browsen und vor allem die öffentliche API des Gitea Endpoints ansprechen.

Verwundbarkeit durch Standardkonfiguration für Reverse Proxies

In der Standardkonfiguration des Gitea Docker image vertraut Gitea <V1.26.3 allen Proxies.

# gitea/app.ini

[security]
REVERSE_PROXY_LIMIT = 1
REVERSE_PROXY_TRUSTED_PROXIES = * # This is a vulnerability!

Die Sicherheitslücken

Womit haben wir es hier zu tun? Mit mehreren kritischen Sicherheitslücken des Ausmaßes 9.8/10 CVSS score, von denen es bekannte Fälle der Ausnutzung gibt.

Exkurs: Die CVSS-Bewertung

Zur Einordnung der Bewertung von “kritisch”: Die CVSS-Kriterien sind ähnlich aufgebaut wie in der klassischen Gefahren- und Risikoanalyse, einem Zweig der Ingenieurswissenschaften. Anders als dort liegt der Fokus allerdings nicht in der Analyse möglicher Fehlerfälle, Schweregrad, Eintritts- und Ausfallwahrscheinlichkeit oder Detektierbarkeit, sondern auf dem Schwierigkeitsgrad der Ausnutzung und möglicher Auswirkungen.

Bedeutung der CVSS-Einzelwerte

Je höher der CVSS-Wert, desto einfacher ist die Sicherheitslücke auszunutzen und desto gravierender sind mögliche Folgen hinsichtlich der Datensicherheitskriterien (Confidentiality, Integrity, Availability).

Das Bild oben zeigt eine Konstellation, in der eine mögliche Attacke aus der Ferne (Netzwerk) mit geringem Aufwand (Complexity, meint Systemhärtung) ohne Randbedingungen (Requirement, z.B. das Anfahren einer vulnerablen Stelle im Code, Vorhandensein eines bestimmten Zustandes des angegriffenen Systems, Auslösen einer race condition etc.), ohne zusätzliche Rechte (als Gast ohne Authentisierung oder Autorisierung) oder Interaktion mit dem User oder der Administratorin des Systems durchgeführt werden kann.

Das wäre für sich genommen noch nicht schlimm, wenn niemand das System benötigt Score 0.0 und nichts Interessantes darauf gespeichert ist. Liegen dort allerdings sensitive Daten Confidentiality, 8.7 oder zum Beispiel eine Datenbank, deren Werte sich nun manipulieren lassen Integrity, 8.7, oder wird auch nur die Verfügbarkeit von benötigten Daten eingeschränkt Availability, 8.7, befindet man sich bereits im Bereich High.

Mit diesem Wissen nehmen wir nun den Transfer auf die kritischen Lücken von Gitea vor.

CVE-2026-20896: Authentication bug in Gitea through reverse-proxies

Kommt ein Angreifer hinter den Reverse Proxy (oder ist gar kein Reverse Proxy vorgeschaltet), kann er eine Anfrage mit X-WEBAUTH-USER im Header direkt an die Gitea-Instanz senden und sich für einen Reverse Proxy ausgeben. Ist Gitea gleichzeitig darauf eingestellt, allen reverse proxies zu vertrauen REVERSE_PROXY_TRUSTED_PROXIES = *, so geht es davon aus, dass bereits authentisiert wurde und eine gültige Session vorliegt. Der Angreifer erhält also Nutzerrechte mit Schreibzugriff auf Repositories, obwohl er nicht mal einen Account angelegt hat.

Das eigentliche Lücke ist hier das unhinterfragte Vertrauen gegenüber dem Sender des Headers ohne weiteren Abgleich mit einem Session Token oder ähnlichem; das Annehmen desselben von fremden Quellen erzeugt lediglich die Verwundbarkeit.

Für diesen Bug gibt es Belege für bereits erfolgte Attacken.

CVE-2026-59774: File-read flaw for anything the Gitea Service Account can read

Diese kritische Sicherheitslücke basiert auf einer unzureichenden Eingabeprüfung des eingebauten Textrenderers von Gitea für org-mode Dateien. Eine detaillierte Beschreibung des Vektors und zu möglichen Wegen eines Angriffs kann auf Saytam Rastogis hervorragendem Blog nachgelesen werden.

Kurzgesagt kann sich ein Angreifer mit Zugriff auf zumindest ein öffentliches Repository eine bösartige .org-Datei zusammenbasteln, mit deren Hilfe er Giteas Konfiguration app.ini auslesen und damit auf darin enthaltene Secrets zugreifen kann, welche ihm erweiterte Rechte zugestehen oder ihn zumindest lateral auf dem System bewegen lassen.

Dies kann laut hacker news und Giteas eigenen Leuten zufolge beispielsweise auch dazu ausgenutzt werden, die Registration Token eines Runners auszulesen und selbigen zu übernehmen.

CVE-2026-60004: RCE allowing attacker with ordinary user rights to execute arbitrary shell commands as the Gitea OS user.

Diese Sicherheitslücke ist deswegen besonders schlimm, weil sie zusätzlich eine privilege escalation ermöglicht.

“The vulnerability in question is CVE-2026-60004 (CVSS score: 9.8), a case of remote code execution that allows an attacker with ordinary write access to a repository to execute arbitrary shell commands as the Gitea OS user.” thehackernews, Aug-2026

Das Ausnutzen dieser Lücke kann den Angreifer also die gesamte Gitea-Instanz übernehmen lassen, sofern er Schreibzugriff auf irgendein (evtl. sogar öffentliches) Repository hat.

Das Lagebild

Es gibt noch weitere kritische Sicherheitslücken, allerdings könen sich Angreifer mit einer Kombination der obigen Darstellungen ohne großen Aufwand

Als normale User auf dem Gitea-System bewegen, ohne sich registriert zu haben, und ohne SSH-Zugriff zu benötigen
Sich als Gitea-Service User ausgeben
Actions übernehmen oder sogar Workflows injizieren und ausführen
Mit etwas Mehraufwand die gesamte Instanz übernehmen, verschlüsseln, Lösegeld verlangen usw.

Was mein Bekannter erlebt hat betraf die Punkte eins und drei. Der Angriff wurde sehr wahrscheinlich automatisiert ausgeführt, nachdem das Internet auf verwundbare Instanzen gescannt worden war.

Zusammengefasst kann man im vorliegenden Fall von einer Mass-Exploitation Campaign für Cryptomining ausgehen.

Der Cryptominer

Bei meinem Bekannten wird folgende Datei als statisch gelinkte Executable (!) auf dem System abgelegt: gitea/data/gitea/sys_health_s3 Der Hash der Datei legt seiner Ansicht nach nahe, dass ein XMRig cyptominer als bösartige Payload eingesetzt wurde, der mit pool.hashvault.pro kommuniziert und dabei einen Großteil der verfügbaren CPU-Leistung für sich beansprucht.

Noch größerer Schaden möglich

Sogar für den auslegungsüberschreitenden Stöfall habe ich ein aktuelles (Sep-2026) Beispiel auf Hackernews finden können: Diebstahl von Quellcode, Sammlung von Zugangsdaten, Privilege escalation bis hin zum root-Zugriff auf das betroffene System.

Wie entdecke ich einen Angriff?

Schlimmstenfalls gar nicht. Sind Profis zielgerichtet am Werk, können allenfalls die Logdateien zum Zeitpunkt direkt nach dem Einbruch Aufschluss geben. Im Falle, dass man sie sofort liest und interpretieren kann. Aber ich schweife ab¹.

Dannoch sollte man sich folgende Fragen stellen:

Betreibe ich eine vulnerable Gitea-Version (<1.27.2)?
Verzichte ich auf eine Monitoring-Lösung, die bei Auffälligkeiten warnt?
Liegt eine ungewöhnlich hohe CPU-Last des Systems vor (Deutet auf Kryptominer-Befall hin)?
Für diesen konkreten Miner kann man zusätzlich nachsehen, ob auf dem System folgende Datei zu finden ist:

find / -name '.sys_health_s3' 2>/dev/null

Beantwortet man sich nur eine dieser Fragen mit ja, ist zügiges Handeln angebracht. Dabei ist durch den Schweregrad der Sicherheitslücken das gesamte Hostsystem als kompromittiert anzusehen, insbesondere wenn der Gitea-Container oder ein eventuell eingebundener Runner rootful läuft, also mit dem Docker Socket ausgestattet wurde.

Bei Befall: Quarantäne

Nächste Schritte: Sofort die betroffene Maschine isolieren und vom Netz nehmen. Die Container herunterfahren, Hostmaschine durchbooten und Updates nachladen. Aschließend die Docker Registry auf Stand bringen und über die Logdateien (Zeitstempel!) ermitteln, ob andere Teile des Systems betroffen sind. Für weitere Details siehe mein Artikel über einen selbsterlebten Angriff auf Gitea.

Lösungen

Gitea Updaten!

Gitea muss dringend auf eine Version >1.27.1 gebracht werden. Dafür kann beispielsweise die docker-compose.yml geändert und die Container danach durchgebootet werden:

# docker-compose.yml
gitea:
 image: gitea/gitea:latest
 container_name: gitea

Weitere Informationen zu aktuellen Fixes finden sich auf Giteas Blog. Der Major Release auf Version 27 löst eine ellenlange Liste an kritischen Sicherheitslücken. Ich habe in diesem Artikel nur ein paar davon herausgepickt, da sie mein direktes Umfeld betreffen und ihre Ausnutzung bekannt ist.

Gitea und Runner `rootless` ausführen

Führt das Ausnutzen einer Sicherheitslücke zum Verlust von Gitea oder dem Action Runner, sollte nicht auch noch das Hostsystem kompromittiert werden. Der Betrieb in einem Container kann den Schadensumfang deutlich reduzieren. Das Aufsetzen einer rootless-Lösung habe ich daher hier beschrieben.

Zusätzliche Maßnahmen (Härtung)

CVE-2026-20896: Netzwerkzugriff erschweren

Bei den folgenden Schritten folge ich der Empfehlung von d00ftech.

Einfügen des Adressraumes des selbst verwendeten Reverse Proxy. Dafür gilt erst einmal herauszufinden, unter welcher Adresse der Reverse Proxy im Netzwerk erreichbar ist. Auf meinem Server beispielsweise laufen Gitea und Reverse Proxy (Caddy) in Docker. Daher finde ich die IP-Adresse wie folgt:

docker inspect caddy \
 --format='{{range $name, $network := .NetworkSettings.Networks}}{{$name}}: {{$network.IPAddress}}{{"\n"}}{{end}}'
caddy-proxy: 172.20.0.2

Dieser Wert wird nun in der gitea/app.ini eingetragen:

[security]
REVERSE_PROXY_LIMIT = 1
REVERSE_PROXY_TRUSTED_PROXIES = 172.20.0.2/32

Direkten Netzwerkzugriff auf Gitea unter Umgehung des eigenen Reverse Proxy blockieren. Dazu darf der Port von Gitea (meist 3000) nicht in der Portfreigabe beispielsweise der Docker-Konfiguration erscheinen:

# docker-compose.yml
services:
 gitea:
 ports:
 - "3000:3000" # remove this!

CVE-2026-59774: Gitea updaten!

Es gibt zwar die Möglichkeit, den org-mode renderer in der app.ini zu deaktivieren (Siehe Gitea Documentation zum Thema), der weitaus bessere Weg ist aus meiner Sicht aber das Update von Gitea selbst!

CVE-2026-60004: Falls möglich Self-Registration abschalten

Der eigentliche Fix ist nur durch ein Update der Gitea-Version möglich. Für kleinere Instanzen mit wenigen Usern mag es zusätzlich zweckmäßig erscheinen, die Selbstregistrierung für neue User abzuschalten. Sie müssen eine Registrierung von nun an bei den Administratoren anfragen (sofern sie nicht eine der anderen oben beschriebenen CVEs ausnutzen).

# gitea/app.ini
[service]
DISABLE_REGISTRATION = true

Weitere hilfreiche Einstellungen sind:

REGISTER_EMAIL_CONFIRM = true # Requires user's email to be confirmed for registration to complete
ENABLE_OPENID_SIGNUP = false # Disallow logons via external API
REQUIRE_SIGNIN_VIEW = true # Force users to login before they can view content or use the public API

Ausblick und Fazit

Versionsverwaltungen sind sehr atttraktive Ziele für gleich einen ganzen Strauß an Angreifertypen: Von Cryptominern wegen der Möglichkeit der Ressourcenübernahme über Ransomware-Gruppen wegen der Quellcodedateien und möglicher Zugangsdaten bis hin zu hochprofessionellen, zielgerichteten Angreifern und staatlichen Akteuren dadurch, dass die Software eine Art Infrastruktur darstellt.

Daher:

“Alle Patches einspielen. Immer. Sofort. Ohne Ausnahmen.” - Felix von Leitner, sagt aber auch das BSI

Was mich ein wenig ratlos zurücklässt ist die schiere Zahl und Kritikalität der gestopften Sicherheitslücken (35 CVEs binnen eines Monats laut Giteas eigenem Blog!). Aus meiner blauäugigen Sicherheitsperspektive ist diese Lösung ein Schweizer Käse und ich bin mir nicht sicher, ob ich Gitea weiter betreiben sollte.

Sofort: Härtung durchführen

Na klar: Gitea auf latest bringen und die oben beschriebenen Härtungsmaßnahmen durchführen.

Kurzfristig: Automatische Updates

In den nächsten Tagen und Wochen werde ich mich damit beschäftigen, die Docker Registry automatisch nach Updates für meine Software zu durchsuchen und sie ebenso automatisch auf meinem Server auszurollen. Blog-Post dazu hier.

Mittelfristig: Her mit Monitoring

Ich werde mich auf die Suche machen nach einer kleinen und leichten Monitoring-Lösung, die Auffälligkeiten wie “CPU-Last ungewöhnlich hoch seit HH:MM:SS” meldet und healthchecks durchführen und überwachen kann. Dabei darf sie selbst kein Einfallstor dastellen, muss also praktisch ohne Rechte auskommen. Ob das wohl einfach möglich ist?

Mittelfristig 2: Weg mit den Secrets

Unverschlüsselte Secrets haben in Repositories nichts verloren. Selbst auf dem Server selbst ist eine .env-Datei, die dort herumliegt, als nicht mehr sicher zu werten. Auch hier werde ich mir Gedanken machen und entsprechend berichten, wenn ich eine Lösung ausgerollt habe.

Mittelfristig 3: News-Feeds einrichten

Hierunter fallen Abos z.B. von Newslettern oder RSS-Feeds idealerweise aller meiner Softwareanbieter, IT-Security-Institutionen oder -Journalisten und weiteren Quellen, aus denen ich Sicherheitslücken, Patches und Maßnahmen zur Systemhärtung entnehmen kann.

Langfristig: Mit Leuten weiterhin ins Gespräch gehen

Es endet wie es beginnt. Bevor ich Probleme mit meiner Software lösen kann, bevor ich überhaupt von den Problemen weiß, ja genau da! Ganz am Anfang, bevor ich überhaupt entschieden habe, welche Software ich einsetze, da stehen: Andere Menschen.

Leute, die ich fragen kann, um Hilfe bitten kann. Deren Zeit ich in Anspruch nehmen darf für eigene Belange. Die ich zum Beispiel per Messenger aus dem Nichts heraus anschreibe und aus ihrem Fokus reiße.

Leute, die sich besser auskennen als ich, die einen anderne Blick auf die Dinge haben, oder deren Meinung ich interessant finde.

Kolleginnen, auch Ehemalige, Bekannte und Freunde, Familie, die ich zufällig oder zielgerichtet auf einen Austausch treffe. Auf einen Kaffee, ein Eis, ein Kaltgetränk, zum Musizieren oder für einen Brettspielnachmittag.

Leute, die mir trotz der Unterbrechung und doofer Fragen freundlich und geduldig helfen. Die vielleicht kurz mit den Augen rollen, mir die Dinge dann aber doch noch ein weiteres mal erklären. Die meine Monologe, kritische Nachfragen und gelegentliche Gegenrede irgendwie tolerieren.

Leute, mit denen ich in einen Austausch treten kann, der am Ende hoffentlich beiden Seiten nützt.

Bei euch allen möchte ich mich bedanken. Mit Leuten wie euch wird alles viel einfacher. Auch der Betrieb dieses Blogs, wo so viel meiner Zeit hineingeht. Ich kann mit euch Entscheidungen diskutieren, erfahren wie ihr Dinge gemacht habt und warum genau so, die Perspektiven wechseln. Und neue Ideen entwickeln.

Bitte bleibt mir erhalten.

Verweis an “Fefe” Felix von Leitner. Zitat: “Annahmen […]: Wir werden angegriffen. Wir merken es zeitnah. Aller Erfahrung nach: Nein, tun wir nicht. Typischer Zeitraum vor Entdeckung von blinden Passagieren: Ein halbes bis fünf Jahre.” - aus dem Vortrag Hackback, Link führt zu Codeberg. ↩︎

Hugo vs. Jekyll: Benchmark

Schallbert — Wed, 30 Sep 2026

Ladezeiten

Schauen wir uns mal an, wie meine Seite mit Jekyll gegenüber Hugo lädt. Hierfür öffne ich die Entwickleroptionen (F12) in meinem Browser, wähle das Network-Tab an und klicke dort auf All. Anschließend lade ich die Seite neu.

Dabei entsteht die folgende Auflistung:

Im Bild unten: Ladezeit meiner Landing Page mit Hugo

Zu erwähnen ist, dass ich hier eigentlich gar nicht Jekyll mit Hugo vergleiche, sondern lediglich deren Ausgabe und daher die gewählten Themes maßgeblich für Größe und Ladezeit verantwortlich sind. Also vergleiche ich praktisch das minimalmistakes theme in Jekyll mit dem terminal theme in Hugo. Hugo ist in diesem Falle etwa 10% schneller als Jekyll.

Im Bild unten: Ladezeit meiner Landing Page mit Jekyll

Größe

Ein anderes Diagramm erhalte ich, wenn ich ganz unten links auf die Stoppuhr klicke und damit eine performance analysis ausführe. Die Kuchendiagramme zeigen für meine Implementierung in Jekyll den größten Anteil in Bildern, gefolgt von CSS und JS. In Hugo geht JS gegen null, und auch der Anteil von CSS ist geschrumpft.

Die folgende Tabelle zeigt ein paar meiner Seiten im direkten Vergleich. Allerdings ist die Übersicht mit Vorsicht zu genießen: Die Werte ändern sich schon mal, wenn ich neu lade (auch mit ausgeschaltetem Cache). Gerade bei eingebundenen Inhalten Dritter wie meinen Videos kommen hier teils stark unterschiedliche Werte heraus. Insgesamt habe ich mit Hugo und Terminal deutliche Optimierungen vorliegen.

Item	minimal-mistakes	terminal-schallbert		Jekyll	Hugo
	transferred	[kB]	Diff [%]	time	[ms]	Diff [%]
Landing	163.47	98.68	-39	30	30	0
Post	2861	1767	-38	340	270	-20
List page	1507	140	-90	30	30	0

Manuell implementiert in Hugo hatte ich das bedingte Laden von Katex nur auf Seiten, wo mathematische Ausdrücke auftauchen (das spart oftmals 90kB min.css).
Mit Hugo habe ich kleinere CSS-Dateien. Es wird nur geladen, was ich auch wirklich verwende. Es gibt kaum noch Code, der nicht angefahren wird.
Automatisch in Hugo sind Medien-Vorschaudateien von den hochauflösenden Dateien abgeleitet und per Bildprozessor auf die Darstellungsverhältnisse im gebauten Zustand platzoptimiert. Diese Optimierung spart bei vielen, klein dargestellten Bildern eine Menge Bandbreite.
Das Terminal-Theme zeigt anders als minimalmistakes keine Kärtchen für “weitere Posts” an. Dies spart die Übertragung von vier Vorschaubildern.
In Hugo habe ich fast gar keine Javascript-Inhalte mehr - eines der Ziele, das ich mir gesteckt hatte.

Auslieferung/Continuous Deployment

Für Jekyll gestaltete sich Bauen und Ausliefern in Gitea etwas hakelig: erst mit einem Jekyll-Dockerimage war ich in der Lage, ruby richtig aufzusetzen. Damit und weil ich meinen Actions nicht erlaube zu cachen dauert das Bauen ziemlich lang: Erst den aktuellen Docker-Container ziehen, ruby und jekyll updaten, gems installieren, die Quelldateien auschecken, anschließend bauen und ausliefern - hier vergehen selbst unter optimalen Bedingungen mehr als 90 Sekunden, bis ein neuer Artikel live ist.

Für Hugo geht der ganze Prozess dank schnellerer Bauzeiten und vorgefertigter Container (siehe dazu mein Artikel zum Thema Continuous Deployment Pipeline mit Hugo in Docker) viel schneller vonstatten.

Selbst im ungünstigsten Fall (siehe Build unten), z.B. nach einem Neustart des Runners nach Update und einer Änderung im Docker-Repository für meinen Hugo Container, bleibe ich weit unter 30 Sekunden.

Komplexität

Ganz klar: Hugo ist hier im Vergleich zu Jekyll unschlagbar.

Da Themes in Hugo steckbare Module sind, benötigen sie keinen Abhängigkeitsbaum in Form von Gems wie bei Jekyll zum Nachladen und installieren. Entsprechend kann hier viel weniger kaputt gehen. Für mich lokal verringert sich die Bauzeit für einen “full build” (zweisprachig) um 75% und auch das automatische Bauen bei Veränderung meiner Markdown-Dateien ist sowohl 5x schneller als auch aussagekräftiger: Wenn ich in Jekyll nämlich “incremental build” einschalte, dann gibt es keine aktualisieren Paginator-Seiten mehr - sprich Listenansichten und Übersichtsseiten werden nicht mit gebaut.

Auf der anderen Seite kann ich in Jekyll sehr flexibel und feingranular selbst eingreifen, eigene Gems entwerfen und recht einfach besondere Gimmicks für meine Seite herstellen wie ein mitscrollendes Inhaltsverzeichnis. Jenes vermisse ich in Hugo etwas.

Fazit: Für die tagtägliche Benutzbarkeit gefällt mir Hugo ganz klar besser als Jekyll. - schallbert, Sep-2026

Continuous Deployment für Hugo

Schallbert — Tue, 15 Sep 2026

Gerade habe ich meine Website von Hugo auf Jekyll umgezogen. Nun will ich sie automatisiert bauen und Änderungen ausrollen, sobald ich einen Artikel fertiggestellt und ihn per git push und anschließendem Merge in main auf meine Gitea-Instanz geschoben habe.

Die Befehlskette

Ich habe einen VPS gemietet, auf dem ich alle Anwendungen in Docker laufen lasse. Die Aufgabe ist nun, einen workflow in Gitea zu bauen (“Actions”), welcher das Update im Repository auscheckt, es hugo zur Verfügung stellt, dort die HTML-Seiten erzeugen lässt, und sie anschließend so auf der Festplatte ablegt, dass mein Webserver die Dateien einlesen und ausliefern kann.

Erfahrungswerte

Das alles hatte ich für meine Website in Jekyll bauen und ausrollen können, daher kann ich auf ein paar Erfahrungswerte zurückgreifen.

Üblicherweise nutzt man dafür standardisierte Aktionen. Ich vereinfache mal stark und liste nur die Hauptdarsteller auf, ohne in fiese Details wie Rechtevergabe (darf Hugo in diesen Ordner schreiben? Hat der hugo-user genügend Rechte?) tiefer einzugehen:

checkout stellt einen gewünschten Stand des Quellrepository bereit
actions-hugo installiert hugo in der virtuellen Maschine der Action, sodass die Website gebaut werden kann
upload-artifact lädt die von hugo erstellte Seite auf den Webserver hoch

Da ich jedoch auf ein- und derselben Maschine in Docker unterwegs bin, kann ich mir das aufwendige Einwählen auf dem Webserver “von außen” sparen. Daher gehe ich einen anderen Weg.

Docker shared Volumes

Ich kann meiner Caddy-Anwendung direkt die gebauten Dateien zur Verfügung stellen, wenn ich das von ihr gelesene Volume bis in die Action weiterreiche.

Aufgepasst: Action volume != Hugo volume

Doch das funktioniert mit actions-hugo nicht: Sie ist selbst kein Docker container, kann also keine Volumes einbinden. Sie baut zwar die Webseite fertig; sobald die Aktion jedoch durchgelaufen ist, reißt sie die Artefakte mit ins Nirvana.

Ich benötige also eine hugo-Runtime, die selbst in einem Docker-Container läuft - ganz nach dem DinD-Ansatz. Diesem kann ich dann das von Caddy verwendete Volume mit Schreibzugriff durchreichen.

Der Workflow

Doch welchen Docker-Container soll ich nehmen?

Man stelle sich nun mehrere Stunden der Recherche und viele Fehlversuche beim Einrichten des Workflows auf meinem Server vor.

Folgendes ergab sich aus meinen Untersuchungen:

checkout@v4 benötigt node.js, und zwar mindestens Version node:18. Der Docker-Container (und das darunterliegende Betriebssystem des Runners!) müssen es installiert haben bzw. unterstützen.
Die Action benötigt git. Auch dies muss der Docker-container idealerweise bereits mitbringen.
Hugo braucht go. Klingt soweit logisch.

Runner-Betriebssystem anpassen

Mein Runner aus dem Jahr 2023 ist inzwischen in die Tage gekommen. Er basiert auf node:16-bullseye, eine Debian-basierte VM. Ich probiere etwas mit Alpine herum, doch diese Installation ist zu minimal für meine Zwecke und lässt mich mit vielen manuellen Anpassungen zurück. Schließlich muss der Runner noch andere Workflows ausführen als diesen hier. Ich entscheide mich letztendlich, bei Debian zu bleiben und nur die Node-Version hochzuziehen. Die Umsetzung in der Runner-Konfiguration sieht dann wie folgt aus:

# /gitea/runner/config.yml

 # The labels of a runner are used to determine which jobs the runner can run, and how to run them.
 # Like: ["macos-arm64:host", "ubuntu-latest:docker://node:16-bullseye", "ubuntu-22.04:docker://node:16-bullseye"]
 # If it's empty when registering, it will ask for inputting labels.
 # If it's empty when execute `deamon`, will use labels in `.runner` file.
 labels: [ubuntu-latest:docker://node:20-bullseye]

Anschließend muss der Runner-Container neu gestartet werden. Idealerweise bootet man Gitea gleich mit durch, dann funktioniert das Registrieren des Runners auch zuverlässig.

Das Workflow-Script schreiben

Um die oben beschriebenen Abhängigkeiten abzudecken entscheide ich mich für einen “batteries included”-Ansatz. So kann ich die Bausteine einfach ohne manuelle Anpassungen zusammenstecken und vertraue auf langfristige Wartung und Pflege der Container, da sie wirklich sehr häufig verwendet werden (Größenordnung mehrere Millionen Pulls). Diese Webseite half mir sehr bei der Auswahl.

Schließlich erstelle ich meinen Workflow basierend auf dem Container von Hugomods.

# /.gitea/workflows/build-deploy-with-hugo.yml

name: Deploy Hugo site
run-name: ${{ gitea.actor }} builds Hugo site
on:
 push:
 branches:
 - main

jobs:
 # Build job
 build:
 runs-on: ubuntu-latest # this is the "label" the runner will use and map to docker target OS
 container: 
 image: hugomods/hugo:latest
 volumes: 
 - /tmp/blog-artifacts:/tmp/blog-artifacts

 steps:
 - name: --- CHECKOUT ---
 uses: actions/checkout@v4
 with:
 submodules: recursive  # Fetches Hugo themes
 fetch-depth: 0

 - name: --- BUILD WITH HUGO --- # chown -R hugo /tmp/blog-artifacts
 run: |
 hugo \
 --minify \
 --cleanDestinationDir \
 --destination /tmp/blog-artifacts

Zielordner bereinigen

Ich habe mich im obigen Beispiel für ein “direktes Deployment” entschieden, ohne Netz und doppelten Boden, und ohne, dass ich die Artefakte herumkopiere oder gar den Server neu starte. Begründung: Der Hugo-Bauprozess benötigt für Meine Seite weniger als 2000ms. Nur in diesem Fenster kann Caddy theoretisch eine “korrupte” Datenbank sehen und ausliefern, also nur während die Platte vom Hugo-Build-Workflow noch beschrieben wird.

Um Inkonsistenzen trotzdem weitgehend zu vermeiden, gebe ich Hugo die Option --cleanDestinationDir mit. Damit ist das Zielverzeichnis stets sauber und Caddy wird im Zweifel keine defekte Seite anzeigen, sondern höchstens eine 404-Fehlermeldung erzeugen.

Submodules

Wie in meiner Projektdokumentation geschrieben, kann man in Hugo zum Laden von Themes sogenannte submodules verwenden. Diese werden in das Projekt eingeklickt und können, wenn korrekt verlinkt, dann auch im Workflow verwendet werden:

 with:
 submodules: recursive  # Fetches Hugo themes
 fetch-depth: 0

Ist alles richtig eingestellt, sollte es nicht zu folgender Fehlermeldung kommen:

# workflow action's error message due to incoherent submodules' commit references
# actions/checkout@v4:
Fetching submodules
/usr/bin/git submodule sync
/usr/bin/git -c protocol.version=2 submodule update --init --force
Submodule 'themes/terminal' (https://github.com/panr/hugo-theme-terminal.git) registered for path 'themes/terminal'
Cloning into '/workspace/schallbert/blog-hugo/themes/terminal'...
fatal: remote error: upload-pack: not our ref 719505fc89332baa69bffb90cee708ff124dd143
Fetched in submodule path 'themes/terminal', but it did not contain 719505fc89332baa69bffb90cee708ff124dd143. Direct fetching of that commit failed.
Error: The process '/usr/bin/git' failed with exit code 1
Error: Process completed with exit code 1.

Voraussetzung ist, dass man die Submodule auch lokal richtig geladen hat:

schallbert@machine:~ git submodule add -f https://github.com/<my/hugo-theme>.git themes/my-hugo-theme
schallbert@machine:~ git submodule update --init --recursive

Die Statusabfrage darf keinen leeren String zurückgeben, sondern muss einen Commit hash beinhalten. Beispiel:

schallbert@machine:~ git submodule status 
44d9a1890d228745ffc300b37a7d73e940ef9fa9 themes/terminal (v4.2.5)

Weiteres Zeugnis ist die .gitmodules-Datei, welche eine Referenz auf das Theme beinhalten muss:

schallbert@machine:➜/blog git:(main) ✗ nano .gitmodules
 [submodule "themes/terminal"]
 path = themes/terminal
 url = https://github.com/panr/hugo-theme-terminal.git

Funktioniert das nicht, so sind die Submodule nochmal komplett zu entfernen und antschließend wie oben beschrieben neu zu initialisieren:

git submodule deinit -f themes/<my-theme>
git rm -r --cached themes/<my-theme>
rm -rf .git/modules/themes/<my-theme>

Typische Probleme: Hugo-Versionen und Deprecations

Nun verlief die checkout-Aktion erfolgreich. Doch der Build mit Hugo schlägt fehl:

 error calling partial: "/workspace/schallbert/blog-hugo/layouts/_partials/head.html:37:40": execute of template failed: template: _partials/head.html:37:40: executing "_partials/head.html" at <$.Page.Language.Locale>: can't evaluate field Locale in type *langs.Language
Error: Process completed with exit code 1.

Lokal auf meiner Maschine baut Hugo erfolgreich, gibt aber ein paar Warnungen heraus:

Änderungen der Language-identifier und -Auswertung ab v0.158

schallbert@machine:➜/blog git:(main) ✗ hugo build --logLevel info 
WARN deprecated: site.Language.Locale was deprecated in Hugo v0.158.0 and will be removed in a future release. Use .Page.Language.Locale instead.
WARN deprecated: .Language.Lang was deprecated in Hugo v0.158.0 and will be removed in a future release.

Man könnte denken, dass sich diese Fehler leicht beheben ließen. Leider können sie sich prima verstecken:

in Submodules, die man als third-party-content lädt (z.B. in Themes). Eine projektweite Suche in der IDE hat Submodules üblicherweise ausgeblendet und liefert keine Treffer.
als Variablen im eigenen Code, die nur indirekt auf die alten Parameter zugreifen: Ich benutze bis dato .Page.Site.Home.AllTranslations, um herauszufinden, ob ich mich auf einer gegebenen Seite in der “Hauptsprache” aufhalte. Allein schon das Scoping ist widersinnig und wird meiner Meinung nach zu Recht entfernt. Das, was ich tun will, kann nun viel einfacher erreicht werden mit .Page.Language.IsDefault

Submodules auf Stand bringen

Bei den Submodulen sehe ich zwei Lösungsansätze:

Die Maintainer anschreiben (bzw. ein Issue aufmachen), dass ihr Code gerade veraltet und sie darum bitten, ihre Themes auf Stand zu bringen.
Die betroffenen Dateien aus dem Submodule herauskopieren und in die eigene Ordnerstruktur integrieren. So würde das in meinem Falle betroffene language-menu.html unter /layouts/partials/language-menu.html eine neue Heimat finden. Dort behebe ich dann die Probleme selbst.

Eigene Lösungen programmieren

Macht die Fehlermeldung keine Lösung offensichtlich, so kann man sich gut an der Hugo Community orientieren. Für die Deprecatoins in v0.158 gibt es beispielsweise eine ausführliche Dokumentation.

Versionen abgleichen

Hmm. Wie das Bild zeigt, verwendet mein Container das Paket hugo extended von hugomods, welches die Version v0.154.5 bereitstellt; ich hatte einen stabilen release für die Action ausgewählt. Vergleichen wir mal mit meiner lokalen Version, die inzwischen ohne auch nur eine Warnung brav baut:

➜ blog git:(main) ✗ hugo version
hugo v0.162.1+extended linux/amd64

Der Klassiker: Es gibt eine Änderung ab v0.158, die die interne API verändert. Ältere Versionen kennen die neuen Felder nicht und meckern. Neuere Versionen hingegen kreiden die Verwendung der alten Felder an.

Ich glaube, diese Probleme lassen sich nur dann zuverlässig vermeiden, wenn die Pipeline für lokal und remote identisch ist. Sprich: Auf dem Lokalen Rechner eine virtuelle Maschine mit dem CI-Betriebssystem booten und alles in Docker wegkapseln. Macht bestimmt Sinn, wenn man in einer größeren Organisation arbeitet und mehrere User vor diesem Problem stehen.

Stattdessen wechsle ich zur Behebung im Remote Container auf die Version image: hugomods/hugo:latest und behebe damit den Fehler. Jedoch habe ich noch immer unterschiedliche Versionen lokal und in der CD-Pipeline. Für mein Betriebssystem gibt es die neueste schlicht noch nicht und auch der Docker Release hängt zeitlich etwas hinter den Releases des Originals.

Die Bau- und Releasezeiten sind fantastisch, oder? Eine Änderung an der Website in 12 Sekunden online zu haben, inkl. Container hochziehen etc. - das gab es bei mir jedenfalls noch nie. Um die 20 Sekunden benötigt der Durchlauf, wenn er die Container refs erst neu holen und herunterladen muss, z.B. bei Updates der Registry von latest.

Einen detaillierten Benchmarkd zwischen Hugo und Jekyll bietet der verlinkte Artikel.

Schallberts Blog mit Hugo

Schallbert — Sun, 06 Sep 2026

Was ist geschehen?

Zum fünften Geburtstag 🥳 stelle ich schallbert’s Blog auf eine neue technische Basis!

Ich habe diesen Blog von jekyll nun auf den Webseitengenerator Hugo umgezogen. Das war viel Aufwand: Über etwa vier Monate hinweg habe ich einen Großteil meiner Freizeit hineingesteckt. Dabei ging der Löwenanteil in das Erstellen und Polieren der Formatierung, Anpassung meiner Inhalte an die neue Umgebung, Reparatur defekter Links und die Dokumentation meines Umbaus.

Warum habe ich das gemacht?

Mit Jekyll stand ich immer mehr auf Kriegsfuß: Viele Abhängigkeiten mit immer häufigeren Defekten, die zunehmend lange Bauzeit und die komplexe Umgebung zum Ausrollen auf meinem Server waren die Hauptgründe.

Meine Seite baut nun etwa fünf mal so schnell wie vorher.

Sie lädt weniger Formatierung nach (CSS, JS) und die Bilder sind noch einmal platzsparender.

Außerdem habe ich weder Ruby noch zig Gems auf Stand zu halten.

Bei den Themes habe ich in Hugo Wert darauf gelegt, es nach benötigter Funktion auszuwählen und nicht nur nach gefälligem Aussehen. Somit ist es jetzt viel simpler und performanter.

Was haben die LeserInnen davon?

RSS logo ^[1]

Der Blog bietet nun einen RSS-Feed. Außerdem sind nun auch meine Projekte in die Schlagwort-Ansicht mit eingebunden. Zu guter Letzt sind durch die Migration zahlreiche Artikel entstanden. Diese sollen einen solchen Umzug für andere leichter machen als ich es hatte, und die Strukturen in Hugo verdeutlichen.

Artikel zum Thema

Was fehlt noch?

Ich bin mit dem Umbau noch nicht ganz fertig:

Die Website auch für die mobile Darstellung optimieren ✓
Es soll möglich sein, Bilder zentriert und in nativer Auflösung anzuzeigen ✓
Der Feed soll Coverbilder meiner Artikel korrekt anzeigen ✓
Ich möchte in CSS einen noch einheitlicheren Look haben (Farben, Bildränder etc.)
Übersichtsseiten könnten die ganze Bildschirmseite einnehmen und dann größere Bilder anzeigen
Es fehlen einige englische Übersetzungen ✓
Schlagworte könnten spezifischer und trennschärfer implementiert werden
Schön wäre ein mitscrollendes Inhaltsverzeichnis auf der linken Seite

Auf diesen Seiten wird es in den kommende Wochen in vielen Details noch einmal Verbesserungen geben. Ich freue mich darauf!

schallbert

Umzug von Jekyll zu Hugo

Schallbert — Sun, 06 Sep 2026

Projekt-Steckbrief

Schwierigkeitsgrad: Mittel 3/5
Kosten: 0€
Zeit ~20h

In diesem Projekt beschreibe ich meinen Umzug von Jekyll mit der Optik von Minimal Mistakes zu Hugo in einem stark modifizierten Terminal-Theme.

Warum überhaupt wechseln?

Schon seit langem war ich nicht mehr vollständig zufrieden mit dem Bauen meiner Website per Jekyll. Der Auslöser für den Umstieg war, dass ich eines Tages plötzlich wegen eines Kompatibilitätsproblemes nicht mehr lokal bauen konnte. Ein bundle update --conservative oder bundle install wie üblich half nicht. Auch das manuelle Nachinstallieren der verursachenden Pakete per gem install commonmarker-0.23.12 oder gem install posix-spawn -v 0.3.15 -- --with-cflags=\"-Wno-incompatible-function-pointer-types\" brachten keine Abhilfe.

Ein Update von Ruby und Jekyll selbst brachte ebenfalls keinen Erfolg. Und überhaupt: Die Bauzeit mit Jekyll ist inzwischen ziemlich lang geworden. Ich bin durch meinen Umzug der Seite von Github Pages auf einen eigenen Server nicht mehr an Jekyll gebunden, was einen Wechsel attraktiver macht.

Weitere Schwierigkeiten mit Jekyll

CI&CD: Meine Deploy-Pipeline war vor Monaten mit ähnlichen Fehlern ausgefallen, sodass ich auf eine ältere Jekyll-Version zurückgreifen musste. Damit vergrößert sich technische Schuld und Angriffsfläche meiner Actions. Ich müsste auf die Suche nach einer gut gewarteten Containerlösung eines anderen Anbieters wechseln. Suche und Einrichtung würden zusätzliche Zeit erfordern.
RSS-Feed: Ich möchte zu meiner Website gern einen RSS-Feed bereitstellen. Meine Experimente mit Jekyll zeigten jedoch, dass nur “Posts” und keine “Announcements” inkludiert werden. Das wollte ich beheben.
Bildformate: Cover-Bilder (Thumbnails) für Posts werden im RSS-Feed durch Jekyll eigentlich mit gebaut. Durch meinen Umstieg von .jpg auf das platzsparendere .avif funktionierte das nun leider nicht mehr. Eine Lösung habe ich trotz mehrerer Anläufe nicht durch den Pull Request Review bekommen.
Icons: Das von mir verwendete Theme nutzt Font Awesome zur Darstellung von Icons und ist insgesamt für eine statische Website recht groß. Ich wollte aber nichts aus dem Netz nachladen und habe die Bibliothek daher lokal gespeichert. Daher war mein Plan, nur die wirklich benötigten Icons heraussuchen und den Rest zu löschen. Mit dem Umstieg auf Hugo ist dies nicht mehr notwendig.

Die Chancen

Von Hugo verspreche ich mir schnellere Bauzeiten, eine vereinfachte CI/CD ohne Nachinstallieren von Bundler, Ruby etc. und die Behebung der oben beschriebenen Schwierigkeiten. Das Abhängigkeits- und Paketmanagement von Hugo unterscheidet sich grundlegend von Jekyll: Zusätzliche Inhalte werden per Git Submodules eingebunden und das Abhängigkeismanagement nutzt statt der Gemfile schlicht Go modules.

Das Migrationswerkzeug

Die Ordnerstrukturen der Inhalte unterscheidet sich deutlich zwischen Jekyll und Hugo. Ich nutze daher ein in Hugo enthaltenes Importwerkzeug, welches mir zumindest die Artikel unter /posts korrekt importiert.

Alle spezifischen Inhalte wie Übersichtsseiten /tags, /pages/error, /pages/legal und Seiten, wo Projekte und Ankündigungen abgelegt sind /_announcements, /_projects, werden allerdings nicht mit umgezogen und müssen manuell kopiert und modifiziert werden.

Anpassen der Front Matter

Viele von mir gemachten Anpassungen in Jekyll funktionieren in Hugo entweder nicht richtig oder führen zum Abbruch des Bauvorganges - die Front Matter einer jeden Markdown-Datei muss also angepasst und teils bereinigt werden.

---
# Alt: So kann die Front matter einer Übersichtsseite in Jekyll aussehen
lang: de
title: Beitragsarchiv
subtitle: Diese Sammlung enthält alle meine Beiträge
layout: collection
collection: posts
permalink: /posts-archive/
entries_layout: grid
classes: wide
author_profile: false
---

In meinem Falle liegen einige Theme-abhänigen Parameter im Frontmatter vor wie layout, classes, author_profile. Der lang-Parameter aus meiner Internationalisierungserweiterung in Jekyll ist nicht einmal korrekte Hugo-Syntax: es erwartet die angezeigte Sprache entweder als Feld unter params: lang oder Ordnerweit. Auch andere, an den eigenen Geschmack angepasste Parameter können definiert und unter params mitgegeben werden.

Permalinks finden gar keinen Eingang mehr in die Front matter, stattdessen findet die Konfiguration zentral statt.

Eine Hugo-kompatible front matter kann so aussehen:

---
title: Beitragsarchiv
description: Diese Sammlung enthält alle meine Beiträge
layout: collection
---

Konfiguration des Theme

Eine Basis-Konfiguration meines Themes kann ich mit folgendem Kommando installieren:

➜ blog git:(main) ✗ git submodule add https://github.com/panr/hugo-theme-terminal ./themes/terminal

Zum Aktivieren muss ich es in der Hauptkonfiguration bekannt machen:

# /hugo.toml

# Add it only if you keep the theme in the `themes` directory.
# Remove it if you use the theme as a remote Hugo Module.
theme = "terminal"

Und schon baut Hugo für mich im Terminal-Theme und Originalfarben.

Dies ist nun nicht vertikal zentriert und für meinen Geschmack zu schmal ausgelegt, der Text recht klein und “meine” Blog-Farben sollen ebenfalls anders sein .

Daher erstelle ich eine .css-Datei, die einige Eigenschaften des Basis-Themes überschreibt. Sie muss im Ordner /static liegen und den Namen des Themes tragen.

/* /static/terminal.css */

:root{
 --background: #252a34;
 --background-highlight: #475064;
 --foreground: #d2eaef;
 --foreground-dimmed: #8b9ea2;
 --accent: #25a679;
 --accent-highlight: #79ae9c;
 --radius: 8px;
 --font-size: 1.35rem;
 --line-height: 1.8em;
}

/* Use system fonts, reduce transferred kB */
body{
 font-family: system-ui, -apple-system, "Segoe UI", Roboto, Arial, sans-serif !important; 
}

/* make content wider */
body .container{
 max-width: 70rem;
 width: 90%;
}

Und schon sieht es fast wie früher aus.

Organisation der Ordnerstruktur

Anders als bei der von mir verwendeten Jekyll-Version verfügt hugo über eingebaute Internationalisierung (i18n). Dafür muss ich meine Ordnerstruktur umbauen und explizit in /de und /en-Ordnerinhalte sortieren. Inhalte werden nun statt auf der höheren Ordner-Ebene direkt unter /_pages, /_announcements, /_posts im Ordner content gehalten, was die Sache übersichtlicher macht.

Vorher

.
├── _announcements
├── assets
│ ├── css
│ │ ├── fontawesome
│ │ ├── katex
│ │ ├── main.scss # <-- theme import, customization
│ │ └── webfonts
│ ├── js
│ │ ├── lunr
│ │ ├── _main.js
│ │ ├── main.min.js
│ │ ├── plugins
│ │ └── vendor
│ └── video
├── banner.js
├── CNAME
├── _config.yml
├── _data
│ ├── de
│ │ ├── l10n.yml
│ └── en
│ ├── l10n.yml
├── en
│ └── index.html
├── Gemfile
├── Gemfile.lock
├── _includes # <-- Layouts (HTML), partials, 3rd-party
├── index.html # <-- Landing page
├── _layouts # <-- Page layouts
├── _pages
│ ├── 404.md # <-- German version
│ ├── [...]
│ ├── en
│ │ ├── 404.md # <-- English version
│ │ ├── [...]
├── _posts/
│ └── en 
├── _projects/
├── _sass
│ ├── minimal-mistakes # <-- Styles (SCSS) for layouts and partials
│ ├── minimal-mistakes.scss
│ └── _video.scss
├── _site/ # <-- Build artifacts
├── staticman.yml

Nachher

Einen guten Überblick über die Ordnerstruktur bietet Hugos Dokumentation. Am wichtigsten für die tägliche Arbeit mit Artikeln und Aussehen der Website sind die Stammordner content, layouts und static.

.
├── archetypes
├── assets
├── content
│ ├── de
│ │ ├── about.md
│ │ ├── announcements/
│ │ ├── posts/
│ │ └── projects/
│ └── en
│ ├── about.md
│ ├── [...]
├── data
├── hugo.yml
├── layouts
│ ├── _default
│ │ ├── baseof.html # <-- defines header, add-ons, content, footer structure
│ │ ├── index.html # <-- landing page
│ │ ├── list.html # <-- grid view
│ │ └── single.html # <-- post view
│ ├── _markup
│ │ └── render-link.html # <-- link highlighting and function (referrer, tabs)
│ ├── _partials
│ │ ├── cover.html # <-- cover (thumbnail) image rendering
│ │ └── math.html # <-- math rendering (katex)
│ └── _shortcodes
│ ├── audio.html
│ ├── image.html
│ └── [...]
├── resources
│ └── _gen
│ └── assets/
├── static
│ ├── assets
│ │ ├── audio/
│ │ ├── css/ # <-- contains overrides for custom layouts 
│ │ ├── docs/
│ │ ├── images/
│ │ ├── js/ # <-- math (katex) JS lives here
│ │ └── video/
│ └── terminal.css # <-- Central theme override (colors, formatting, styling)
└── themes
 └── terminal # <-- GIT submodule: Vanilla "Terminal" theme

Bei beiden Lösungen werden Layouts in html und Stil/Format ind CSS definiert. Da ich bei Jekyll mehr Plugins verwenden musste, wird das Setup größer.

Manuelle Anpassungen: Shortcodes

Mit Shortcodes kann man in Hugo nicht-Text-Inhalte (Medien, Links, Formatierung, Stil) definieren, die dann nach definierter Vorschrift gerendert werden. Dafür legt man eine html-Datei an, welche den Dekorator definiert und entsprechende css-Klassen einbindet. Außerdem fügt man die gewünschte Formatierung in der überschreibenden Theme-css-Datei ein.

Da ich hier absolut kein Profi bin, probiere ich anschließend so lange herum, bis mir das Layouting gefällt und ich keine Artefakte/Überlagerungen mehr sehe.

.
├── layouts
│ └── _shortcodes
│ └── my-shortcode.html # <-- Custom shortcode file
├── static
│ └── terminal.css # <-- Central theme override (colors, formatting, styling)

Syntax: Hugo und Jekyll

Shortcodes werden bei Hugo in der Markdown-Datei mit folgender Syntax angezeigt:

{{< shortcode-html-filename options >}}
{{< image src="/path/to/image.avif" alt="Image: alt text" position="right" >}}

Im Vergleich dazu sehen Shortcode-ähnliche Dekoratoren in Jekyll für Liquid, die in Jekyll benutzte Beschreibungssprache so aus:

### Liquid in interpreter code
{% Liquid bracket syntax %}
### Liquid "shortcode" pendant
{% include gallery id="gallery" caption="Eindrücke von **MobFobAmp**. Zum Vergrößern anklicken." %}
### Liquid decorator for layouting
{:.list-inline}

image

Anwendungsbeispiel zur Bildanzeige. In der nächsten Zeile folgt ein zentriertes Bild.

Der klassische Bild-Dekorator für Markdown [Alt Text](/path/to/image) wird in Hugo standardmäßig als mittig zentriertes Bild ohne Textfluss gerendert. Für ein schönes Layouting benötige ich jedoch ein paar Varianten, welche etwas zusätzlichen Code in cascading style sheets und html erfordern.

Bild zentriert, ohne Textfluss
Bild links , Textfluss rechts
Bild rechts, Textfluss links

Zuerst besorgt sich Hugo Dateipfad und Bildtext. Anschließend liest es die gewünschte Formatierung aus der Markdown-Datei, welche mit der position-Variable angelegt wird. Anschließend wendet sie die image-wrapper Klasse aus der .css-Datei darauf an. Die Ausrichtung der Bilder gilt für bessere Lesbarkeit nur für die Desktop-Variante der Webseite (>684px).

Die Anpassungen des Themes gehen zur richtigen Darstellung von Bildern recht weit. Außerdem habe ich noch eine Galerie entwickelt, falls ein Post über sehr viele Bilder verfügt. Daher habe ich für die Bildformatierung und -Ausrichtung einen eigenen Artikel geschrieben.

audio

Zur Darstellung des Audio-Players verwende ich die im Browser implementierten Standards.

Your browser does not support the audio element.

Beispielplayer: Melodie auf dem E-Bass

{{- /* /layouts/_shortcodes/audio.html */ -}}

{{ $src := .Get "src" }}
{{ $caption := .Get "caption" | default "" }}

<div class="media-wrapper">
 <div class="media-container">
 <audio controls>
 <source src="{{ $src }}" type="audio/mp3">
 Your browser does not support the audio element.
 </audio>
 {{ with $caption }}
 <div class="media-title">{{ . }}</div>
 {{ end }}
 </div>
</div>

In css verwende ich einen Wrapper und Media-Container, um Titel im Rahmen des Players anzeigen zu können und die Formatierung zu erleichtern. Auch hier habe ich angepasstes Verhalten für ein “responsive layout” bei Mobilgeräten oder Änderungen der Größe des Browser-Fensters.

video

Das CSS ist identisch mit audio. Es gibt nur im html geringfügige Unterschiede. Der von mir verwendete Container unterstützt unter src= als Quellen sowohl “embed-Links” von Webseiten wie peertube als auch lokale Quelldateien.

Your browser does not support the video tag.

Video-Beispiel (lokal): Linearführungen mit Kugelumlauf

{{- /* /layouts/_shortcodes/video.html */ -}}

{{- $src := .Get "src" -}}
{{- $title := .Get "title" | default "" -}}
{{- $caption := .Get "caption" | default "" -}}

<div class="media-wrapper">
 <div class="media-container">
 {{- if hasPrefix $src "http" -}}
 <iframe src="{{ $src }}" frameborder="0" allowfullscreen></iframe>
 {{- else -}}
 <video controls>
 <source src="{{ $src }}" type="video/mp4">
 Your browser does not support the video tag.
 </video>
 {{- end -}}

 {{- if or $title $caption -}}
 <div class="media-title">
 {{- if $title -}}{{ $title }}{{- else -}}{{ $caption }}{{- end -}}
 </div>
 {{- end -}}
 </div>
</div>

Updates

Auch bei mir “altern” Inhalte. Manchmal wechsle ich Technologien oder Anbieter, und manchmal bewegen sich auch Dritte von Lösungen weg, deren Implementierung ich hier im Blog beschrieben habe. Daher habe ich update-shortcodes eingeführt.

Verlinkungen

Folgendes Verhalten wünsche ich mir für Links auf meinem Blog:

interne Links sollen im selben Tab geöffnet werden und die Nutzer weiterleiten.
interne Links sollen zu Seiten in derselben Sprache verweisen und nicht auf die Standard-Sprache oder zurück zur Hauptseite führen.
externe Links sollen mit einem Symbol gekennzeichnet werden: ↗
externe Links sollen in einem frischen Tab geöffnet werden: target="_blank"
exterme Links sollen weder auf die ursprünglichen Inhalte zugreifen noch den Quellverweis sehen können rel="noopener noreferrer"

Dafür erstelle ich unter /layouts/_markup die Datei render-link.html. Den Code hierfür und seine Hintergründe stelle ich in einem separaten Post vor: Hugo Multi-language: Interne Permalinks

Der Override für CSS sieht wie folgt aus.

/* /static/terminal.css */

.external-link .external-link-icon{
 display: inline-block;
 font-size: var(--font-size);
 vertical-align: middle;
 transform: translateY(-0.1em);
}

Manuelle Anpassungen: Partials

Partials kann man sich vorstellen wie die Layout-Bausteine für eine Hugo-Website. Sie werden unter /layouts/_partials abgelegt und überschreiben die Standards des verwendeten Themes. Dabei wird die Ursprungsdatei gar nicht mehr geladen, was ein Herüberkopieren der Originaldatei in den Ordner mit anschließender manueller Anpassung empfehlenswert macht.

index

Die Startseite für den Blog ist komplett selbt geschrieben und liegt nicht in Markdown, sondern in html vor. Sie zeigt ihre Inhalte anders an als alle anderen Blog-Seiten und daher lohnte es sich für mich nicht, Templates zu programmieren. In der entsprechenden /layouts/_partials/index.html lade ich dafür notwendige scss und css-Dateien und gebe die Struktur der Seite vor. Die folgende Tabelle gibt einen Überblick über meine Änderungen.

File	Purpose	Customization
cover	thumbnail / cover image for overview pages, lists, and grids	Add custom cover image decorator, alt text
head	Defines Favicon, search console, page parameters, feeds etc.	Custom favicon path
header	Page header containing menu, logo, navigation etc.	Add logo and subtitle to menu, lang selector
logo	Custom page logo, title, subtitle	Full
math	Displays math content with Latex/Katex	None, implement math support

math

Mein Blog soll mathematische Notation unterstützen. Dafür benutze ich Katex

{{- /* /layouts/_partials/math.html */ -}}

<link rel="stylesheet" href="/assets/css/katex.min.css">
<script defer src="/assets/js/katex.min.js"></script>
<script defer src="/assets/js/contrib/auto-render.min.js" onload="renderMathInElement(document.body);"></script>

<script>
 document.addEventListener("DOMContentLoaded", function() {
 renderMathInElement(document.body, {
 delimiters: [
 {left: '\\[', right: '\\]', display: true}, // block
 {left: '$$', right: '$$', display: true}, // block
 {left: '\\(', right: '\\)', display: false}, // inline
 ],
 throwOnError : false
 });
 });
</script>

cover image

Unter der Bezeichnung cover verstehe ich ein Titelbild eines Blog-Posts. Es wird in Übersichtsseiten, Artikel- und Tag-Listen etc. angezeigt und soll die Inhalte des Blog-posts unterstützend beschreiben. Auch mein RSS-Feed soll diese Bilder für die Übersicht verschiedener Artikel auf Endgeräten meiner Leserschaft verwenden.

Es ist besonders stark komprimiert und benötigt wenig Übertragungsbandbreite. Daher ist seine Auflösung gering (440x220 oder 640x352). Für einen einheitlichen Look sind sie zudem stets monochrom.

Die Markdown-Syntax zum Einbinden des Covers sehe ich wie folgt vor:

---
cover_alt: 'Image: Hugo console build output. It shows a full build time below 2sec. (~90% reduction over build time with Jekyll)'
cover: /assets/images/migrating-hugo-to-jekyll/hugo-jekyll-build-compare-cover.avif
---

Anschließend erstelle ich unter layouts/_partials die Datei cover.html und schreibe folgenden Code hinein:

{{- /* /layouts/_partials/cover.html */ -}}

{{- /* Handles cover-image generation */ -}}

{{- $cover := false -}}
{{- $autoCover := default $.Site.Params.autoCover false }}

{{- if index .Params "cover" -}}
 {{- if .Resources.GetMatch .Params.Cover }}
 {{- $cover = (.Resources.GetMatch .Params.Cover).RelPermalink -}}
 {{- else -}}
 {{- $cover = absURL .Params.Cover -}}
 {{- end -}}
{{- else if $.Site.Params.AutoCover -}}
 {{- if (not .Params.Cover) -}}
 {{- if .Resources.GetMatch "cover.*" -}}
 {{- $cover = (.Resources.GetMatch "cover.*").RelPermalink -}}
 {{- end -}}
 {{- end -}}
{{- end -}}

{{if $cover -}}
 <!-- Cover image found -->
 <img src="{{ $cover }}"
 class="post-cover"
 alt="{{ .Params.cover_alt | plainify | default (.Description| plainify) }}"
 title="{{ .Params.CoverCredit |plainify|default (.Title | plainify) }}" />
{{- end }}

Der Code sucht und extrahiert den Pfad zum Coverbild. Sollte ein valider Pfad gefunden werden, wird es als post-cover mit entsprechendem CSS angezeigt.

Dem XML-Template füge ich als erstes Element innerhalb des <description>-Tags das Coverbild hinzu. Erst danach kommt der eigentliche Artikel. Die meisten Feed Reader nehmen dieses Bild dann als Cover für ihre Übersichten.

Manuelle Anpassungen: Layouts

Damit sich meine Seite in Hugo weiterhin ganz ähnlich anfüllt wie zuvor in Jekyll muss ich in den Layouts ein paar Änderungen vornehmen. Im Folgenden habe ich sie beschrieben.

baseof.html

Hier werden die Basis-Inhalte definiert. Definitionen für Kopf- und Fußzeile werden importiert und Stylesheets eingebunden. Die allermeisten oben beschriebenen Änderungen werden an dieser Stelle importiert.

{{- /* /layouts/baseof.html */ -}}

<!DOCTYPE html>
<html lang="{{ $.Site.Language }}">
<head>
 {{ if .Param "math" }}
 {{ partialCached "math.html" . }}
 {{ end }}
 {{ block "title" . }}
 <title>{{ if .IsHome }}{{ $.Site.Title }}{{ else }}{{ .Title }} :: {{ $.Site.Title }}{{ end }}</title>
 {{ end }}
 {{ partial "head.html" . }}
 <link rel="stylesheet" href="{{ "/assets/css/gallery.css" | relURL }}"> 
 <link rel="stylesheet" href="{{ "/assets/css/media.css" | relURL }}">
</head>
<body>
{{ $container := cond ($.Site.Params.FullWidthTheme | default false) "container full" (cond ($.Site.Params.CenterTheme | default false) "container center" "container") }}

<div class="{{- $container -}}{{- cond ($.Site.Params.oneHeadingSize | default false) " headings--one-size" "" }}">

 {{ partial "header.html" . }}

 <div class="content">
 {{ block "main" . }}
 {{ end }}
 </div>

 {{ block "footer" . }}
 {{ partial "footer.html" . }}
 {{ end }}
</div>

</body>
</html>

list.html

Für Übersichtsseiten wie Artikel, Tags, Projekte benötige ich eine Listenansicht. Dabei möchte ich je vier Artikel in einer Zeile anzeigen. Jeder Artikel bekommt ein eigenes “Kärtchen” mit Titelbild (cover), Titel, Kurzbeschreibung und - falls Verfügbar - weiteren Details wie Lesezeit. Hugos paginator crawlt den entsprechenden Ordner und stellt die Inhalte zusammen, wärend mein Stylesheet list.css Formatierung und Anzeige übernimmt.

{{- /* /layouts/_default/list.html */ -}}

{{ define "main" }}
 <link rel="stylesheet" href="{{ "/assets/css/list.css" | relURL }}">
 {{ with .Content }}
 <div class="index-content">
 {{ . }}
 </div>
 {{ end }}

 <div class="posts posts-grid">
 {{ range .Paginator.Pages }}
 <article class="post on-list">
 <a href="{{ .Permalink }}" class="post-card" aria-label="{{ .Title }}">
 {{ partial "cover.html" . }}

 <div class="post-card-body">
 <h4 class="post-title">
 {{ .Title | markdownify }}
 </h4>

 <div class="post-excerpt">
 {{ if .Description }}
 <p>{{ .Description }}</p>
 {{ end }}
 </div>

 {{- if and (.Param "readingTime") (eq (.Param "readingTime") true) -}}
 <div class="post-reading-time">
 {{ .ReadingTime }} {{ $.Site.Params.minuteReadingTime | default "min read" }}
 </div>
 {{- end -}}
 </div>
 </a>
 </article>
 {{ end }}

 {{ partial "pagination.html" . }}
 </div>
{{ end }}

single.html

Meine single,html ist fast identisch mit der Standardimplementierung von terminal. Ich habe lediglich die Möglichkeit hinzugefügt, ein zum Titel gehöriges “banner-image” zu haben, und importiere die _partial/cover.html-Vorschrift zum Laden eines Coverbildes.

<article class="post">
 {{ with .Params.banner }}
 <img
 src="{{ . }}"
 class="post-banner"
 alt="{{ $.Params.banner_alt | plainify | default ' ' }}"
 />
 {{ end }}

Bei all den Änderungen könnte man überlegen, ein eigenes Theme zu forken… 🤔

Qualitätskontrolle

Neu ist für meine Website auch, dass ich auf tote Links prüfe. Die Seite ist erwachsen geworden und verfügt über so viele interne und externe Verlinkungen, dass dies manuell nicht mehr sinnvoll durchzuführen ist. Mit welchem Tool ich vorgehe und wie ich dabei Hugo-Eigenheiten berücksichtige, dokumentiert der Artikel zum Thema htmltest-Konfiguration für Hugo.

Veröffentlichung

Auch für Hugo benötige ich eine automatisierte Pipeline. Sobald ich eine Änderung nach main schiebe, soll die Webseite automatisch neu gebaut und ausgeliefert werden. Wie das genau funktioniert beschreibe ich im Artikel Hugo-Website mit Github Actions in Docker bauen und ausliefern.

Leistung

Was der ganze Aufwand jetzt gebracht hat? Für user ist Aussehen und Navigation sehr ähnlich zur Website in Jekyll. Die Verbesserungen machen sich allerdings durch schnellere Ladezeiten, geringere zu übertragende Datenmengen und bessere Übersichtlichkeit aus. Einendetaillierten Vergleich zwischen nehme ich im Artikel Jekyll vs. Hugo Benchmarking vor.

Hugo: Bilder im Textfluss ausrichten

Schallbert — Sat, 29 Aug 2026

Warum das Ganze?

Mein Theme kann aus dem klassischen Markdown ![Image Alt Text](/path/to/image/) keine Bildformatierung und -Positionierung ableiten. Das benötige ich aber, um Bilder links, mittig, und rechts zu platzieren - mit und ohne Textfluss. Also muss ich selbst ran und mir etwas programmieren.

Einstieg in shortcodes, layouts, css

Einen Überblick verschaffe ich mir auf cshire und stelle schnell fest, dass mein erster Versuch per /layouts/render-image.html nicht funktioniert.

Debugging

Auf diese Weise stelle ich fest, ob render-image.html überhaupt gelesen und angewendet wird - und zwar unabhängig von CSS:

<div style="border: 3px dashed red; padding: 10px; margin: 10px; font-weight: bold;">
 RENDER-IMAGE.HTML IS BEING READ!
</div>

Das funktioniert. Also muss Hugo irgendwas in der Markdown-Verarbeitung entgehen.

Ursachenbehebung

Ich sehe nun, dass Hugo zwar das Layout rendert, meine Bilder aber nicht richtig auswertet. Warum? Weil zur Auswertung der Bilder ein Auslöser, genannt shortcode, fehlt. Shortcodes in Hugo werden mit {{ <shortcode-name> parameter1="String" parametern="string" }} im Markdown angelegt, mittels der entsprechenden Vorschrift /layouts/shortcodes/<shortcode-name>.html ausgewertet und anschließend durch CSS interpretiert dargestellt.

Shortcode: image.html

Ich habe mir also ein Shortcode-Template gebastelt, sodass ich dem Bild ein paar weitere Parameter zusätzlich zu Quelldatei src und Alternativtext alt mitgeben kann: position, caption, attrid, attrlink. Position und Titel des Bildes sind selbsterklärend. Eine Attributionsmöglichkeit wollte ich für nicht selbsterstellte Bilder haben. Bei diesen greife ich entweder auf offene Inhalte unter Rechtsverhältnissen wie den creative commons zu oder besorge mir vorab das schriftliche Einverständnis der Urheberrechtsinhaberschaft.

{{- /* layouts/_shortcodes/image.html */ -}}

{{- $src := .Get "src" -}}
{{- $alt := .Get "alt" | default "" -}}
{{- $position := .Get "position" | default "center" -}}
{{- $caption := .Get "caption" -}}
{{- $attrid := .Get "attrid" -}}
{{- $attrlink := .Get "attrlink" -}}

<figure class="media-frame media-frame--{{ $position }}">
 <img src="{{ $src }}" alt="{{ $alt }}">

 {{- if $caption -}}
 <figcaption class="media-caption">
 <span class="caption-text">{{ $caption }}</span>
 {{- if and $attrid $attrlink -}}
 <a
 href="{{ $attrlink }}"
 class="attr-link"
 aria-label="Attribution {{ $attrid }}"
 >
 <sup class="attr-id">[{{ $attrid }}]</sup>
 </a>
 {{- end -}}
 </figcaption>
 {{- end -}}
</figure>

Diese Vorlage liest die mitgegebenen Parameter aus dem Shortcode aus und packt das Bild <img> in einen Rahmen <figure class="media-frame">. Dieser trägt die Positionsinformation. Sofern ein Bildtitel und/oder eine Attribution vorliegt, wird dies in der figcaption class="media-caption" abgebildet.

Verwendung des Shortcodes

In Markdown würde ein Bild mit “Vollausstattung” nun so aussehen:

{{< image src="/path/to/image.jpg" 
alt="Example placeholder image for shortcode demonstration purposes" 
caption="Shortcode demo image" 
attrid="1" attrlink="https://example.com/" 
position="right" >}}

Migration

Nur wie komme ich jetzt von den bisher von mir in Jekyll verwendeten ![alt](/path/to/image) {: .align-center} in das oben angegebene Format?

Mit einem Skript! Dafür erstelle ich mir ein python-Programm, welches durch jeden meiner Artikel kämmt und dort nach Bildern in der oben angegebenen Formatierung sucht. Bei einem Treffer extrahiert es src, alt, position und ersetzt den kompletten Ausdruck zu einem Hugo-Shortcode-Äquivalent.

import os
import re
from pathlib import Path

# spaces/tabs only, no newlines
SPACES = r'[ \t]*'

IMG_WITH_OPTIONAL_ALIGN = re.compile(
 r'!\[([^\]]*?)\]\(([^)]*?)\)' # alt, src
 + SPACES + # optional spaces/tabs before decorator
 r'(?:\{:' + SPACES + # literal "{:"
 r'[^}\n]*?\.align-(center|left|right)\b[^}\n]*?' # decorator body (no newlines)
 r'\})?' # optional "}"
)

def convert_image_alignments(directory):
 def repl(m):
 alt = m.group(1).replace('"', "'")
 src = m.group(2)
 position = m.group(3) or ''
 # return built Hugo shortcode. Escape Python f-string curly brace { with {{.
 return f'{{{{< image src="{src}" alt="{alt}" position="{position}" >}}}}'

 for root, _, files in os.walk(directory):
 for file in files:
 if not file.endswith('.md'):
 continue

 filepath = Path(root) / file
 content = filepath.read_text(encoding='utf-8')

 new_content = IMG_WITH_OPTIONAL_ALIGN.sub(repl, content)
 if new_content != content:
 filepath.write_text(new_content, encoding='utf-8')
 print(f"Updated: {filepath}")

if __name__ == "__main__":
 project_root = input("Enter the path to your project root: ").strip()
 if os.path.isdir(project_root):
 convert_image_alignments(project_root)
 print("Conversion complete!")
 else:
 print("Invalid directory path.")

Bei den Regexes habe ich mir von Mistral helfen lassen, ansonsten ist das Skript aber einfach gehalten.

Bilder mit Titel und/oder Attribution waren in Jekyll als figure deklariert. Auch für diese schreibe ich ein ganz ähnliches Skript und lasse es bei der Migration durchlaufen.

CSS

Kommen wir zur Darstellung der Bilder. Ich erstelle eine seitenfüllende CSS-Datei /assets/css/media.css, welche außerdem Größe und Formatierung anderer eingebetteter Medien wie Audio- und Videodateien einheitlich sowohl für die mobile- als auch die Desktopansicht regeln soll. Dafür greift sie auf die in der Vorlage definierten class=-Attribute zu.

Ich nehme zur Erläuterung mal einen Ausschnitt aus der Datei heraus: Hier lege ich das Verhalten des media-frame-Objektes fest. Jedes Asset (Bild, Video, Audio) wird in einem Rahmen eingebettet, welcher der Darstellung die nötige Luft verschafft. Mit dem Attribut position= wird definiert, wo und wie dargestellt werden soll.

Dabei sind die Inhalte standardmäßig zentriert und werden solange sie nicht größer sind als die maximale Textbreite in ihrer nativen Auflösung dargestellt.

.media-frame img,
.media-frame audio,
.media-frame video {
 display: block;
 width: auto;
 max-width: 100%;
 height: auto;

 margin: 0;
 padding: 0;
 border: 0;
 border-radius: 0;
}

.media-frame--center {
 margin-left: auto;
 margin-right: auto;
}

/* Left/Right align only for Non-mobile use */
@media (min-width: 768px) {
 .media-frame--left {
 float: left;
 max-width: 60%;
 margin-top: 0.35em;
 margin-right: 1rem;
 margin-bottom: 0.75rem;
 }

 .media-frame--right {
 float: right;
 max-width: 60%;
 margin-top: 0.35em;
 margin-left: 1rem;
 margin-bottom: 0.75rem;
 }
}

Auf einer Seite ausgerichtete Bilder werden in der Breite begrenzt, denn es soll noch Textfluss drum herum stattfinden. Außerdem werden minimale Abstände zu anderen Objekten definiert, damit sich bei aufeinanderfolgenden Medien nicht Rahmen an Rahmen reibt. In der mobilen Ansicht ist der Platz so beengt, dass Bilder stets zentriert dargestellt werden.

Galerie

Für den Fall, dass ich viele Bilder an einer zentralen Stelle anzeigen will, erstelle ich mir zusätzlich einen gallery-Shortcode und zugehöriges CSS. Die Galerie zeigt Bilder in einem Raster an. Bewegt man die Maus über eines der Bilder, so erscheint es heller als die anderen. Klickt man auf ein Bild, so erscheint es in groß am unteren Rand der Galerie, wobei der oben bereits beschriebene media-Shortcode wiederverwendet wird.

Die darzustellenden Bilder werden in der front matter des Markdown-Dokumentes als Liste per src und alt angelegt. Hier ein Ausschnitt aus der Vorlage zur Auswertung des Shortcodes.

<section class="hugo-gallery">
 <div class="hugo-gallery__frame">
 <div class="hugo-gallery__grid" role="list">
 {{- range $i, $img := $items -}}
 {{- $src := $img.src -}}
 {{- $alt := $img.alt | default (printf "Gallery image %d" (add $i 1)) -}}

 {{- $thumbURL := $src -}}
 {{- $p := strings.TrimPrefix $src "/assets/" -}}

 {{- with resources.Get $p -}}
 {{- $thumb := .Fit "400x220" -}}
 {{- $thumbURL = $thumb.RelPermalink -}}
 {{- end -}}

 <a
 class="hugo-gallery__thumb"
 href="#gallery-full-{{ $i }}"
 aria-label="{{ $alt }}">
 <img
 src="{{ $thumbURL }}"
 alt="{{ $alt }}"
 class="hugo-gallery__thumb-img"
 loading="lazy">
 </a>
 {{- end -}}
 </div>

Ich iteriere durch alle in der Frontmatter definierten Bilder, begrenze ihre Größe auf handliche 400x220px und ordne sie in einem Raster class=hugo-gallery__grid an.

Tests

Das Erstellen der Vorlagen ging verhältnismäßig schnell. Mit CSS stehe ich aber auf Kriegsfuß. Ständig funkt mir irgendein Override aus einer anderen Datei dazwischen oder ich komme mir selbst mit den Styles im Basis-CSS in die Quere. Daher benötige ich einen Ort zum Testen von Formatierung und Anordnung.

Daher habe ich eine Bild-testseite erstellt. Neugierig? Prüfen der Darstellung von Medien in Hugo

htmltest-Konfiguration für Hugo

Schallbert — Mon, 10 Aug 2026

Nun bin ich mit dem Umzug meiner Website zu Hugo fast fertig. Ich musste mehrere Anpassungen in der Frontmatter jedes Artikel vornehmen, damit sie in Hugo ähnliche Funktionen aufweisen wie zuvor mit Jekyll. Es ergaben sich einige Änderungen in der Ordnerstruktur teils durch die Migration, teils auch durch meine Erfahrungen als Autor, sodass auf dem Weg einige Links in praktisch jedem meiner Artikel zu überarbeiten waren. Inzwischen habe ich fast 340 davon, wenn man die Übersetzungen mitzählt.

Der schieren Masse der Links komme ich ohne weitere Hilfsmittel nicht bei. Also benötige ich Werkzeug.

htmltest

Htmltest ist ein Hilfsprogramm, das HTML-Dateien nach Problemen durchsuchen kann. Unter anderem spürt es defekte Links auf. Ich installiere es per

# Red Hat-based Linux package manager install command
sudo dnf install htmltest

und wende es auf die von Hugo “gebauten” HTMl-Dateien im /public-Verzeichnis an:

htmltest public/
# [...]
✘✘✘ failed in 2.890119823s
2612 errors in 337 documents

Das sind aber ganz schön viele Fehler! Die Darreichungsform erscheint mir außerdem ziemlich unübersichtlich, siehe Bild.

Ausgabe in Datei umleiten

Folglich tue ich mich erstmal ziemlich schwer mit diesem Werkzeug. Ich hatte angenommen, dass mir ein paar Links kaputtgegangen sind und nicht mit tausenden Fehlern gerechnet. Also fiel ich dem typischen not-invented-here Syndrom anheim und programmierte selbst ein Werkzeug in python, welches sich im Nachhinein als nicht gut genug entpuppte. Kurzgesagt:

Htmltest ist ein tolles und unglaublich schnelles Werkzeug. Wenn man dessen Ausgabe leserlich macht und richtig deutet, kann man damit ziemlich glücklich werden. Mit ein bisschen Herumprobieren gelange ich zu folgendem Befehl:

htmltest public/ 2>&1 | ansi2html > htmltest-output.html

Bedeutung: “Führe htmltest im /public/-Ordner aus. Leite Fehler aus stderr in die Ausgabe stdout um. Reiche die Ausgabe an ansi2html¹ weiter. Schreibe dessen Ausgabe in eine Datei namens htmltest-output.html.

Das sieht doch so schon viel besser aus!

Fehlerkategorien

Die mit htmltest gefundene Fehler lassen sich für meine Zwecke in ein paar wenige Kategorien sortieren:

Hugo-intern bedingte Fehler wie durch livereload.js verursachte target does not exist-Meldungen.
Unvollständige Links, die zwar in der Praxis funktionieren, aber href lacks trailing slash-Fehler erzeugen. Diese Art Fehler machen bei mir den Löwenanteil der berichteten Probleme aus.
Lookup-Fehler GET <src> [...] failure in name resolution, bei fehlender Verbindung, unzureichenden Rechten, aktiver Bot-Abwehr oder wenn der Zielserver offline ist
Harte, durch defekte Links erzeugte target does not exist-Fehler. Genau diese wollte ich eigentlich beheben.

Das Log bereinigen

Wie bekomme ich nun nur noch Fehler der vierten Kategorie angezeigt? Durch ein paar Änderungen in den Werkeugen und die Beseitigung der Trailing-Slash-Fehler.

Fehler der Kategorie 1, die durch Hugos nützliche livereload-Funktion hervorgerufen werden, sehen so aus:

 target does not exist --- en/tags/tools/index.html --> /livereload.js?mindelay=10&v=2&port=1313&path=livereload

LiveReload ist diejenige Funktion, die mir ständiges F5-Tippen im Browserfenster erspart, wenn Hugo eine meiner Änderungen nach dem Speichern der Markdown-Datei baut. Für den Test kann ich es jedoch kurz deaktivieren. Die folgende Lösung reduziert die Anzahl erzeugter Fehler um eins pro html-Seite.

hugo server --disableLiveReload

Lookup-Fehler der Kategorie 3 vermeide ich durch einen Fokus auf interne Links worüber ich die vollständige Kontrolle habe. Hierbei hilft mir der Parameter -s, --skip-external in htmltest:

htmltest -s public/ 2>&1 | ansi2html > htmltest-output.html
# [...]
✘✘✘ failed in 494.7678ms
446 errors in 337 documents

Tote externe Links kann ich zu einem späteren Zeitpunkt beheben; nun will ich erstmal die durch die Migration entstandenen Probleme lösen.

“Missing trailing slash”: Fehlerbehebung per Markup

Mit den vielen href lacks trailing slash-Fehlern tue ich mich lange zeit schwer, müsste ich doch an fast jeden Markdown-Link in jedem Artikel ein / anfügen. Zum Glück finde ich eine Lösung in meinem Markup render-link.html:

{{- /* /layouts/_markup/render-link.html */ -}}

{{- $url := .Destination | safeURL -}}
{{- $is_external := or (strings.HasPrefix $url "http://") (strings.HasPrefix $url "https://") -}}
{{- $is_anchor := strings.HasPrefix $url "#" -}}
{{- $is_asset := strings.HasPrefix $url "/assets/" -}}

[...]

{{- /* Add / to internal paths that have no file extension */ -}}
{{- if and (not $is_external) (not $is_anchor) (not $is_asset) -}}
 {{- $parsed := urls.Parse $url -}}
 {{- if and $parsed (not (strings.HasSuffix $parsed.Path "/")) (eq (path.Ext $parsed.Path) "") -}}
 {{- $url = printf "%s/" $url -}}
 {{- end -}}
{{- end -}}

[...]

Bedeutung: Interne Links, die weder auf Überschriften is_anchor noch Mediendateien is_asset verweisen, bekommen genau dann ein / angehangen, wenn sie eine korrekte Syntax aufweisen parsed und noch keinen Slash am Ende der URL vorweisen können.

Dies löst 95% der Fehlermeldungen durch weniger hässliches html. Die restlichen 5% hole ich mir durch Anhängen von ein paar Slashes in der Hugo-Konfiguration. Beispiele:

# hugo.yml
url: "/en/" # /en -> /en/ 
logoHomeLink: "/en/" # /en -> /en/

Fertig! Übrig bleiben nur noch harte, interne Fehler.

htmltest -s public/ 2>&1 | ansi2html > htmltest-output.html
# [...]
✘✘✘ failed in 359.28ms
102 errors in 84 documents

Manuelles Suchen und Beheben

Was nun folgt ist reine Fleißarbeit. Ich öffne das Zieldokument (also jenes, auf welches per Link verwiesen wird) und schaue mir an, ob zum Beispiel Überschriftenlinks zwischen verschiedenen Sprachen uneinheitlich sind. Falls ja, füge ich individuelle Anchor-Links an die Überschrift an.

### Überschrift {#heading3}

Falls in der Zieldatei alles paletti ist, öffne ich zusätzlich alle Quelldateien, die den defekten Link verwenden. Dort korrigiere ich den Link manuell. In den meisten Fällen befindet sich die Zieldatei inzwischen in einem anderen Ordner, oder der Sprachpräfix ist falsch gesetzt.

Das Ergebnis

Nach ein paar Stunden anstrengender und dröger Handrbeit werde ich belohnt:

htmltest public/ -s 2>&1
Skipping the checking of external links.
htmltest started at 10:51:23 on public
========================================================================
✔✔✔ passed in 238.970354ms
tested 338 documents

Bald kann ich mit meiner neuen alten Seite online gehen!

ansi2html bzw. colorized-logs ist ein Hilfsprogramm, welches Konsolenausgabe inkl. Formatierung und Textfarben in html umwandelt. ↩︎

Hugo Multi-Lang: Interne Permalinks

Schallbert — Mon, 27 Jul 2026

Wer in Hugo wie ich einen mehrsprachigen Blog baut, könnte folgendes Problem kennen:

Interne Links in Artikeln verschiedener Sprachen verweisen nur auf Seiten in der Standard-Sprache.

Konfiguration

Grundlage für das Problem ist die folgende Einstellung:

# hugo.yml

defaultContentLanguage: "de"
defaultContentLanguageInSubdir: false
disableDefaultLanguageRedirect: true

Meine Standardsprache ist Deutsch und zugehörige Artikel werden in das Hauptverzeichnis des Blogs gebaut. Eine Weiterleitung in das Sprachverzeichnis /de findet nicht statt.

Die Verzeichnisstruktur lautet:

├── content
│ ├── de
│ │ ├── about.md
│ │ ├── announcements
│ │ ├── legal.md
│ │ ├── posts
│ │ ├── privacy.md
│ │ └── projects
│ └── en
│ ├── about.md
│ ├── legal.md
│ ├── posts
│ ├── privacy.md
│ └── projects

Das Problem mit der Standardsprache

Ich halte Artikel durch Nutzung von slug in meiner Standardsprache unter Adressen erreichbar wie example.com/my-post, example.com/my-2nd-post/. In der Zweitsprache hingegen erscheinen sie als example.com/en/my-post, example.com/en/my-2nd-post/.

Wenn ich zwei Artikel nun intern verlinken möchte, dann verweist der Link stets auf den Artikel meiner Standardsprache.

# English version of my post
# example.com/en/my-post
---
slug: my-post

---
Post's English content
[2nd](/my-2nd-post)

Ich erreiche damit statt des gewünschten /en/my-2nd-post nur die deutsche Version /my-2nd-post. Das finde ich blöd, denn so müsste ich jeden Link in allen Artikeln manuell anpassen. Leider scheint Hugo dafür keine eingebaute Lösung mitzubringen. Also erstelle ich mir eine Vorschrift, wie Links gerendert werden sollen:

{{- /* /layouts/_markup/render-link.html */ -}}

Lösung: Sprachabhängige Link-Prefixes

Dort soll folgendes passieren: Wenn beim Bauen ein relativer Link innerhalb der Seite gefunden wird, so ist genau dann ein Sprachpräfix wie /en vor diesen Link zu setzen, wenn die Sprache der zu rendernden Seite nicht der Standardsprache entspricht (denn für letztere benötige ich wegen defaultContentLanguageInSubdir: false keinen Sprachpräfix).

Standardsprache auslesen

Nur wie komme ich an die Standardsprache? Die Parameter defaultContentLanguage sind in Templates nicht zugänglich. Nach längerer Recherche finde ich eine passende Lösung für das Problem in der Hugo community: Die Standardsprache ist meist die erste Sprache des gewichtsbasierten Index (welcher die Sprachen nach Reihenfolge erscheinen lässt): index .Page.Site.Home.AllTranslations 0 Wenn ich diesen nun auslese, ist die “erste” meine Standardsprache.

Code für render-link.html

{{- /* /layouts/_markup/render-link.html */ -}}

{{- $url := .Destination | safeURL -}}
{{- $currentLang := .Page.Language.Locale -}}

{{- $is_external := or (strings.HasPrefix $url "http://") (strings.HasPrefix $url "https://") -}}
{{- $is_anchor := strings.HasPrefix $url "#" -}}
{{- $is_asset := strings.HasPrefix $url "/assets/" -}}
{{- $is_lang_prefixed := strings.HasPrefix $url (printf "/%s/" $currentLang) -}}

{{- if $is_anchor -}}
 {{- $url = printf "%s%s" .Page.RelPermalink $url -}}
{{- else -}}
 {{- if not $is_external -}}
 {{- if and (not $is_lang_prefixed) (not $is_asset) (not .Page.Language.IsDefault) -}}
 {{- $url = printf "/%s%s" $currentLang $url -}}
 {{- end -}}
 {{- end -}}
{{- end -}}

{{- /* Add / to internal paths that have no file extension */ -}}
{{- if and (not $is_external) (not $is_anchor) (not $is_asset) -}}
 {{- $parsed := urls.Parse $url -}}
 {{- if and $parsed (not (strings.HasSuffix $parsed.Path "/")) (eq (path.Ext $parsed.Path) "") -}}
 {{- $url = printf "%s/" $url -}}
 {{- end -}}
{{- end -}}

<a href="{{ $url | relURL }}"{{ if $is_external }} target="_blank" rel="noopener noreferrer" class="external-link"{{ end }}>
 {{- .Text | safeHTML -}}
 {{- if $is_external -}}
 <span class="external-link-icon" aria-hidden="true">↗</span>
 {{- end -}}
</a>

Solange die Standardsprache und der Gewichtsindex übereinstimmen, d.h. die Standardsprache ganz oben auftaucht, funktioniert dies prima.

Zusatzfunktionen

Was der Code sonst noch macht:

Prüfung, ob Links nach “extern”, also von meiner Site weg gehen. Jene bekommen dann ein eigenes Fenster und den Indikator ↗.
Prüfung, ob der Link auf eine Überschrift “anchor” führt. Details dazu siehe unten.
Prüfung, ob der Link zu einer (Medien-)Datei “asset” führt. Asset-Links werden nicht modifiziert.

Handelt es sich um einen Überschriftslink, so wird dieser gegebenenfalls auf die vollständige URL ergänzt. Das geschieht nach folgendem Schema: #heading --> /<opt_lang>/<opt_category>/<title>/#heading

Richtig auflösende Permalinks auf Überschriften

Auch für hochspezielle Permalinks innerhalb einer Seite habe ich eine Lösung gefunden. Nehmen wir an, ich habe verschiedensprachige Überschriften :

---
# German
# content/de/posts/yyyy-mm-dd-hugo-create-language-specific-permalinks.md

description: Mit _markup interne Links richtig routen
title: "Hugo Multi-Lang: Interne Permalinks"
slug: hugo-create-language-specific-permalinks
---

## Richtig auflösende Permalinks auf Überschriften {#permalinks}
Lorem Ipsum...

---
# English
# /content/en/posts/yyyy-mm-dd-hugo-create-language-specific-permalinks.md

description: Routing internal links with _markup
title: "Hugo Multi-Lang: Internal Permalinks"
slug: hugo-create-language-specific-permalinks
---

## Correct Permalinks to headings {#permalinks}
Lorem Ipsum...

Dann sollte ein Klick auf diesen Link zurück zur Überschrift #permalinks sprachunabhängig wieder zurück zur Überschrift führen. Schlüssel für diese Lösung ist das Einführen einer Überschriftsdefinition (Heading-ID) in Markdown, in diesem Fall {#permalinks}.

Funktioniert so noch nicht.

Weil #permalinks auf <blog's baseurl>/#permalinks verweist und somit der Link auf die aktuelle Seite fehlt. Doch auch das bekommen wir hin: Ich erweitere den Link-Renderer um ein paar Zeilen Code und gebe die aktuelle Seiten-URL als Präfix hinzu.

Code für render-link.html mit Unterstützung für Überschriften

{{- $is_anchor := strings.HasPrefix $url "#" -}}

{{- if $is_anchor -}}
 {{- $url = printf "%s%s" .Page.RelPermalink $url -}}
{{- end -}}

Nun wird (#permalinks)erweitert zu /hugo-create-language-specific-permalinks/#permalinks, sodass der Link endlich zum Ziel führt.

Scheitern von SSH-Verbindungen

Schallbert — Fri, 12 Jun 2026

In diesem kurzen Artikel geht es um Fehler beim Aufbau einer SSH-Verbindung. Egal ob andere Rechner, Server oder Dienste wie Versionsverwaltung - die Fehlermeldungen und zugehörige Lösungen sind meist gleich. Weiterlesen lohnt sich allerdings nur, wenn gängige Hilfeseiten wie Githubs troubleshooting-ssh nicht die erwünschte Lösung brachte.

Problem: “No Route To Host”

Die Konsolenausgabe zeigt (im lokalen Netz):

➜ blog git:(article) ✗ ssh 192.168.0.27
ssh: connect to host 192.168.0.27 port 22: No route to host

Oder (in einem entfernten Netz)

➜ blog git:(article) ✗ ssh 1.2.3.4
ssh: connect to host 1.2.3.4 port 22: Network is unreachable

Ursache ist sehr wahrscheinlich eine falsch eingegebene IP oder eine fehlgeschlagene DNS-Namensauflösung. Im lokalen Netz ist ein realistischer Grund, dass der Teilnehmer abgeschaltet ist und der Router ihn daher nicht erreichen kann. Abhilfe schafft meist eine Korrektur der Zieladresse, Einschalten des Ziels oder Update der Routing-Tabelle.

Problem: Connection Refused

Konsolenausgabe:

➜ blog git:(article) ✗ git push gitea
ssh: connect to host git.schallbert.de port 22: Connection refused
fatal: Could not read from remote repository.

Hier kann nicht mal eine Verbindung zum Ziel hergestellt werden. Man ist also “vor” der Authentisierung schon gescheitert. Meiner Erfahrung nach werden solche Fehler aus drei Gründen erzeugt:

Der Host ist noch nicht bereit. Er bootet beispielsweise gerade (Netzwerkkarte ist an) aber der SSH-Dienst ist noch nicht hochgefahren. Hier hilft meist: abwarten.
Eine Firewall, ein Rate Limiter, oder Dienste wie fail2ban weisen die Verbindung ab (REJECT). Die Gründe hierfür sind meist zu viele erfolglose Anmeldeversuche oder eine fehlgeleitete Bot-Erkennung. In seltenen Fällen kann es aber auch sein, dass die eigene IP-Adresse auf einer “deny-list” auftaucht, die von den Zielen eingelesen wurde. Auch hier empfiehlt sich: warten.
Der angesprochene Dienst erwartet einen anderen Port als den SSH-Standard Port 22. Somit stimmen User/Ziel-Adresse/Port nicht überein.

Das Port-Problem lässt sich leicht lösen.

Herausfinden des “Listen Port” auf dem Host (Server Configuration / SSH). Auf dem Bild ist dargestellt, wie die Einstellung auf meiner Gitea-Instanz aussieht. Alternativ genügt meist ein Blick in die Konfigurationsdatei des entsprechenden Services.
Die SSH-Konfiguration unter ~./ssh/config mit einer konkreten Port-Nummer versehen. Beispiel:

# /.ssh/config
 Host gitserver
 Hostname git.schallbert.de
 Port 222
 [...]

Problem: Too Many Authentication Failures

Konsolenausgabe:

➜ blog git:(article) ✗ git pull
Received disconnect from <ipAddress> port <portId>: Too many authentication failures

Wir haben nun also eine Verbindung zum Server 😁, aber der mag uns nicht reinlassen 😨. Immerhin wird mitgeteilt, warum: Er meint, wir hätten zu viele Schlüssel an seiner Haustür ausprobiert.

Server-Anmeldelimit prüfen

Dieser Fehler tritt auf, wenn das Server-Limit der Anmeldeversuche gerissen wird. Der Wert beträgt beim Service sshd beispielsweise standardmäßig MaxAuthTries = 6. Hat man viele Schlüssel für mehrere Verbindungen abgespeichert oder verwendet wie ich neuerdings Hardware Security Keys und legt Zweitschlüssel an (also ssh-keys.count*2), wird dieser Wert schnell überschritten.

Fies bei diesem Fehler ist außerdem, dass er nur bei bestimmten Services “unten” in des Agents Schlüsselbund auftritt: unter den ersten sechs dürfen ja fünf Schlüssel falsch sein. Zudem schützt einen nicht, wenn man die Schlüssel in der ~./ssh/config korrekt hinterlegt hat. Der Agent nimmt stets alle Schlüssel zum Probieren mit, wenn man es ihm nicht explizit verbietet.

Das Verbot erteilen wir per IdentitiesOnly yes. Hiermit wird dem Agent klar gesagt, dass er nur die für diesen Host explizit angegebenen Identities (Also Schlüsseldateien oder Nutzername/Passwort) verwenden soll.

# /.ssh/config
Host gitserver
 Hostname git.schallbert.de
 Port 222
 User <user>
 PreferredAuthentications publickey
 IdentityFile <path_to_private_key1>
 Identityfile <path_to_private_key2>
 IdentitiesOnly yes

Git-Config überprüfen

Diesen Fehler bekommt man auch, wenn die Git-Konfiguration des Repository unter <reponame>/.git/config nicht mit dem in der SSH-Konfiguration ~/.ssh/config hinterlegten Datensatz für Server und Repository übereinstimmt. Ändert man die SSH-Konfiguration, so sind alle auf diesem Server bereitgehaltenen Repo-Konfigurationen ebenfalls zu ändern.

Beispiel:

# <reponame>/.git/config
# [...]
[remote "origin"]
	url = ssh://git@git.schallbert.de:222/schallbert/<reponame>.git
	fetch = +refs/heads/*:refs/remotes/origin/*
[branch "main"]
	remote = origin
	merge = refs/heads/main
	vscode-merge-base = origin/main

In diesem Falle wird die gitserver-Konfiguration gar nicht verwendet, sondern sich direkt einwählt. Dies führt dazu, dass der Agent kein IdentitiesOnly yes Flag mitgeliefert bekommt und er Schlüssel durchprobiert, bis der Server abwinkt. Lösung:

[remote "origin"]
 url = git@gitserver:schallbert/<reponame>.git
	fetch = +refs/heads/*:refs/remotes/origin/*

Problem: Permission Denied (publickey,password)

Konsolenausgabe:

➜ blog git:(article) ✗ ssh -T git@gitserver
git@git.schallbert.de: Permission denied (publickey,password).

Dieses Problem kann leider viele verschiedene Ursachen haben. Ein paar räumt Githubs Anleitung bereits aus dem Weg, darunter:

sudo verwendet
Falscher Server
nicht den git-user verwendet
Falschen Schlüssel verwendet (client)
Schlüssel nicht hinterlegt (server)

Die Ausgabe bei falschem Username sieht so aus:

➜ blog git:(article) ✗ ssh -T mit@gitserver
mit@git.schallbert.de: Permission denied (publickey).

Eine weitere Ursache kann eine fehlende Abstimmung zwischen der Konfigurationsdatei ~./ssh/config und dem im git client hinterlegten Remote-Adresse liegen. Sind diese nicht deckungsgleich, wird eine eventuell bestehende Konfiguration gar nicht erst benutzt.

Eine Überprüfung kann man mit git remote -v durchführen.

➜ blog git:(article) ✗ git remote -v
origin	ssh://git@git.schallbert.de:222/schallbert/blog.git (fetch)
origin	ssh://git@git.schallbert.de:222/schallbert/blog.git (push)

Korrekt wäre mit der verbesserten Konfigurationsdatei (Ports eindeutig gesetzt, Identity Files definiert und auf die Angegebenen beschränkt):

# Update link to server's git repository, use host alias from config file
➜ blog git:(article) ✗ git remote update origin git@gitserver:schallbert/blog.git
# Now check if the update was effective
➜ blog git:(article) ✗ git remote -v
origin	git@gitserver:schallbert/blog.git (fetch)
origin	git@gitserver:schallbert/blog.git (push)

Problem: Agent Refused Operation

Konsolenausgabe:

➜ blog git:(local-setup) ✗ git push --set-upstream origin local-setup 
sign_and_send_pubkey: signing failed for ED25519-SK <path-to-private-key> from agent: agent refused operation

Diesen Fehler sehe ich erst, seitdem ich Hardware Security Keys für ssh verwende. Aus meiner Sicht kann er zwei Ursachen haben. Beide sind zum Glück leicht zu beheben:

Der Agent kennt den Schlüssel nicht. Der Befehl ssh-add löst das Problem. Prüfung per ssh-add -l | grep “<your-key’s-comment>”
Der angeforderte Schlüssel ist nicht da. Kann bei HSK und HSM passieren, falls sie nicht eingesteckt sind, nicht richtig auf dem NFC-Lesegerät platziert sind oder das HSM im Netzwerk nicht verfügbar ist. Oder wenn manuell im Verzeichnis ~./ssh/config gearbeitet wurde und der Schlüssel nun umbenannt oder gelöscht ist.

Hardware Security Key: SSH einrichten

Schallbert — Sun, 03 May 2026

Motivation

In meinem Post über Hardware Security Keys schrieb ich, dass ich möglichst viele meiner Verbindungen passwortlos mit meinem neuen HSK absichern möchte. Ich verwende SSH-Verbindungen für verschiedene Dienste und Zwecke: Ich greife auf meinen VPS zu, benutze Dienste wie Github, Gitea sowie meine eigene Gitea-Instanz und lasse die Erzeugung von Backups im lokalen Netz über scp laufen, welches das SSH-Protokoll verwendet.

SSH-Zugriff für Hardware Security Keys einrichten

HSKs wie mein Yubikey können private Schlüssel für SecureShell-Zugriffe abspeichern. Somit muss man sie nicht mehr lokal auf jedem Endgerät ablegen (das bleibt aber konfigurierbar, siehe unten). Zudem sind sie gegenüber der Verwahrung auf einem Rechner besser gegen unbefugte Zugriffe geschützt.

Also probiere ich aus, meinen Github-SSH-Zugriff auf HSK umzustellen und folge Yubicos Anleitung für passwordlose Authentisierung für Github. Das Verfahren zur Erzeugung von SSH-Schlüsseln nach FIDO unterscheidet sich für verschiedene Schlüsselhersteller nicht. Ich verlinke ebenfalls die Nitrokey-Anleitung als Referenz.

Was so nicht funktioniert

Doch mit den Empfehlungen von Yubico selbst komme ich auf meinem Betriebssystem und der Standardinstallation von openssh nicht zum Ziel. Das aus der Anleitung zusammengebaute Kommando lautet:

schallbert@machine:~# ssh-keygen -t ed25519-sk -O resident -O verify-required -O application=ssh:github -O user=schallbert -C "schallbert@github.com"

Nach Erstellung muss man den öffentliche Schlüssel (Dateiendung .pub) in der Web-Anwendung des jeweiligen Dienstes im Menüpunkt SSH-Zugang hinterlegen.

Bedeutung des Kommandos und der wichtigsten Optionen

Dieser Befehl¹ sagt der Anwendung ssh-keygen, dass sie mir einen Schlüssel des Typs -t ed25519-sk erzeugen soll. Die Endung -sk sagt aus, dass der Schlüssel auf einem Security Key - in meinem Fall dem Yubikey - gespeichert werden soll.

Um das Flag -O resident zu verstehen muss man wissen, dass FIDO Authenticator-Schlüssel wie mit -sk erzeugt aus zwei Teilen bestehen: Ein key handle Teil, welcher auf der Festplatte des Rechners verbleibt und der private Schlüssel selbst, welcher nur auf dem HSK existiert. Nur zusammen können sie Authentisierungsanfragen korrekt beantworten. Das Flag selbst weist jedoch an, beide Schlüsselteile auf den Yubikey zu schreiben. Das erleichtert die Verwendung mehrerer Geräte mit demselben Schlüssel: Der key handle-Teil kann vom Yubikey ausgelesen und auf anderen Endgeräten abgelegt werden. Auf der anderen Seite jedoch genügt nun das Verlorengehen des Yubikey allein, um möglichen Angreifern SSH-Zugriff zu geben.

-f filename legt Namen für die Schlüsseldateien fest. Macht besonders dann Sinn, wenn man mehrere SSH-Verbindungen oder HSM verwalten muss. Ich habe mir eine Konvention erstellt, um nicht durcheinander zu kommen. Diese orientiert sich stark an der Schreibweise des Schlüssel-Auslesens von einem HSK (ssh-keygen -K).

-f <keyType>_<protocol>:<service>_<user>_<device>

Als konkretes Beispiel würde mein Dateiname hier wie folgt lauten:

-f ed25519-sk_ssh:github_schallbert_yubikey-main

-C schallbert@github.com fügt der Schlüsseldatei selbst einen Kommentar hinzu, zum Beispiel eine Kontaktadresse. Somit bekommt der Schlüssel ein Label, was die Handhabung unter mehreren vereinfacht.

-O application=ssh:github dient nur der sauberen Auflistung im Authenticator-Programm und sorgt dafür, dass ich Schlüssel nicht miteinander verwechseln kann. Ansonsten steht dort nämlich nur ssh:keygen und ich kann nicht sehen, für welche Services ich Schlüssel hinterlegt habe. Außerdem hilfreich bei der Verwendung von -resident, da bei der Extraktion der Schlüssel mit ssh-keygen -K Unterscheidbarkeit gegeben bleibt.

-O user=schallbert hat für mich keinen praktischen Nutzen, da SSH dieses Flag nicht interessiert und der Yubikey Authenticator meinen Nutzernamen anders als erwartet nicht anzeigt.

-O no-touch-required vermeidet, dass der Hardware Security Key bei jeder Verwendung des Schlüssels berührt werden muss. Nützlich bei sehr häufiger Verwendung, allerdings Sicherheitsverlust durch Automatisierbarkeit.

-O verify-required sagt aus, dass die PIN des HSM abzufragen ist, bevor der Schlüssel genutzt werden kann. Eigentlich als zusätzliche Sicherheit gedacht, bekomme ich damit in meiner Shell jedoch Probleme. Und zwar wird die PIN einmal abgefragt, erzeugt aber vom ssh-agent nicht jedes mal eine Abfrage in meiner Konsole. Sobald ich in einer anderen Session versuche mich per SSH zu verbinden, erhalte ich eine Fehlermeldung agent refused operation:

schallbert@machine:~# ssh -T git@github.com
sign_and_send_pubkey: signing failed for ED25519-SK "schallbert@github.com" from agent: agent refused operation
root@opnsense: Permission denied (publickey).

Woran hat es gelegen?

Nach langer, frustrierender Fehlersuche (Was mache ich falsch? Funktioniert es mit dem Zweitschlüssel? Warum geht es beim ersten mal, danach aber nicht mehr? Was ist, wenn ich die Schlüssel erneut erstelle? Was passiert an anderen Rechnern? Was meint “KI” dazu? - Letzteres kostete bestimmt eine Stunde und ließ mich komplett auf der Stelle treten) probiere ich es mit einem anderen Kommando. Das funktioniert auf Anhieb.

Was hingegen funktioniert

schallbert@machine:~# ssh-keygen -t ed25519-sk -O application=ssh:github -C "schallbert@github.com" -f ed25519-sk_ssh:github_schallbert_yubikey-main

Lasse ich verify-required weg, kann ich mich erfolgreich anmelden und der SSH-agent läuft sauber durch.

Was `verify-required` benötigt

Dieser Post im Forum superuser bringt für mein Fehlerbild Licht ins Dunkel. Die Terminal-Session mit der ich das SSH-Schlüsselpaar erstelle speichert die per verify-required Flag erzwungene Pin-Eingabe zwischen. Daher funktioniert der Login erst einmal. Logge ich mich später oder in einem anderen Fenster ein, wie ich es oben getan habe um z.B. git pull in einem meiner Repos zu prüfen, fragt der SSH-Agent meine PIN nicht ab.

Das liegt wohl daran, dass der SSH-Agent selbst keine Prompts an das anfragende Programm ausgeben kann. Abhilfe schafft ein Untermodul von Openssh: openssh-askpass. Dieses kann man dem Agent übergeben, welcher dann die PIN-Abfrage über askpass an den User übermittelt.

Installation von ssh-askpass

Mein Betriebssystem hatte ssh-askpass nicht installiert, daher hole ich das hier nach. Es verwendet den Paketmanager DNF “Dandified YUM” statt apt oder anderer gängiger Manager. Dabei ist die Namensgebung meiner Meinung nach nicht 100% einheitlich, spreche ich den ssh-Programme doch im Terminal mit ssh-agent an, muss jedoch openssh-agent tippen für die Installation.

# verify-required needs openssh subpackage through Fedora's package manager
schallbert@machine:~# sudo dnf install openssh-askpass
Installing:
 openssh-askpass
[...]
Complete!

Nun will ich dem Agent mitteilen, dass er ssh-askpass zum Erfragen der PIN ansprechen kann. Dafür mus ich wissen, in welchem Pfad sich das Submodul befindet.

schallbert@machine:~# which openssh-askpass
/usr/bin/which: no openssh-askpass [...]

Komisch, aber ich hatte es doch installiert! Frage ich mal den Paketmanager:

schallbert@machine:~# dnf repoquery --list openssh-askpass
[...]
/usr/libexec/openssh/ssh-askpass

Aha, openssh versteckt sich im Ordner libexec. Na dann kann ich das Modul jetzt dem Agent bekanntgeben.

schallbert@machine:~# eval "$(ssh-agent -s; SSH_ASKPASS=/usr/libexec/openssh/ssh-askpass)"
Agent pid 16747

Ich prüfe die Verbindung zu Github und bekomme wie gewünscht einen Dialog angezeigt, der meine PIN abfragt. Anschließend muss ich den HSK noch berühren und bekomme dann die Erfolgsmeldung. Damit das alles auch in einem neuen Terminal und nach Neustart des Rechners funktioniert, füge ich eine Referenz auf den Schlüssel in meine Konfigurationsdatei ein.

# ~/.ssh/config
Host github
 User git
 Hostname github.com
 PreferredAuthentications publickey
 IdentityFile ~/.ssh/ed25519-sk_ssh:github_schallbert_yubikey-main

Um auf Nummer sicher zu gehen, den Agenten neustarten und neue Terminalsessions erstellen. Sollten Zugangsdaten im Cache gewesen sein, ist das hiermit zurückgesetzt. Anschließend erneut die SSH-Verbindung testen.

 schallbert@machine:~# eval "$(ssh-agent -k)" && eval "$(ssh-agent -s)"

Einziger Wehrmutstropfen ist, dass ich jetzt beim Verbinden mit SSH ein zusätzliches Popup bekomme. Das wird durch die grafische Nutzeroberfläche gnome ausgelöst. Leider finde ich keine Option, die zugehörige Einstellung permanent speichern. Somit wird es bei jeder Verbindung mit verify-required angezeigt. Bei Gnome wird ist das Problem bereits für andere Anwendungen bekannt, anscheinend aber noch nicht abgestellt.

Übertragung auf Windows-Systeme

Ich habe meine Schlüssel ja mit der Option -O resident erzeugt. Da liegt es nahe, die Extraktion des key-handle mal auf einem komplett anderen System zu testen: Windows.

Ich öffne die Kommandozeile und tippe

schallbert@windows-machine:~# ssh-keygen -K
Enter PIN for authenticator:
You may need to touch your authenticator to authorize key download.
Provider "internal" returned failure -1
Unable to load resident keys: invalid format

Invalid format? Im Netz steht öfters geschrieben, dass die Schlüssel manchmal am Ende noch ein LineFeed-Zeichen benötigen um richtig erkannt zu werden. Ohne Download vom HSK kann ich sie aber nicht modifizieren. Also übertrage ich öffentlichen Schlüssel und key-handle manuell auf den Rechner und probiere testweise das git pull-Kommando aus. Und siehe da: Es klappt!

Möchte man also die Schlüssel mit verschiedenen Betriebssystemfamilien verwenden, nutzt die Option -resident anscheinend nichts. Der Befehl ssh-keygen -K ist nicht granular steuerbar: Er lädt alle auf dem HSK befindlichen resident keys herunter.

VPS: Vorsicht bei Schlüssel-Ersatz

Noch ein Hinweis aus eigener Erfahrung: Hat man bereits SSH-Schlüssel hinterlegt bei einem Dienstanbieter, der selber Ressourcen bereitstellt (In meinem Fall einen Server als VPS) so werden neue SSH-Schlüssel meist nicht über das Web-Frontend an diese Ressource weitergereicht.

Die “alten” Schlüssel werden folglich weiterhin benötigt und die Neuen nicht verwendet, obwohl sie in der Web-App abgelegt sind!

Die neuen Schlüssel müssen dem Ziel manuell bekanntgemacht werden.

Das führe ich der Anleitung von meinem Hoster Hetzner folgend mit dem Befehl ssh-copy-id aus.

Neue Schlüssel manuell auf VPS ablegen

schallbert@machine:~# ssh-copy-id -i ./ed25519-sk_ssh:server_schallbert_yubikey-main.pub server

Dabei ist server der SSH-Alias für meinen VPS. Ich verbinde mittels des bekannten, “alten” Schlüssels lasse den “Neuen” ablegen. Doch irgend etwas funktioniert nicht wie erwartet:

/usr/bin/ssh-copy-id: INFO: attempting to log in with the new key(s), to filter out any that are already installed
/usr/bin/ssh-copy-id: WARNING: All keys were skipped because they already exist on the remote system.
		(if you think this is a mistake, you may want to use -f option)

Schlüssel erfolgreich übertragen?

Ich logge mich also auf meinem Server ein und prüfe, ob der neue Schlüssel tatsächlich in der ~/.ssh/authorized_keys Datei auftaucht. Tut er nicht. Also führe ich das obige Kommando erneut aus, diesmal mit aktivierter -f (Force) Option. Und tatsächlich, die Übertragung klappt!

schallbert@machine:~# ssh-copy-id -f -i ./ed25519-sk_ssh:server_schallbert_yubikey-main.pub server 
Number of key(s) added: 1

Now try logging into the machine, with: "ssh -i <identityFile> 'server'"
and check to make sure that only the key(s) you wanted were added.

Zum Testen wie empfohlen nun mit dem neuen Schlüssel einloggen und… Läuft! Erst jetzt können die alten Schlüssel sicher gelöscht werden: shred -u <path/to/private/key>

Auf direktem Wege ohne ssh-copy-id

Will man den neuen Schlüssel ohne zusätzliche Werkzeuge bekannt machen, so kann man den Inhalt der öffentlichen Schlüsseldatei <key-filename>.pub auch direkt selbst in eine neue Zeile von ~/.ssh/authorized_keys schreiben. Dafür benötigt man lediglich eine offene SSH-Verbindung zum Ziel.

Überlegungen zu Komfort und Bedienbarkeit

Wenn ich mir meine SSH-Verbindungen so ansehe, dann teilen sie sich grob in zwei Kategorien:

Admin-Zugänge (VPS, NAS, Raspberry Pi) und Signaturen
Protokoll-Zugänge (Git etc.)

Erstere erfordern aus meiner Sicht ein höheres Sicherheitsniveau. Zudem nutze ich sie nicht so häufig wie Versionsverwaltungen. Daher empfehle ich für die erste Kategorie verify-required und würde dies bei der Zweiten weglassen. Mit der Option no-touch-required würde ich ebenso verfahren: falls alle paar Minuten ein Commit hochgeladen werden soll, werden ständige Berührungen des Schlüssels schnell irritierend.

Alle Optionen bekommt man bei Aufruf des Handbuchs per man ssh-keygen angezeigt. ↩︎

Hardware Security Keys

Schallbert — Sat, 25 Apr 2026

Begriffsabgrenzung: TPM und HSK

Akronym	Bezeichnung	Kurzbeschreibung
TPM	Trusted Platform Module	Fest verbaut. Schützt das Gerät selbst
HSK	Hardware Security Key	Mobil. Schützt Konten, Zertifikate, private Schlüssel

Das Trusted Platform Module ist ein Sicherheitschip, der kryptografische Schlüssel sicher speichert und Funktionen wie Secure Boot, BitLocker-Verschlüsselung und Geräteidentität bereitstellt. Er ist fest auf der Hauptplatine eines Computers oder Smartphones verlötet.

Ein Hardware Security Key HSK, Hardware-Sicherheitsschlüssel hingegen ist meist mobil und kann mit verschiedenen Geräten verbunden werden. Es kann Schlüssel nicht nur speichern, sondern meist auch kryptografische Operationen (Schlüsselgenerierung, Signatur, Verschlüsselung) ausführen. HSKs sind hochsicher und manipulationsgeschützt konstruiert. Sie können extern zertifiziert bzw. auditiert sein, sodass auch hochsensible Vorgänge wie Zahlungstransaktionen ausgeführt werden können.

Was bisher geschah

Ich hörte einen Podcast vom Bundesamt für Sicherheit in der Informationstechnik (BSI) zum Thema “Passkey statt Passwort”. Den Empfehlungen folgend habe ich mir ein mobiles Hardware-Sicherheitsmodul (HSM) gekauft, um in Zukunft Passkeys für meine Dienste zu verwenden. Schon lange bin ich nicht mehr glücklich mit meiner fragmentierten Geheimnisverwaltung aus Zetteln, Browser-Plugins, offline-Passwortmanagern wie KeePass, auf Festplatte abgelegten SSH-Schlüsseln, Backup-Keys und Notfallcodes diverser Anbieter.

Ich möchte endlich mal Ordnung in die Landschaft bringen, ohne mich an einen kommerziellen Anbieter so fest zu binden, dass ich von ihm abhängig werde.

Zielvorstellung

Keine Passwörter oder Login-Daten mehr merken müssen
Möglichst einfache, dabei sichere Verwaltung von Passwörtern aufbauen
Ordnung in den Accountwust bringen
Digitalen Nachlass regeln
Anderen ermöglichen, es mir gleichzutun

Welche Erwartung ich jetzt schon einmal nehmen kann: Ganz ohne Passwörter oder Pins geht es auch mit dem HSK nicht. Ein Yubikey ist kein Passwortmanager. Er kann zwar Zertifikate, Passkeys und Secrets für OTPs halten, gibt diese Geheimnisse dann aber nicht mehr preis. Mit seiner Hilfe kann man signieren (Authentizität beweisen), Verschlüsseln und abgeleitete Schlüssel erstellen.

Vielmehr lässt sich die Passwortverwaltung mit Hilfe eines Hardware-Sicherheitsschlüssels aber zentralisieren und vereinfachen, da gängige Passwortmanager z.B. Passkeys unterstützen und so kein “Masterpasswort” mehr nötig ist.

Yubikey

Als HSK nutze ich zwei Yubikey Schlüsselanhänger. Einen zum immer dabeihaben und einen als Zweitschlüssel, welcher an einem sicheren Ort verwahrt wird. Es gibt noch andere Anbieter mobiler Hardware Security Keys wie Nitrokey. Die kannte ich vor Verfassen dieses Artikels noch nicht. Das ist bedauerlich, ist ihr Produkt doch quelloffen und damit idealer Testkandidat für mein Blog 😥.

Yubico Authenticator

Das GUI-Programm “Yubikey Authenticator” ist nützlich zum Einrichten, Belegen der Funktionstaste (z.B. Bestätigung oder Passwortausgabe als Tastatursimulation) und falls man 2FA-Einmalkennwörter z.B. als TOTP erzeugen will. Außerdem unterstützt mein Yubikey PKI, sodass man dort unter anderem auch SSL-Zertifikate und private Schlüssel geschützt ablegen kann.

Konzept des HSK

Dabei gehört es zum Konzept, dass private Schlüssel entweder direkt auf dem Hardware-Schlüssel erzeugt werden oder - ohne sie lokal dauerhaft zu speichern - zwar auf einem Endgerät erstellt, aber auf dem Yubikey abgelegt werden. Diese verbleiben auf dem Schlüssel und sind nicht exportierbar. Er unterstützt gängige asymmetrische Verfahren wie RSA und ECDH. Für Details siehe z.B. diese BSI-Publikation über kryptografische Verfahren. Außerdem wird der Schlüssel die meiste Zeit offline, also ohne Energieversorgung herumliegen und dadurch kaum angreifbar sein. Eine zusätzliche Pin als Schutzmaßnahme bei Verlust des Schlüssels ist ein weiterer Sicherheitsfaktor.

Zweitschlüssel

Dennoch sollte man sich notieren, welche Zugänge man mit welchem Verfahren schützt, damit die richtigen Accounts im Falle des Verlustes gesperrt werden können. Ein “Zweitschlüssel” sollte vorhanden und belegt sein, was fast genauso zeitaufwendig ist wie den Hauptschlüssel zu konfigurieren.

NFC

Von der NFC-Unterstützung meines Schlüssels hatte ich mir erhofft, Logins noch schneller und leichter hinter mich bringen zu können. Zwei Dinge hier stören mich jedoch: Meinen Laptop kriege ich partout nicht dazu, den Yubikey per NFC zu erkennen. Und auf dem Handy funktioniert die NFC-Erkennung höchstens mittelmäßig. Halte ich den Schlüssel dran, startet die App und bittet mich um Eingabe der Pin. Tue ich dies, muss ich den Schlüssel wieder entfernen und erneut an den Sensor halten “Schlüssel nicht bewegen!”. Das funktioniert längst nicht jedes mal und wirkt insgesamt ziemlich störanfällig. Schade.

Was mir beim Umgang mit Yubikey fehlt

Insgesamt vermisse ich ein paar Komfort-Funktionen beim alltäglichen Umgang mit dem Yubikey. Bei Klick auf die gewünschten Schlüssel oder Accounts passiert nämlich nichts. Und konfigurieren kann ich da anscheinend auch nichts.

Bei der Verwendung von Passkeys würde ich mir eine Verknüpfung wünschen. Ein Klick auf den entsprechenden Schlüssel im Authenticator sollte die entsprechende App bzw. das Browserfenster mit der Zielwebsite aufrufen. Da ich das HSK zu diesem Zeitpunkt bereits mit der PIN entsperrt habe, kann sogar der Anmeldevorgang nach Berührung des Schlüssels vollautomatisch stattfinden.

Ähnliches wünsche ich mir beim Umgang mit Accounts. Warum heißt das Modul “Accounts”, wenn ich meine Konten nicht direkt darüber aufrufen kann? Auch hier muss ich die entsprechenden WebApps etc. selbst öffnen, den Passwortmanager am Start haben und dann noch die 2FA-Codes vom Authenticator herauskopieren. Das geht bestimmt einfacher.

Touch, password, PIN, PUK, management key, passphrase

Je nach Modul gibt es auch bei der Verwendung des Yubikey zumeist eine Mehr-Faktor-Authentisierung. Das unkomplizierteste Verfahren ist eine Anwesenheitserkennung über eine Berührung des Sticks. Damit kann sichergestellt werden, dass eine Person das HSK aktiv bedient und nicht etwa automatisch eingeloggt werden kann. Touch kann modulübergreifend angewendet werden; zur Detailkonfiguration komme ich in meinem Artikel über SSH.

Das Accounts-Modul kann optional mittels Passwort, das Passkeys-Modul per PIN gesichert werden. Manche Anbieter verlangen die Einrichtung einer PIN als zweiten Faktor sogar.

Das Certificates-Modul muss mit PIN, und PUK und Management Key vor unbefugtem Zugriff gesperrt werden. Private Schlüssel oder Zertifikate können optional zusätzlich mit einer Passphrase ausgestattet werden, was die Schlüssel selbst schützt (und aus meiner Sicht für den Yubikey keinen Sinn macht, da die privaten Schlüssel ohnehin nicht auslesbar sind).

Funktionsumfang und kryptographische Landschaft

Da das HSK einen so großen Sicherheitsgewinn verspricht, möchte ich natürlich möglichst viele seiner Fähigkeiten nutzen. Ich habe jetzt ein paar Wochen mit den verschiedenen Modulen herumgespielt und muss feststellen, dass man sich ganz schön hineindenken und viel lernen muss, um alle gut nutzen zu können. Immerhin versteht man danach ungefähr was die Module tun und bekommt einen guten Überblick zu den Themen Internet-Sicherheit, Verschlüsselungsverfahren und -Protokolle.

“Accounts” und “Passkeys” sind für Eingabemasken (Plattformen, Webseiten, Shops) und Apps (Mailer, Passwortmanager, Messenger) einfach einzurichten: Absolut empfehlenswert! - schallbert

Yubikey-Modul	Beschreibung
Accounts	Verwaltung von Konten/Anmeldungen, unterstützt TOTP
Passkeys	Passwortloses Anmeldeverfahren durch FIDO/WebAuthn (Public-Key-Credential)
Certificates	Speicherung und Nutzung von Zertifikaten; unterstützt OpenPGP (PGP) und X.509 (PIV)
Slots	Zwei programmierbare Slots zur Ausgabe statischer Passworte oder Einmalkennwörter

Kompliziert und aufwendig wird es meiner Meinung nach mit Public/Private Keys und Zertifikaten. Erzeugungs- und Validierungsverfahren hängen vom Betriebssystem oder darauf verfügbaren Programmen ab und Anleitungen greifen teils zu kurz oder widersprechen sich: Nur für Nerds oder Profis. - schallbert

Gehen wir die Module mal durch.

2-Faktor-Authentisierung “Yubikey: Accounts”

Der Yubikey kann als Generator für zeitbasierte Einmalkennwörter dienen. Dafür legt man wie in jeder anderen Authenticator-App auch pro Dienst ein Konto an und übergibt einen Sicherheitsschlüssel (Geheimnis, Secret) an den Yubikey. Auf Basis dieses Geheimnisses können bei angestecktem HSK nun Einmalcodes erzeugt werden.

Da es keine Möglichkeit gibt, diese “Secrets” vom Yubikey zu exportieren, muss der Vorgang für Zweitschlüssel wiederholt werden. Doch nicht jeder Anbieter sieht die Nutzung mehrerer Authentikatoren vor. Also kann es sinnvoll sein, das Geheimnis in der Zwischenablage¹ zu halten und ihn bei der Konfiguration des/der Zweitschlüssel wiederzuverwenden.

Passkeys “Yubikey: Passkeys”

Das Passkey-Modul meines Yubikey funktioniert recht gut. Viele Services² unterstützen die passwortlose Anmeldung leider noch nicht oder akzeptieren Passkeys nur als zweiten Faktor. Bei anderen Services³ kann ich das Passwort nicht deaktivieren, sodass ich kaum einen Sicherheitsgewinn sehe oder mir werden Backup-Codes ausgegeben, die im Notfall als zweiter Faktor dienen sollen⁴. Immerhin, ich kann durch den Passkey jetzt bei einigen Diensten die Passwort-TOTP-Anmeldung umgehen und bin schneller eingeloggt.

“Die wohl größten Vorteile der Technologie für Nutzerinnen und Nutzer liegen darin, dass Sie in Zukunft zum einen keine Passwörter mehr erstellen und verwalten müssen. Zum anderen sind Passkeys immun gegen die breite Masse bekannter Phishing-Angriffe.” - BSI-Website, Oktober 2025

Die Authenticator-App braucht man nicht zur Konfiguration von Passkeys. Dies läuft komplett im Browser oder der Kommandokonsole ab. Beide müssen das Handling von Passkeys unterstützen.

Keys & Certificates “Yubikey: Certificates”

Um hier etwas Licht hineinzubringen, müssen wir uns erst einmal den Unterschied zwischen Schlüsselpaar und Zertifikat im Kontext der Authentisierung vor Augen führen. In beiden Fallen geht es darum, die Identität des Client zu verifizieren. Vor einem Server (z.B. per SSH), einer Institution (z.B. einer Certificate Authority) oder einem anderen Client (z.B. per PGP). Somit wird für das Ziel feststellbar, dass es sich tatsächlich um den zur Verbindung berechtigten Client handelt.

Public/Private Key Pair

Das reine Schlüsselpaar (also kein Zertifikat) wird üblicherweise dann verwendet, wenn das Ziel der Kommunikation im Besitz desjenigen ist, der auch über den Client verfügt. Dann nämlich kann der Client zum Aufsetzen der Verbindung den öffentlichen Schlüssel auf dem Host platzieren. Dieses Verfahren wird z.B. bei Einrichten von SSH-Verbindungen und für einige APIs wie bei der Search Console verschiedener Suchmaschinenanbieter angewendet.

Der Host kann dem Client mit dem öffentlichen Schlüssel verschlüsselte Testnachricht schicken, welche nur mit dem zugehörigen privaten Schlüssel wieder in Klartext umgewandelt werden kann. Schickt der Client den korrekten Klartext zum Host zurück, ist für den Host bewiesen, dass der Verbindungspartner authentisch ist.

Certificates / PIV

Doch was, wenn der Host nicht unter der Kontrolle des Clients steht? Wie soll dann sichergestellt werden, dass sich weder Client noch Server für jemand anders ausgibt und einen gefälschten öffentlichen Schlüssel hinterlegt? Genau da kommen Zertifikate zum Einsatz.

Vereinfacht gesagt enthält das Zertifikat nicht nur den öffentlichen Schlüsselteil, sondern zusätzliche Informationen über den Netzteilnehmer und die gewünschte Verbindung. Nun kommt eine vertrauenswürdige, an der Kommunikation zwischen Client und Server unbeteiligte dritte Partei ins Spiel. In der Private Key Infrastructure PKI nennt man sie Certificate Authority CA.

Der Netzteilnehmer sendet nun den öffentlichen Schlüssel samt Metadaten über sich selbst an die CA und stellt einen sogenannten CSR, einen Certificate Signing Request. Die CA prüft nun, ob der Kanal des Teilnehmers auch wirklich diesem gehört.

Bei einer E-Mail (Stichwort PGP/GPG) kann die CA beispielsweise einen aus dem Public Key errechneten Hash-Link an die angegebene Mailadresse versenden. Wird der Link geklickt, beweist dies der CA gegenüber, dass die Mailadresse tatsächlich dem Client gehört und sie kann das Zertifikat ausstellen, den CSR also mit ihrem privaten Schlüssel signieren.

Bei Domains (Stichwort SSL/TLS) kann die CA beim Domain Name Service DNS-Anbieter prüfen, ob die Angaben zur Anfrage des Servers passen.

Clients haben die Signaturen gängiger Certificate Authorities eingespeichert (z.B. im Browser). Wird das Zertifikat auf dem Rückweg zwischen Server und Client manipuliert, verändert sich der Hashwert und der Client spuckt eine Zertifikatswarnung aus: “invalid certificate”. Jetzt muss man jedoch den Certificate Authorities vertrauen⁵ 🙃

Der Rechner sollte dafür offline sein. Wenn man supersicher sein will, macht man das Anlernen auf einem Live-Betriebssystem. Das bootet üblicherweise von einem USB-Stick und hat nach dem Herunterfahren alles vergessen. ↩︎
Z.B. Gar nicht: Mailbox, 2FA: Discord und Kraken, zum Zeitpunkt Apr-26. Vielleicht habe ich aber auch nicht die richtigen Einstellungen gefunden? ↩︎
Z.B. Google, Github und Hetzner, zum Zeitpunkt Apr-26. ↩︎
Auch diese Backup-Codes müssen sicher abgelegt werden. Idealerweise wieder offline, unbedingt aber unabhängig vom HSK. ↩︎
Es gibt Alternativen zu Institutionen wie CAs, siehe Web of Trust. So kann die Verifikation der Identität beispielsweise auch peer-to-peer von unbeteiligten Dritten stattfinden. ↩︎

Giteas act_runner rootless: Startprobleme

Schallbert — Sat, 28 Mar 2026

Das Fehlerbild

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

Issue-Ticket bei Gitea

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

Problem mit Kernel-Berechtigungen?

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

Warum Container keine Container starten dürfen

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

Auswirkungen, falls trotz DinD etwas schief geht

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

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

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

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

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

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

Sackgasse: Nur unbedingt benötigte Rechte vergeben

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

Meine Vorgehensweise:

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

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

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

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

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

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

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

Zukünftige Lösung: Virtualisierung oder Daemonless

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

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

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

Linux Security Modules (seccomp, AppArmor, SELinux)

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

Apparmor

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

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

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

Einfache Lösung: Komplett abstellen

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

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

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

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

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

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

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

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

Richtige Lösung: Für jede Anwendung justieren

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

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

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

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

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

Entsprechend gut sieht jetzt auch das Logfile aus. Fertig!

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

Vortrag: Software-defined vehicle

Schallbert — Sun, 25 Jan 2026

— Dezember 2025 — Neuer Vortrag veröffentlicht

Ich habe vor kurzem einen Vortrag zum Thema software-defined vehicle gehalten. Die Folien sind jetzt zur Ansicht auf meiner Hauptseite unter Vorträge verfügbar.

Die Rückmeldungen waren überwältigend positiv. Der Vortrag gewährt tiefe Einblicke in die aktuelle Lage der Automobilindustrie und hilft dabei zu verstehen, warum sich die “klassischen” Autobauer so schwer tun, mit den modernen Fahrzeugen aus Fernost mitzuhalten.

Jekyll-dockerimage: Bundler und Gemfile

Schallbert — Fri, 14 Nov 2025

Was ist bundler?

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

Will ich lokal bauen, so tippe ich beispielsweise

bundle exec jekyll serve --incremental --future

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

bundler in der CI-Pipeline

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

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

Keine Schreibrechte

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

Spezifikationsdatei für bundler

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

Fehlerbehebung

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

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

bundle config set frozen true

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

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

`Gemfile.lock` für verschiedene Umgebungen optimieren

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

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

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

In meiner Lockfile taucht daraufhin folgender Eintrag auf:

nokogiri (1.18.10-x86_64-linux-musl)

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

fail2ban: Update zerstört Konfiguration

Schallbert — Thu, 23 Oct 2025

Alle paar Wochen sehe ich auf meinem Server üblicherweise nach dem Rechten:

Ist bei Docker alles ok? docker ps
Werden die Backups korrekt erzeugt? borgmatic repo-info
Funktionieren meine Abwehrmaßnahmen? iptables -n -L
Laufen meine Daemons zur Update-Automation? htop -F /server-config

Dieses mal allerdings zeigte iptables mir gähnende Leere. Das ist ungewöhnlich und deutet darauf hin, dass mit fail2ban etwas nicht stimmt.

schallbert@machine:~# iptables -n -L

Chain FORWARD (policy DROP)
target prot opt source destination 
DOCKER-USER all -- 0.0.0.0/0 0.0.0.0/0 
DOCKER-FORWARD all -- 0.0.0.0/0 0.0.0.0/0 

Chain DOCKER-USER (1 references)
target port opt source destination

Übersetzt lautet die Ausgabe etwa in etwa

“Die FORWARD-Chain leitet wie von Docker benötigt an die für Container relevante DOCKER-USER-Chain weiter. Unter dieser sind allerdings keine Anwendungen gelistet, die Pakete zurückweisen oder deren Weiterleitung verbieten (REJECT/DROP) können.”

An dieser Stelle müssten zwei Einträge für caddy-server und caddy-ratelimit auftauchen.

“fail2ban ERROR Failed during configuration”

Also schaue ich zuerst mal bei Docker nach:

docker logs -t fail2ban # Logs für den Container mit Namen fail2ban mit Zeitempel ausgeben

Statt wie üblich nach dem Durchscrollen mit <timestamp> Server ready belohnt zu werden, bekomme eine nicht enden wollende Flut an Logmeldungen angezeigt. Sie wiederholen sich und zeigen, dass fail2ban mit Exit with code 255 aussteigt. Einen besseren Überblick liefert mir das Log, wenn ich nur die letzten 100 Zeilen ausgebe:

docker logs -t --tail 100 fail2ban # Nur die letzten 100 Zeilen des Logs ausgeben, mit Zeitstempel

Die Fehlermeldung

<timestamp, ID> ERROR Failed during configuration: Bad value substitution: 
option 'action' in section 'caddy-ratelimit' contains an interpolation key 'banaction' which is not a valid option name. 
Raw value: '%(action_)s'

Die Meldung ist interessant, weil ich genau an dieser Stelle auch schon beim Erstellen im Zuge des Artikels Fail2ban mit Caddy Probleme mit der jail.local hatte. Damals musste ich action = iptables-multiport aus der Konfiguration nehmen, weil die auslösenden IP-Adressen auf der falschen CHAIN (INPUT) gelandet waren.

Nun scheint also die default-action auf der DOCKER-USER chain nicht mehr zu funktionieren. Also gehe ich ins Netz und suche nach ein paar Quellen für eine mögliche Lösung. Ich finde aber weder in der Update-Historie von fail2ban noch in der von mir benutzten Distribution von linuxserver.io Hinweise auf Updates, die hier große Änderungen im action.d Ordner veranlassen würden.

Lösung per `banaction = iptables[type=multiport]`

Also bemühe ich die Websuche und finde einen Kommentar eines Maintainers von fail2ban:

“[…] With action = iptables[type=multiport, protocol=tcp, chain=DOCKER-USER] you overwrote the default action […] [Solution:] simply set the chain variable only in the jail […]: port = http, https banaction = iptables[type=multiport] chain = DOCKER-USER” - sebres, Dec-2024

Die Grundlage dieser Aussage kann man in den Docker Docs nachlesen. Nebenbemerkung: An allen Stellen wird empfohlen, für zukünftige Anwendungen das modernere nftables statt iptables zu verwenden. Hier gibt es einen Artikel zum Thema.

Somit kann ich das bisher in meiner jail.local vorhandene action-Feld komplett löschen und stattdessen banaction verwenden. Sie sieht nun wie folgt aus:

# jail.local update Oct-2025

# Server/Client errors: 401 403 404 500
[caddy-status]
enabled = true
chain = DOCKER-USER
port = http,https
filter = caddy-status
logpath = <path/to/logfiles>
findtime = 10min
maxretry = 5
bantime = 1d
banaction = iptables[type=multiport]

Mit dieser Konfiguration fährt fail2ban normal hoch und gibt Server ready aus.

Überprüfen der Lösung mittels iptables

Ich erzeuge mir wie oben beschrieben Einträge in den Test-Logfiles, welche die Aktionen von caddy-status und caddy-ratelimit auslösen sollen. Wie erwartet erhalte ich in der “blocklist”:

schallbert@machine:~# iptables -n -L

Chain DOCKER-USER (1 references)
target prot opt source destination 
f2b-caddy-ratelimit tcp -- 0.0.0.0/0 0.0.0.0/0 multiport dports 80,443
f2b-caddy-status tcp -- 0.0.0.0/0 0.0.0.0/0 multiport dports 80,443

passtdas auf Github

Schallbert — Sun, 14 Sep 2025

— September 2025 — passtdas zum Download verfügbar

Das Werkzeug passtdas liest eine G-Code Datei für die Bearbeitung mit einer CNC-Fräsmaschine und ermittelt die Werkstückgrenzen (Extremwerte) in X und Y. Anschließend schreibt es ein weiteres CNC-Programm mit diesen Punkten und ermöglicht so, dass die Werkstückgrenzen direkt an der Maschine angefahren werden können.

So kann stets sichergestellt werden, dass der Rohling korrekt ausgerichtet ist und das Werkstück drauf passt.

Link zum Projekt auf Github

Ich habe vor, das Projekt demnächst in eine Browser-Lösung zu portieren und will es auf diese Weise einfacher zugänglich machen.

Schallbert

passtdas - ein Hilfsprogramm für die CNC

Schallbert — Mon, 08 Sep 2025

Das Problem

Ein Bekannter von mir schrieb mich an. Er betreibt eine CNC-Portalfräsmaschine als Hobby so wie ich und fertigt oft Einzelstücke. Die dabei entstehenden Reste sind aber teils zu schade zum Wegwerfen. Für eine bestmögliche Materialausnutzung probiert er, diese Reste als Rohlinge für weitere Projekte zu verwenden.

“Weißt du, wie ich an der Maschine herausfinden kann, ob mein Frästeil auf den Rohling passt?” - Anonym

Schnell ist es passiert: Den Maßen zufolge passt das Werkstück so gerade auf den Rohling. Setzt man den Nullpunkt nur leicht falsch, so fährt der Fräser über die Werkstückgrenzen hinaus und man kann das Werkstück wegwerfen.

Die Lösung

Es wäre doch toll, wenn die Maschine vor Beginn des Fräsvorganges die Kontur des Werkstückes abfahren würde, oder? So könnte man unkompliziert herausfinden, ob sich der Rohling wirklich komplett innerhalb der Werkstückgrenze befindet.

Da ich auf Anhieb keine schnelle Lösung online finden kann, denke ich an selbstgeschriebene Software für die Umsetzung. Daher mache ich mich an die Arbeit.

TODO: ADD VIDEO LINK

Die Software

Für einen schnellen Prototypen wähle ich die Hochsprache python. Warum? Ich beherrsche python recht gut, Bibliotheken für die erforderlichen geometrischen Berechnungen sind verfügbar, und das geschriebene Programm lässt sich leicht in eine all-in-one-Datei kompilieren.

Das Programm soll Maschineninstruktionen (G-Code) lesen und die Fräspfade analysieren. Die Stellen, an denen im Fräsprogramm die maximalen und minimalen X- und Y-Werte angefahren werden, sollen abgespeichert und selbst als Bewegungskommando in einer Pfaddatei ausgegeben werden.

Lädt man dieses Programm auf die Maschine, so wird ein so ermittelter “Extremwert” angefahren und die Z-Achse von Sicherheits- auf Messhöhe abgesenkt. Anschließend wird das Programm pausiert, sodass der Bediener Anpassungen der Werkstückposition vornehmen kann. Erst durch Einabe eines weiteren Startbefehls wird der nächste Extremwert angefahren usw.

Dieses Programm wird passtdas heißen.

Programmart

Ich entscheide mich für ein Konsolenprogramm mit wenigen Parametern:

Shortcut	Parameter name	Description
`-f`	`--file`	The source file to be analyzed. Required.
`-s`	`--zsafety`	Safety height the machine will do flyovers with. Optional.
`-p`	`--zprobe`	Probe height the machine will pinpoint to. Optional.

Die beiden Höhenparameter bekommen Default-Werte, sodass sie nicht immer mit angegeben werden müssen.

Eingabe

passtdas liest Dateien ein und durchsucht sie zeilenweise nach Bewegungsbefehlen G00, G01, G02, G03. Während die Auswertung für lineare Bewegungen wie G00, G01 einfach ist - Lineare Bewegungen lassen sich durch Punkt-zu-Punkt-Verbindungen ausdrücken, deren Extremwerte nicht zwischen den Punkten liegen können - kann das für Kreissegmente durchaus herausfordernd sein.

Die Höheninformation auf der Z-Achse wird ebenfalls mitgelesen und gespeichert. So kann die Zerspanungstechnikerin schnell prüfen, ob die maximale Frästiefe mit der Gewünschten übereinstimmt.

Befinden sich in der G-Code-Datei keine oder falsch formulierte Anweisungen, so gibt das passtdas entsprechende Fehlermeldungen aus und bricht die Analyse ab.

Definition Kreissegmente

Zum Hintergrund: Im G-Code können Kreissegmente auf zwei Arten definiert werden.

[...]
G00 X5.660 Y-0.000 Z10.000
G02 X-5.660 Y0.000 R5.660 F1600
[...]

Kommando:

“Fahre einen Kreisbogen im Uhrzeigersinn ab dem Punkt X5.66 Y0 mit Radius 5.66mm bis zum Punkt X-5.66 Y0 mit Vorschub 1600mm/min auf Höhe 10mm.”

Zeichnet man diese Kommandos, entsteht ein hängender Halbkreis. Kreise können mittels dreier Punkte definiert werden. Doch nur zwei Punkte sind gegeben. Der dritte Punkt muss mit Hilfe von Anfangs- und Endpunkt aus dem ebenfalls angegebenen Kreisradius berechnet werden.

Aufgabe: Finde heraus, wo dieser Kreis seine Extremwerte in XY hat.

Aber auch so kann ein Kreissegment definiert sein:

[...]
G00 X-2.5696 Y5.0431
G03 X-4.6258 Y3.2616 Z-0.5000 I2.5696 J-5.0431
[...]

Kommando:

“Fahre einen Kreisbogen gegen den Uhrzeigersinn ab dem Punkt X-2.56 Y5.04 mit Mittelpunktkoordinaten I2.56 J-5.04 bis zum Punkt X-4.62 Y3.26.”

Zeichnet man diese Kommandos, entsteht ein kurzes Kreissegment im oberen linken Quadranten. Hier sind zwar drei Punkte (Start- und Endpunkt sowie Kreismittelpunkt) gegeben. Doch auch hier kann es mitunter schwierig werden, herauszufinden, ob irgendwo auf dem Kreisbogen ein Extremwert angefahren wird.

Aufgabe: Finde heraus, wo dieser Kreis seine Extremwerte in XY hat.

Extremwerte von Kreissegmenten berechnen

Ein Kreissegment kann je nach Spanne bis zu vier zusätzliche Extremwerte haben: X+, Y+, X-, Y-. Bei einem Vollkreis sind dies stets die Koordinatenschnittpunkte vom Radius aus gesehen.

def get_extremes_from_arc(arc, coordinates):
 # [...]
 x_plus_radius = [center_x + radius, center_y, xyz[2]]
 y_plus_radius = [center_x, center_y + radius, xyz[2]]
 x_minus_radius = [center_x - radius, center_y, xyz[2]]
 y_minus_radius = [center_x, center_y - radius, xyz[2]]
 extremevalue_order = [x_plus_radius, y_plus_radius, x_minus_radius, y_minus_radius]
 if (arc[1] - arc[0]) < 0:
 # crossing the 0° line (x-axis), handle overflow with nested if below
 arc[1] += 360
 result = []
 for crossing_angle in range(0, 721, 90):
 if crossing_angle in range(int(arc[0]), int(arc[1] + 1)):
 i = int(crossing_angle / 90)
 if i > 3:
 i -= 4
 result.append(extremevalue_order[i])
 # [...]

Sind Kreismittelpunkt sowie Kreisradius bekannt, kann aus den Anfangs- und Endpunkten der überstrichene Winkel bestimmt werden. Hierdurch wird nun klar, ob Kreisanfangspunkt und/oder -Endpunkt selbst Extremwerte darstellen, oder ob durch Überstreichen eines Koordinatennullpunktes zusätzliche Extremwerte entstehen. Genau dies tut das obige Codebeispiel.

Datentabelle

Alle möglichen Extremwerte (zwei bei einer Linie, bis zu vier bei einem Kreissegment) werden nun in einer Datentabelle gesammelt. Sobald jede G-Codezeile ausgewertet und die Liste damit komplett ist, werden die Maximal- und Minimalwerte für jede Achse aus dieser Liste bestimmt.

So entstehen schließlich vier XYZ-Koordinaten, welche für jede Raumrichtung die maximale Ausdehnung des Werkstückes beschreibt.

Parallel durchsucht das Programm alle Befehle an die Z-Achse und merkt sich die maximale Eintauchtiefe.

Ausgabe

Das Kommandozeilenprogramm verfügt über keine visuelle Ausgabe. Daher beschränke ich mich auf die Erstellung eines Simulationsprogramms für die Fräsmaschine, in dem die Werkstückausdehnung angefahren wird und bei jedem Punkt pausiert:

G90

# Go to coordinate zero
MSG "Zmin of this job: -1.0"
G00 Z40
G00 X0 Y0
G01 Z15 F1200

MSG "PathPreview: Hit START to go to Ymin: ['0.0', '-5.66']"
M00
G00 Z40
G00 X0.0 Y-5.66
G01 Z15 F1200

MSG "PathPreview: Hit START to go to Xmin: ['-5.66', '0.0']"
M00
G00 Z40
G00 X-5.66 Y0.0
G01 Z15 F1200

MSG "PathPreview: Hit START to go to Ymax: ['0.0', '5.66']"
M00
G00 Z40
G00 X0.0 Y5.66
G01 Z15 F1200

MSG "PathPreview: Hit START to go to Xmax: ['5.66', '0.0']"
M00
G00 Z40
G00 X5.66 Y0.0
G01 Z15 F1200
# [...]

Obiges Beispiel fährt die Extremwerte eines Kreises mit r=5.66mm ab. Dabei fährt es stets eine Sicherheitshöhe von Z40 zum Überstreichen der Punkte an und bewegt die Z-Achse bei Ankunft langsam mit F1200 auf die Zielhöhe von Z15. Wichtig dabei ist, dass der Nullpunkt in Z vorher korrekt vermessen wurde - sonst kommt es möglicherweise zur Kollision mit dem Werkstück.

Test und Verifikation

Um zu sehen ob das Programm auch wie erwartet funktioniert habe ich drei Testdateien erstellt:

Unit tests: Prüft einzelne Funktionen im Programm, z.B. ob Linien- und Kreissegmente korrekt erkannt werden
integration tests: Testen, ob Funktionen im Verbund korrekt funktionieren, z.B. die richtige Berechnung von Extremwerten anhand von Eingabewerten
End to end tests: Diese Tests prüfen über die gesamte Funktionskette, z.B. ob falsch formatierte Eingabedateien erkannt werden

Zum Schluss erstelle ich mehrere Testdateien mit dem Programm und fahre die daraus erzeugten Extremwerte mit meiner CNC an.

Open-source software

Der Quellcode für passtdas steht kostenlos auf GitHub zur Verfügung, muss allerdings durch Python interpretiert werden.

Ich baue ein Endanwenderfreundliches und leicht zu bedienendes Programm daraus, sobald genügend Leute den Wunsch dafür geäußert haben.

Giteas act_runner rootless ausführen

Schallbert — Sun, 10 Aug 2025

In diesem Artikel zeige ich, wie ich den act_runner meiner Gitea-Instanz von gitea/act_runner auf gitea/act_runner:latest-dind-rootless umstelle.

Warum dieser Aufwand? Weil act_runner in Docker läuft und Zugriff auf den Daemon per /var/run/docker.sock als sogenanntes Volume (gemeint im Sinne von Datenträger) bzw. Bind-Mount benötigt, um zu funktionieren. Der Besitzer dieses Sockets ist root, wodurch der Container praktisch Vollzugriff auf das Hostsystem erhält.

“RULE #1 - Do not expose the Docker daemon socket (even to the containers)” - OWASP / Docker Security Cheat Sheet

Dies ist hoch riskant, denn es liegt im Prinzip des Runners, von Dritten erzeugten Job-Code auszuführen. Ein offenes Einfallstor. In Verbindung mit direktem Durchgriff auf das Hostsystem kann das im Falle eines erfolgreichen Angriffes einen Totalausfall bzw. die “feindliche Übernahme” meiner Infrastruktur bedeuten.

Gefahr durch `docker.sock`

Ich richte mich in dieser Anleitung nach der Empfehlung von OWASP zum Thema Docker-Sicherheit und wende deren Regel(n) in der Praxis an. OWASP steht für “Open Web Application Security Project”. Es ist eine Organisation, die sich für höhere Sicherheit von Webanwendungen einsetzt und dabei Anwender wie mich mit kostenfreien Artikeln, Dokumentation und Technologie unterstützt.

Die unter Regel 1 beschriebenen Maßnahmen lauten:

Dockers tcp Socket abgeschaltet lassen

Sollte der Zugang zum Docker Daemon per tcp eingeschaltet sein, kann sich mit diesem - sofern keine weiteren Vorkehrungen getroffen wurden - über eine ungesicherte Verbindung und ohne Authentisierung verbunden werden. Der Daemon ist dann durch praktisch jeden Internetnutzer zugänglich und damit angreifbar.

Wie stelle ich also sicher, dass der tcp Socket abgeschaltet ist? Die Anleitung hierzu findet sich in den Docker Docs und muss quasi verkehrt herum angewandt werden. Auch dort wird ausdrücklich vor ungeschützter Verfügbarmachung des tcp-Sockets gewarnt.

Nach Ausführen aller erforderlichen Schritte lasse ich netstat einmal durchlaufen. Es listet mir offene Sockets, Netzwerkschnittstellen und Routing-Tabellen auf:

# check if Docker Daemon's "dockerd" tcp socket is exposed
schallbert@machine:~# netstat -lntp | grep dockerd
# test is a pass if this command does not return anything.

Bei mir findet sich kein Eintrag mit dockerd. Mein Server ist an dieser Stelle schon einmal nicht verwundbar.

Den Docker Socket `/var/run/docker.sock` nicht in andere Container einbinden

Hier wird es schon etwas schwieriger: act_runner benötigt den Socket, um Job-Container zu erzeugen, zu verwalten und schließlich wieder zu entsorgen. Ohne Zugriff auf den Docker Daemon über den Socket funktioniert die Build-Pipeline schlicht und einfach nicht - es sei denn, man möchte komplett auf Docker verzichten und sowohl den Runner als auch die Build-Jobs direkt auf der Host-Maschine laufen lassen. Damit gingen aber viele Nachteile einher: Verlust der Kapselung, keine Portabilität, schlechte Skalierbarkeit, geringere Sicherheit…

Aber auch für die Option mit Docker gibt es eine Lösung: act_runner Docker-in-Docker aufsetzen. Mit diesem Setup erhält act_runner einen eigenen Docker Daemon, jedoch mit eingeschränkten Rechten und ohne Zugriff auf den des Host-Systems. Dieser übernimmt dann den Lebenszyklus von Job-Containern, sodass sie komplett unabhängig vom Host-System laufen.

Docker in Docker

Folgendes Schaubild verdeutlicht den Unterschied:

Act_runner “rootless” starten

Also folge ich der Anleitung und kopiere mir eine passende docker-compose.yml zusammen. Wichtig hier:

Es muss privileged: true gesetzt werden. Ansonsten kann der Docker Daemon im act_runner-Container nicht richtig starten, da ihm Kernel-Funktionen fehlen. Somit schmiert der ganze Container wieder und wieder ab, ohne dabei hilfreiche Fehlermeldungen zu erzeugen.
Die Umgebungsvariable DOCKER_HOST=unix:///var/run/user/1000/docker.sock muss gesetzt sein. Hier wird der Docker Socket über einen nicht-privilegierten User gesteuert und steht dem Runner für die Verwaltung von Job Containern zur Verfügung. Der Daemon läuft gekapselt im Container und steht nicht in Verbindung mit der Host-Maschine.

Volume-Verwirrung

Prima! Da der Runner nun läuft, lasse ich ihn direkt mal auf einen Job los. Leider schlägt das Bauen bereits nach Sekundenbruchteilen mit dieser Meldung fehl:

# Runner step: Set up job
failed to start container: Error response from daemon: error while creating mount source path '<volumeSourceFullPath>': mkdir <volumeSourcePath>: permission denied

Hier habe ich stundenlang recherchieren müssen und war lange der falschen Überzeugung, dass es an fehlenden Berechtigungen bei Ordnern auf der Host-Maschine liegt. Später erst verstand ich wirklich, dass Docker-in-Docker genau so gemeint ist, wie es heißt: Nicht nur werden Container durch Container erzeugt, sondern innerhalb des Containers läuft ein separater Docker Daemon!

Damit funktioniert nämlich der klassische Weg nicht mehr, Volumes in Job Containern direkt vom Host-System per -v /a/b:/x/y verfügbar zu machen. Stattdessen müssen Volumes nun durchgereicht werden. Beispiel:

host directory /opt/server/www/blog-artifacts -> act_runner volume /tmp/blog-artifacts –> job container volume /tmp/blog-artifacts

Das :z im Volume vom act_runner wird jetzt wichtig. Es zeigt Docker gegenüber an, dass dieses Volume zwischen Containern geteilt wird. Diese Volumes müssen nicht nur in der docker-compose.yml von act_runner angegeben werden, sondern auch die Job-Skripte im Ordner .gitea/workflows/ sind jetzt entsprechend anzupassen. Hier wird das :z auf der “rechten Seite” hingegen nicht benötigt.

“is not a valid volume”

Allem Aufwand zum Trotz laufen meine Jobs noch immer nicht durch. Dieses Mal wegen einer Fehlermeldung, die mir bereits bekannt vorkam:

# Runner step: Set up job
[/tmp/blog-artifacts] is not a valid volume, will be ignored

Also rein in die config.yml von act_runner und die Volume-Namen hinzufügen:

# /gitea/runner/config.yml
# [...]
 valid_volumes: ["/tmp/blog-artifacts", "/tmp/lectures-artifacts"]
# [...]

In dieser Datei kann ich privileged: false stehen lassen, denn der Job Container selbst benötigt anders als act_runner keine Kernel-Features.

Berechtigungen korrekt setzen

Nun erhalte ich erneut Permission Denied Fehlermeldungen beim Ausführen meiner Jobs, wenn auch nicht direkt im ersten Schritt der Aktionen. Da ich die Volume-Pfade jetzt bis ins Kleinste geprüft habe, kann es eigentlich nur noch an den Ordnerberechtigungen auf der Host-Maschine liegen.

Damit die vom Job-Container erzeugten Artefakte durch die Volumes auf meinem Host abgelegt werden können, muss ich das zu schreibende Verzeichnis und alle Unterordner -R an den vorher definierten, nicht-privilegierten User ID=1000 übergeben:

schallbert@machine:~# chown -R 1000:1000 /target/path/to/artifact/

Endlich funkioniert alles reibungslos und ich habe der (unwahrscheinlichen, aber möglichen) Übernahme meines Host-Systems durch bösartige Job-Container einen Riegel vorgeschoben.

Rate limiter für Gitea

Schallbert — Fri, 25 Jul 2025

Hier halte ich eine Schritt-für-Schritt Anleitung fest, die das Problem meiner Gitea-Abstürze lösen soll. Die Erfahrung aus der Erstanwendung eines Rate Limiters für meinen Blog lasse ich hier einfließen mit dem Ziel, dass die Anwendung robuster läuft und gegen ungerichtete Denial of Service Attacken geschützt wird.

Schritt 1: Log-Quelle für rate limiter festlegen

Gitea erzeugt natürlich selbst Logs, theoretisch bis herunter auf Zugriffsebene durch externe Clients. Doch schaffte ich es in der Vergangenheit nicht, Giteas Access-Logs aus Docker auszuleiten. Daher geben wir jetzt dem als Reverse Proxy angeflanschten Caddyserver die Anweisung, Logs stellvertretend zu erstellen. In ihnen tauchen dann Zugriffe auf das Webinterface von Gitea auf.

In der Caddyfile sieht das Log-Modul total unspektakulär aus.

# /caddy/Caddyfile

#[...]
log {
 output file /log/gitea/access.log
 }

Internen Traffic vom Log ausschließen

Nun schaue ich die Logs mal an und sehe Einträge, die ich gar nicht haben will. So erzeugt act_runner zum Beispiel alle zwei Sekunden einen Fetch Task POST nach Gitea und alle zehn Sekunden einen GET Request mit demselben Ziel als Health check. Diese brauchen für mich im Log gar nicht erst aufzutauchen. Mein erster Gedanke hier war, einfach Anfragen von internen IP-Adressen nicht zu loggen. Da Caddy allerdings als Reverse Proxy fungiert, laufen ausnahmslos alle IP-Adressen “intern”.

Also muss ich act_runner spezifische Logs anders erkennen:

# /caddy/Caddyfile

#[...]
git.schallbert.de {
 reverse_proxy * http://gitea:3000

 # Enable logging for fail2ban, don't log for runner
 log_skip /api/actions*
 log {
 output file /log/gitea/access.log
 }
}

Die log_skip Direktive weist caddy nun an, keine Logs für Zugriffe auf /api/actions* mehr anzulegen.

Reverse-Proxy: Remote IPs anzeigen

Dennoch habe ich noch immer ein Problem: Wenn im Log alle externen Anfragen auf einer internen IP-Adresse hereinkommen, wie soll ich “böse” Anfragen dann wegblocken? Eine Websuche zeigt, dass dies für Reverse Proxy in Docker ein üblicher Stolperstein ist. Leider helfen mir viele Lösungen nicht, da sie andere Serversoftware wie nginx verwenden oder andere Services hinter ihren Proxies laufen haben als Gitea.

Doch tatsächlich ist es ganz einfach: Nur eine Zeile muss an der richtigen Stelle in die Caddyfile eingefügt werden und schon kommen die remote IP-Adressen unverfälscht rein.

# /caddy/Caddyfile

#[...]
git.schallbert.de {
 reverse_proxy * http://gitea:3000 {
 trusted_proxies 172.16.0.0/12 # Docker-internal netwock traffic runs with these IPs
 }
#[...]

Die Direktive trusted_proxies teilt Caddy mit, dass dem von Docker bereitgestelltem Netzwerk vertraut werden kann. Somit wird die eigentliche Quell-IP angezeigt statt der internen Schnittstelladresse des Containers. Genau das brauche ich, um die Adressen später mit fail2ban analysieren zu können.

Schritt 2: Anwendungsfall bestimmen

Schauen wir uns an, wie viele HTTP 200 ok Anfragen im Grenzfall zwischen Normalnutzung und “abuse” kommen. Dazu surfe ich auf Gitea herum und klicke einen Haufen Dinge an, wie ich das als Mensch sonst nie in der Geschwindigkeit tun würde. Danach mache ich eine Auswertung der Logs.

Damit haben wir erste Richtwerte für den Rate Limiter.

# rate limiter tests
findtime = 10s
maxretry = 10
bantime = 6h

Schritt 3: Fail2ban konfigurieren

Anschließend konfigurieren wir Filter und Jail-Datei von fail2ban so, dass sie die oben definierten Logs analysieren.

Filter

Ich verwende hier schlicht denselben Filter für meinen Rate-Limiter aus dem vorherigen Artikel wieder. Uns interessieren nur erfolgreiche Anfragen, die wir innerhalb eines Zeitfensters zählen.

Jail

Ich verwende die Werte aus den rate limiter Tests 1:1 hier in der Jail-Datei weiter. Als Filter verweise ich auf caddy-ratelimit (Link oben).

# /fail2ban/config/fail2ban/jail.local
# [...]

[gitea-ratelimit]
enabled = true
chain = DOCKER-USER
port = http,https
filter = caddy-ratelimit
logpath = /var/log/caddy2/gitea/access.log
findtime = 10s
maxretry = 10
bantime = 6h

Mit einem Neustart von fail2ban schalte ich den Schutz scharf.

Schritt 4: Rate limiter testen

Hier gehe ich genauso vor wie in meinem Artikel fail2ban with caddy und komme zum selben Ergebnis. Es funktionert!

Rate limiter mit Caddy und fail2ban

Schallbert — Thu, 10 Jul 2025

Hier beschreibe ich, wie man das meist zur Abwehr unerlaubter Zugriffsversuche eingesetze Werkzeug fail2ban auch zur Begrenzung der Anzahl von erfolgreichen Zugriffen innerhalb eines definierten Zeitfensters verwenden kann. Dies nennt man “rate limiting” und soll denial of service Attacken vereiteln, bei denen mein Server überlastet wird.

Caddy-Logs einschalten

Zuerst müssen wir den Logger des Webservers einschalten. Bei Caddy geht das mit wenigen Zeilen Code, die ich meiner bestehenden Konfiguration hinzufüge:

# caddy2/config/Caddyfile

blog.schallbert.de {
# Define webserver
root * /www/blog
encode gzip
file_server

# Enable logging for fail2ban
log {
output file /log/blog/access.log
}

# [...]

Ab jetzt werden im angegebenen Pfad Logs angelegt, die ich mit einer logrotate-Konfiguration verwalte.

Fail2ban als Rate Limiter konfigurieren

Nochmal kurz zur Wiederholung: fail2ban greift auf die Paketfilter-Regeln der Maschine zu und modifiziert sozusagen ihre Firewall, um dynamische Angriffe abzuwehren. Damit dies funktioniert, müssen fail2ban Logdateien zur Verfügung gestellt werden, die eine Host-Applikation wie beispielsweise ein Webserver erzeugt und IP-Adressen der Client-Rechner enthalten.

Vorüberlegung: “http 200 OK” als Filter?

Auch normale, zulässige Zugriffe 200 OK müssen für meinen Rate Limiter zählen.

Um ein Gefühl zu bekommen wie der Logger Zugriffe aufzeichnet, werfe ich einen Blick in die Logs. Ich lasse mir die Anzahl Einträge zurückgeben, die einen Status 200 OK enthalten. Dazu führe ich mit grep eine Suche durch und lasse mir die Anzahl Treffer zeilenweise per wc -l ausrechnen.

schallbert@machine:/var/log/caddy2/blog# grep -o '"status":200' access.log | wc -l
847

Gut, es hat heute also bereits 847 Zugriffe gegeben, die 200 OK zurückgemeldet bekommen haben. Nun rufe ich selbst mal die Landing page meiner Blogseite auf und lasse mir dann die Artikelübersicht anzeigen.

schallbert@machine:/var/log/caddy2/blog# grep -o '"status":200' access.log | wc -l
858 // after calling blog.schallbert.de
rschallbert@machine:/var/log/caddy2/blog# grep -o '"status":200' access.log | wc -l
882 // page loaded after clicking "Posts" button

Whow, das waren 35 Einträge für zwei Klicks! Wenn ich mir das Log so ansehe, dann erklären sich die vielen Zeilen mit Assets - sprich Bildern und Logos, die geladen werden.

Damit ist leider klar, dass das Filterkriterium status:200 für meinen Rate Limiter nicht ohne Weiteres funktionieren kann. Denn die Anzahl Meldungen hängen maßgeblich von dem jeweiligen Artikel ab. Ich müsste also eine Grenze definieren, über der kein normaler Mensch Zugriffe auf mein Blog erzeugt.

Um nur “echte” Zugriffe auf meine Seiten zu zählen, muss ich die Assets in den Logs irgendwie ausschließen. Glücklicherweise gibt es dafür eine einfache Direktive in Caddy.

# caddy2/config/Caddyfile

 # Enable logging for fail2ban
 log_skip /assets*
 log {
 output file /log/blog/access.log
 }

log_skip sorgt nun dafür, dass alle Zugriffe auf Dateien im assets/-Ordner und darunter nicht mitgeloggt werden.
Das Verhalten von Fail2ban wird mittels zweier Konfigurationsdateien festgelegt:

Ordner `filter.d`

filter.d/<filter-name>.conf beinhaltet die Definition eines zu betrachtenden Ereignisses. So kann die failregex ein “Seite nicht gefunden” http 404 Statuscode ebenso zum Auslösen des Paketfilters verwendet werden wie der erfolgreiche Zugriff für den Aufbau meines Rate Limiter, welcher auf 200 OK reagiert. Abgeschrieben habe ich für die Regex bei Rafael Kassner.

# /opt/fail2ban/config/filter.d/caddy-ratelimit.conf

[Definition]
failregex = "client_ip":"<HOST>"(.*)"status":200
datepattern = \d+
ignoreregex =

Außerdem werden in der Datei weitere Randbedingungen bestimmt, z.B. das Datumsformat datepattern an den Log-Output des zu schützenden Systems angepasst.

Datei `jail.local`

jail.local bestimmt die Bedingungen, bei deren Eintritt der Paketfilter für die Client-IP aktiv wird und weitere Zugriffsversuche blockt. Für den Einsatz als Rate Limiter benötige ich folgende Felder:

findtime - das Zeitfenster, in welchem Angriffe gezählt werden, maxretry ist die Anzahl zulässiger Versuche im Zeitfenster und bantime ist die Zeit, für die geblockt wird. ignoreip ist meist per Werkseinstellung auf die relevanten internen IP-Adressen vorkonfiguriert. In meinem Falle funkt act_runner zum Beispiel an intern gitea zur Abfrage, ob neue Automatisierungsaufgaben anliegen. Diese Zugriffe will ich auf keinen Fall behindern.

Das im Folgenden verwendete Beispiel für fail2ban zeigt den Rate Limiter auf meinem Blog. Am Ende sind Dateien und Log-Einträge für gitea im Wesentlichen gleich. Nur Filternamen und Parameter unterscheiden sich voneinander durch die unterschiedlichen Anforderungen an Webseite und DevOps-Platform.

# /opt/fail2ban/jail.local
# ...

[caddy-ratelimit]
enabled = true
chain = DOCKER-USER
action = iptables-multiport
port = http,https
filter = caddy-ratelimit
logpath = /var/log/caddy2/blog/access.log
findtime = 10s
maxretry = 10
bantime = 6h

Sind diese beiden Dateien konfiguriert, kann man fail2ban neu starten und sich die Logs anschauen. Wenn man noch Fehler in den Dateien hat, gibt fail2ban folgendes aus:

ERROR Errors in jail 'caddy-ratelimit'. Skipping...

Tritt dies auf, kann z.B. das Jail nicht dem Filter (muss gleichnamig sein!) nicht zugeordnet werden, eine Feld-Definition wie maxretry ist falsch getippt oder ein Zahlenformat kann nicht gelesen werden. Wenn alles gut läuft, lautet der Eintrag:

Reading config files: /etc/fail2ban/filter.d/caddy-ratelimit.conf

Rate Limiter testen

Nun möchte ich prüfen, ob alles wie erwartet funktioniert.

Filter-Regex überprüfen

Als ersten Schritt schaue ich auf den Filterbegriff und prüfe, ob er in den Logs zuverlässig gefunden wird. Praktischerweise hat fail2ban hierfür ein passendes Werkzeug eingebaut: fail2ban-regex <logfile> <filter>. Ich kann also schlicht die Filterdatei und ein Test-Logfile eingeben und sehe dann, ob ich Treffer bekomme.

fail2ban-regex ./access.log /etc/fail2ban/filter.d/caddy-ratelimit.conf 

Running tests
=============

Use filter file : caddy-ratelimit, basedir: /etc/fail2ban
Use datepattern : \d+ : \d+
Use log file : ./access.log.2
Use encoding : UTF-8

Results
=======

Failregex: 2009 total
|- #) [# of hits] regular expression
| 1) [2009] "client_ip":"<HOST>"(.*)"status":200
`-

Ignoreregex: 0 total

Date template hits:
|- [# of hits] date format
| [2685] \d+
`-

Lines: 2685 lines, 0 ignored, 2009 matched, 676 missed
[processed in 0.12 sec]

Quantitativ bekomme ich, was ich erwarte: das oben beschriebene Suchverfahren per grep liefert mir exakt dieselben Ergebnisse.

Jail überprüfen

Als nächsten Schritt muss ich testen, ob der Rate Limiter auch greift. Dafür simuliere ich mir Logeinträge. Die Jail-Regeln nehme ich für diesen Test stark zurück, sonst muss ich zu viele Eingaben in kurzer Zeit erzeugen.

# /opt/fail2ban/jail.local TEST
# ...

[...]
findtime = 10s
maxretry = 2
bantime = 100s

Nach einem Neustart von fail2ban erzeuge ich mir eine zweite Konsole, wo ich Log-Einträge simulieren kann. Dabei müssen mindestens Zeitpunkt, IP-Adresse des Aufrufenden und Status enthalten sein; ich gehe aber auf Nummer sicher und nehme vollständige Einträge.

echo '{"ts":1751246139,"remote_ip":"1.1.1.1","status":200,[superLongIrrelevantOtherStuffForFiltering]}' >> /var/log/caddy/blog/access.log

Dies gebe ich mehrfach ein, um über mein Limit von 2 retries zu kommen.

In der ersten Konsoleninstanz prüfe ich anschließend den fail2ban-Status für den entsprechenden Filter.

fail2ban-client status caddy-ratelimit
Status for the jail: caddy-ratelimit
|- Filter
| |- Currently failed:	0
| |- Total failed:	0
| `- File list:	/var/log/caddy2/blog/access.log
`- Actions
 |- Currently banned:	0
 |- Total banned:	0
 `- Banned IP list:

Das war nichts. Warum offenbart die fail2ban-Logdatei:

# /fail2ban/config/log/fail2ban/fail2ban.log
WARN [caddy-ratelimit] Ignoring all log entries older than 20s; # probably messages generated within a fail2ban restart period

Also nochmal mit passenden Zeitstempeln. Diese muss ich aus der aktuellen Systemzeit ($(date +%s.%N)) ziehen, wenn ich sie ständig anpassen muss. Daher nehme ich eine vollständige Logzeile her, modifiziere sie auf die IP-Adresse 1.1.1.1 und füge passende Zeitstempel ein:

 echo "{\"level\":\"info\",\"ts\":$(date +%s.%N),\"logger\":\"http.log.access.log0\",\"msg\":\"handled request\",\"request\":{\"remote_ip\":\"1.1.1.1\",\"remote_port\":\"38229\",\"client_ip\":\"1.1.1.1\",\"proto\":\"HTTP/1.1\",\"method\":\"GET\",\"host\":\"blog.schallbert.de\",\"uri\":\"/vacuum-clamping/\",\"headers\":{\"Accept-Encoding\":[\"gzip, deflate, br\"],\"Connection\":[\"keep-alive\"],\"User-Agent\":[\"Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/121.0.0.0 Safari/537.36 Edg/121.0.0.0\"],\"Accept\":[\"text/html,application/xhtml+xml,application/xml;q=0.9,image/webp,*/*;q=0.8\"],\"Accept-Language\":[\"en-US,en;q=0.5\"]},\"tls\":{\"resumed\":false,\"version\":772,\"cipher_suite\":4865,\"proto\":\"http/1.1\",\"server_name\":\"blog.schallbert.de\"}},\"bytes_read\":0,\"user_id\":\"\",\"duration\":0.001207354,\"size\":12290,\"status\":200,\"resp_headers\":{\"Last-Modified\":[\"Tue, 10 Jun 2025 19:33:01 GMT\"],\"Content-Encoding\":[\"gzip\"],\"Server\":[\"Caddy\"],\"Alt-Svc\":[\"h3=\\\":443\\\"; ma=2592000\"],\"Vary\":[\"Accept-Encoding\"],\"Etag\":[\"\\\"gzip\\\"\"],\"Content-Type\":[\"text/html; charset=utf-8\"]}}" >> access.log

Nach mehrmaligem Aufruf dieses gebastelten Kommandos erhalte ich nun

fail2ban-client status caddy-ratelimit
Status for the jail: caddy-ratelimit
|- Filter
| |- Currently failed:	1
| |- Total failed:	11
| `- File list:	/var/log/caddy2/blog/access.log
`- Actions
 |- Currently banned:	1
 |- Total banned:	4
 `- Banned IP list:	1.1.1.1

Das sieht super aus. Auf zum letzten Schritt.

Paketfilter überprüfen

Wenn wir nun einmal in die Logs schauen, müsste unser [caddy-ratelimit] Jail nun bei jeder “normalen” Anfrage triggern.

schallbert@machine: nano fail2ban/config/log/fail2ban/fail2ban.log

 <timestamp> <id> INFO [caddy-ratelimit] Found <IP a>
 <timestamp> <id> INFO [caddy-status] Found <IP b>
 <timestamp> <id> INFO [caddy-ratelimit] Ignore 172.18.0.1 by ip
 <timestamp> <id> INFO [caddy-status] Ignore 172.18.0.1 by ip
 <timestamp> <id> INFO [caddy-ratelimit] Found <IP c>
 <timestamp> <id> INFO [caddy-ratelimit] Found <IP c>
 <timestamp> <id> INFO [caddy-status] Found <IP c>
 <timestamp> <id> INFO [caddy-status] Found <IP c>
 <timestamp> <id> INFO [caddy-ratelimit] Found <IP d>
 <timestamp> <id> INFO [caddy-status] Found <IP d>
 <timestamp> <id> INFO [caddy-status] Found <IP e>
 <timestamp> <id> INFO [caddy-ratelimit] Found <IP e>
 <timestamp> <id> INFO [caddy-ratelimit] Found <IP f>

Um die ganze Kette getestet zu haben müssen wir jetzt noch prüfen, ob die entsprechende IP-Adresse auch wirklich in der Hardware geblockt ist. Dafür gebe ich ein:

schallbert@machine:~# iptables -n -L | grep "1.1.1.1"
REJECT all -- 1.1.1.1 0.0.0.0/0 reject-with icmp-port-unreachable

Scheint ja alles in Ordnung zu sein. Für einen letzten Test von einer externen IP-Adresse rufe ich im Browser einen Link Checker auf, der meine Webseite crawlen und damit den Rate Limiter auslösen soll. Obwohl dieser 44 Links in kürzester Zeit durchläuft, wird der Test als “bestanden” angezeigt. Sehr merkwürdig, [caddy-ratelimit] hätte anschlagen müssen!

iptable-chain INPUT statt FORWARD

Verwirrt schaue ich mir mal die ganze iptable an. Parallel suche ich mir die IP-Adresse des Link Checker heraus. Sie taucht in den iptables auf. Und trotzdem wird offensichtlich nicht geblockt. Woran das liegt? Ein genauer Blick zeigt:

Chain INPUT (policy ACCEPT)
target prot opt source destination 
f2b-caddy-ratelimit tcp -- 0.0.0.0/0 0.0.0.0/0 multiport dports 22

Problem hier ist, dass mein Jail auf der INPUT-Chain liegt. Die Anfragen gehen aber doch nicht direkt an meine Server-Hardware, sondern werden über Docker an Caddyserver weitergeleitet. Um zu funktionieren, muss ich auf der FORWARD-Chain landen, wo DOCKER-USER bereits ist. Sehr merkwürdig, hatte ich doch in der jail.local extra chain = DOCKER-USER angegeben. Irgend etwas muss diese Definition überschreiben.

Ein unscheinbarer Forenpost zusammen mit dem Kommentar multiport im iptables-Print bringt mich auf die Lösung: Die action = iptables-multiport Direktive überschreibt mein chain = DOCKER-USER Statement, denn in der zugehörigen Konfigurationsdatei iptables.conf wird folgendes gesetzt: chain = INPUT.

Also lösche ich den action Eintrag einfach, sodass fail2ban auf den Default für DOCKER-USER zurückfällt: multiport dports 80,443. Nun taucht der Jail-Name auch korrekt in iptables auf.

schallbert@machine:~# iptables -n -L
Chain DOCKER-USER (1 references)
target prot opt source destination 
f2b-caddy-ratelimit tcp -- 0.0.0.0/0 0.0.0.0/0 multiport dports 80,443

Erfolg genießen

Endlich zeigt ein weiterer Link Check, dass mein Rate Limiter funktioniert.

Gitea stürzt ab: Zu viele Anfragen

Schallbert — Mon, 30 Jun 2025

Hier möchte ich kurz darstellen, wie ein Absturz eines Dienstes meinen Server über Stunden wiederholt lahmgelegt hat. Und dies so gründlich, dass ich nur aus der Konsole des Anbieters überhaupt einen Neustart durchführen konnte. Ich erkläre, wie es dazu kam und wie ich dieses und ähnliche Probleme in Zukunft vermeiden möchte.

Ich wurde angegriffen. Oder?

Ich saß gerade an einem Artikel, den ich später posten wollte. Zur Sicherheit erstellte ich wie üblich einen Commit und wollte ihn auf meine Gitea-Instanz schieben. Doch mein git push Befehl lief einfach nicht durch.

Verwundert versuchte ich, meine Webseite aufzurufen. Zurück kam:

Merkwürdig. Anschließend wollte ich mich auf meinem Server einloggen, um nach dem Rechten zu sehen: ssh <servername>. Wieder blieb das Terminal ohne Reaktion. Mist!

Timeout. Als letzte Rettung meldete ich mich bei meinem Hoster an und schaute auf die Graphen des Servers:

Oh, was ist denn da los? Nun versuche ich über die Weboberfläche, den Server herunterzufahren. Klappt auch nicht. Erst ein harter Neustart ist erfolgreich. Ich kann mich wieder per SSH einloggen und sehe, dass auch alle Docker-Container wieder ganz normal hochfahren.

Was war passiert?

Gut, dass ich eine Woche lang alle Logs aufbewahre. So und über die Auslastung der Maschine über Zeit kann ich einigermaßen rekonstruieren, was passiert ist.

Welche Logs helfen?

Crash lokalisieren! Auslösende Anwendung finden im kern.log, Zeitstempel notieren.
Gibt es systemweite Auswirkungen oder andere Dienste, die beeinträchtigt werden? Im syslog nachsehen.
Falls der Verdacht aufkommt, das System sei möglicherweise gehackt worden: auth.log hat die Details.
Sollte die betroffene Anwendung im Container laufen, helfen entsprechende Logs dort möglicherweise weiter.
Logs der Anwendung selbst sichten. Besonders die Zeit kurz vor dem Crash ist interessant.

Und hier nochmal im Detail die Logs, die ich mir für meine Verhalten angesehen habe und wo sie zu finden sind.

log name	purpose	relevant content for this issue
/var/log/syslog	System-wide (bare metal) messages	(docker) warning: “health check for container `<ID>` timeout” (containerd) error: “ttrpc: received message on inactive stream”
/var/log/auth.log	Contains authentication messages from external hosts, in my case mostly SSH	None
/var/log/kern.log	Logs all app, service, daemon and system crashes	Out of memory: Killed process `<ID>` (`<serviceName>`)
[.]/gitea/log/gitea.log	Protocol for requests, actions on Gitea’s web interface, repo changes etc.	`GET` requests, crash/restart indications
docker container logs `<containerID>`	Docker’s logs for the container in question	Received signal 15; terminating. (SIGTERM)

kern.log/syslog

Hier sehe ich neben dem Stack trace, was genau passiert ist. Die am besten verständlichste Meldung ist folgende:

Out of memory: Killed process `<ID>` (gitea)

Gitea ist also der Stecker gezogen worden, weil es praktisch alle Systemressourcen gezogen hatte. Wenn ich im Log nach oben scrolle, sehe ich ein paar Minuten vorher:

<timestamp> <machineName> dockerd[716]: level=warning msg="Health check for container <ID>"
<timestamp> <machineName> dockerd[716]: level=error msg="stream copy error: reading from a closed fifo"

Bereits hier sehe ich Warnungen, dass der gitea-Container nicht sauber arbeitet. Ein weiterer Vorteil, den das Einbauen von “Healthchecks” in der docker-compose.yml Datei hat. Über Zweck und Einbau von Healthchecks in docker hatte ich aus anderen Gründen bereits einen Artikel verfasst.

gitea.log

Folgender Log-Eintrag zeigt wegen eines Bugs in einem Submodul indirekt an, dass Gitea gerade neu gestartet ist:

cmd/web.go:205:serveInstalled() [W] Table system_setting Column version db default is , struct default is 1

Und weiter oben im Log nun:

Sehr interessant. Die highlight.css liegt in meinem öffentlichen Repo. Auf ihrer Grundlage erhält die Seite lectures.schallbert.de ihr Aussehen. Diese Datei ist ziemlich groß, fast 1MiB. Und sie wird hier gleich zig male geladen, und das praktisch für jeden Commit.

Nun schaue ich mir weitere Crashes in der Vergangenheit an. Immer sind es bursts von GET-Befehlen auf große Dateien oder die Anforderung von compares zwischen zwei Branches des Repository, die einem Aufhängen meines Servers vorausgehen.

Wer steckt dahinter?

Alle crash-auslösenden Requests kommen aus dem selben IP-Adressraum. Die Abstürze starteten bereits vor ein paar Wochen. Zumeist aber zu Tageszeiten, die ich (und anscheinend auch viele meiner LeserInnen) nicht mitbekamen. Und nach ein paar Minuten war der Server stets wieder im Normalbetrieb.

Oha, die Spur führt zu Google’s Cloud Platform (GCP).

Aber ich hatte doch Robots ausgesperrt?

In der Tat hatte ich die Suchmaschinenindexierung für Gitea gestoppt. Merkwürdig. Oder habe ich es hier gar nicht mit einer der Google-spiders oder “KI”-Scraper, sondern mit einem fiesen Hacker zu tun, der sich bei “Google Cloud” eine virtuelle Maschine gemietet hat?

Log-Recherche: Wie häufig wird die Datei angefragt?

Ein Spider würde ja höchstens einmal alle paar Wochen alle meine Seiten durchsuchen, richtig? Und sich hoffentlich nicht über meine robots.txt hinwegsetzen. Erst recht nicht würde ein Crawler mehrfach und in kurzen Abständen denselben Request stellen, oder?

Zum dies zu prüfen, suche ich in den *Gitea Logs nach Einträgen von GET-Anfragen auf einer der großen und damit ressourcenintensiv zu übertragenen Dateien:

gunzip gitea.log.<date.rotateID>
grep "<filename>" gitea.log.<date.rotateID>

In der Liste sehe ich, dass dieselbe Anfrage auf dieselbe Zieldatei von derselben IP-Adresse mehrfach und binnen Sekunden gestellt wird. Kurz vor dem Crash benötigt mein Server schon fast 4sec, um die Anfrage zu bedienen.

Auch sehe ich, dass sich die IP-Adresse alle paar Stunden ändert.

Einen DoS-Angriff parieren

Zusammenfassend muss ich zum Schluss kommen, dass ich aus dem Adressraum des GCP per Denial-of-service angegriffen werde.

Um ein bisschen mehr Hintergrundwissen zu sammeln, besuche ich ein paar Websites zum Thema. Dort lerne ich, dass gitea auf meinem Server unter einer Application Layer Attack zusammenbricht. Jetzt da ich weiß, was passiert und wie das Problem heißt, fällt das Finden von Lösungen gleich viel leichter 😅

Ich will mich natürlich nicht kampflos ergeben, indem ich meine Gitea-Instanz dauerhaft vom Netz nehme. Also, welche Optionen habe ich?

Mehr Ressourcen bereitstellen

Zugegeben, meine Maschine hat nur 40GB Speicher und 2GB VRAM sowie eine mickrige 2-Kern CPU aus 2009. Ich könnte einen leistungsfähigeren Server buchen, um Lastspitzen besser abreiten zu können. Doch dies würde den Angriff nicht verhindern, sondern nur seine Auswirkungen abmildern.

Rate limiting direkt im Webserver

Rate limiter begrenzen die Anzahl Anfragen eines Clients innerhalb eines Zeitfensters. Dadurch werden die Ressourcen des Servers geschont. Dies ist eine “weiche” Abwehr von Dos-Attacken, denn auslösende IP-Adressen werden mit einer Fehlermeldung kurzzeitig und sanft abgewehrt. Üblicherweise wird HTTP status code 429 “Too Many Requests” zurückgegeben, wenn der Limiter eingreift.

Gitea verfügt über keinen Rate Limiter. In meinem Setup läuft Gitea hinter einem reverse proxy, der von meinem Caddyserver bereitgestellt wird. Hier also müsste ich ansetzen. Für Caddy gibt es Rate limiter nur als externe Module, welche manuell in xcaddy nachinstalliert und eingerichtet werden müssen.

Blocken mit IP-table Regeln

Hier könnte man sich erneut fail2ban hernehmen und mehrfache Anfragen derselben Ressource von einer IP-Adresse schlicht blocken. Gitea hat in der Dokumentation eine Beschreibung der Einrichtung. In meinem Falle müsste ich für die Umsetzung dort weitermachen, wo ich bereits einmal aufgegeben hatte und damit nicht nur SSH, sondern auch normale Seitenaufrufe überwachen.

Für mich klingt diese Lösung am Sinnvollsten, denn sie trennt klar Funktionen in verschiedene Anwendungen auf. Ich nutze ausschließlich bei mir bereits verfügbare Applikationen: Caddy würde die Zugriffslogs bereitstellen und fail2ban müsste sie lesen und Filter in der Konfoguration jail.local so setzen, dass es sich wie ein Rate Limiter verhält.

Jetzt schaue ich mal, wie ich Caddy entsprechend mit fail2ban verbinden kann. Den weiterführenden Artikel Fail2ban mit Caddy einrichten verlinke ich direkt mal 🙂

Webshop selber aufsetzen - Teil3

Schallbert — Sun, 15 Jun 2025

Die Auswahl anhand von Leitfragen

Welche Lösung ist einfach gestrickt und mit wenig Zeitaufwand zu installieren?
Welche Lösung ist leichter zu pflegen?
Bei welchem System kann ich als Betreiber am einfachsten nachvollziehen, wie was funktioniert (Transparenz, Abhängigkeiten)?
Wo ist die Angriffsoberfläche geringer?

Hier fehlt noch einiges!

In den letzten Wochen ist mir die Lust nach einem eigenen Webshop etwas vergangen, da ich mich erst um die Sicherheit meines Servers und die Einarbeitung alter, fast fertiger Projekte kümmern wollte. Ich werde diese Serie vervollständigen, sobald mich das ich-will-was-Neues-machen-Fieber erneut packt.

Haltet durch! Schallbert

Webshop selber aufsetzen - Teil2

Schallbert — Thu, 15 May 2025

Ein paar Optionen für die Webshop-Software

Gehen wir mal davon aus, dass in der Vorauswahl nur Software landet, die meine Anforderungen zumindest teilweise erfüllt. Im Folgenden möchte ich ein paar mögliche Ecommerce-Lösungen vorstellen.

Shopify

Shopify ist eine alles-inklusive-Paketlösung für den Onlinehandel. Shopify Inc. hat ihren Hauptsitz in Kanada und wickelt das europäische Geschäft über Irland ab. Die auf der Website zu findenden Bereiche Rechtliches sowie die Komplexität der Informationsdarstellung zum Thema Datenschutz lassen mich vermuten, dass Shopify ein multinationaler Konzern ist - und nicht nur die Onlineshops selbigen zur Verfügung stellt.

Aber zurück zum Thema.

Die Domain sowie das Hosting sind bei Shopify im Preis inbegriffen und der eigene Shop kann ohne Programmierkenntnisse per Weboberfläche, Auswählen eines Themes und Einstellen von ein paar Parametern in kurzer Zeit erstellt werden. Shopify besitzt eine ausführliche Dokumentation und bietet Fortbildungen und allerlei weitere Dienstleistungen für ihre Abonnenten an.

Doch wo bleibt da der Spaß? Schließlich betreibe ich ein Techblog und bin kein Geschäftsmann im eigentlichen Sinne. Ein bisschen Programmieren muss da schon drin sein. Außerdem gefällt mir als Open-Source-Fan das Konzerngehabe (man schaue sich ihre moderne, mit automatisch abspielenden Videos ausgestattete, auf Marketing-Zwecke durchoptimierte Website an) nicht so besonders gut. Die Konfigurierbarkeit ist bestenfalls mittelmäßig und die Optimierung auf Suchmaschinenergebnisse muss ich wie bei den meisten anderen Lösungen auch selbst erledigen. Was Datenschutz und Sicherheit angeht, betreiben sie die übliche Compliance- und Stand-der-Technik-Kommunikation; ich kann also nicht dahinter schauen und muss davon ausgehen, dass sie ihre Kunden auch im eigenen Interesse gut schützen.

Shopify bezeichnet sich selbst als closed-source SaaS platform.

Daher streiche ich diese Plattform von meiner Liste präferierter Webshoplösungen, weil ich mich nicht ohne Not von Wohl und Wehe Dritter abhängig machen möchte. Bei Shopify hätte nämlich nicht ich die Kontrolle über Abokosten oder “meinen” Anteil an der Cloud, sondern Shopify. Nicht ich kann bestimmen, wie viele Transaktionen im “Plan” inklusive sind, sondern Shopify. Nicht meine Kunden blieben Herren ihrer Daten, sondern Shopify oder ein von ihnen mit der Abwicklung beauftragtes Drittunternehmen.

Wordpress / WooCommerce

Ich kenne Wordpress nur als Moloch. Die Eierlegende Wollmilchsau, die durch eine unübersichtlich gewordene Anzahl an Plugins, Erweiterungen und Funktionen alles kann, was man sich nur wünschen kann. Und vieles mehr, was man nicht braucht.

Aber es ist quelloffen, kostenfrei und wird laut eigener Darstellung von sehr, sehr vielen Shopbetreibern genutzt. Schauen wir uns also mal die bekannteste Ecommerce-Erweiterung zu Wordpress an: WooCommerce.

Ich fand auf Anhieb zig Anleitungen zum Aufsetzen eines WooCommerce-Shops (Beispielsweise von GeeksForGeeks oder Themeisle), also verzichte ich im Folgenden auf eine eigene Darstellung.

Nach dem Querlesen einiger Anleitungen fasse ich zusammen:

Ein WooCommerce-Shop lässt sich einfach per Assistent aufsetzen und konfigurieren
Es stehen sehr viele Themes zur Verfügung und einfach einzubindende Shopdesigns bieten für jeden Geschmack eine passende Optik
Es hilft, bereits eine Wordpress-Seite zu haben und etwas Basiswissen bezüglich Domains, DNS und Hostern zu besitzen
Viele Zahlungsdienstleister und einige Versandabwickler sind vorkonfiguriert auswählbar
Es gibt eine Menge YouTube-Lehrvideos zum Thema und eine ausführliche Dokumentation liegt ebenfalls vor
Zahllose Plugins erlauben die Optimierung des Shops auch auf sehr spezialisierte Gebiete und Einsatzzwecke
Allerdings steht dieser Optionsvielfalt gegenüber, dass die Auswahl der “besten Lösung” schwer fallen kann und dass Optimierungen der Seite hinsichtlich Geschwindigkeit und Auffindbarkeit komplex werden können

Alles in allem wirkt WooCommerce auf mich wie eine ausgewogene Mischung aus “Ich will schnell etwas Brauchbares zusammen klicken” und “Ich möchte alles konfigurieren und umbauen können”.

Snipcart

Snipcart würde ich als “Shopping-Plugin” für eine beliebige Website verstehen. Auch statische Websites, die eigentlich nur einen Warenkatalog darstellen können, werden mit Snipcart zu einer vollwertigen eCommerce-Lösung. Kernelement ist hier der Warenkorb “cart”, über den der Kaufvorgang abgewickelt wird.

Die Schnittstelle ist das HTML Markup der Webseite. Snipcart wird als JavaScript-Blob eingebunden und per HTML referenziert. Gestaltung und Aussehen läuft über cascading style sheets. In meinem Fall also könnte ich das vorhandene “Tech Stack” bestehend aus einer statischen Jekyll-site mit CD-Pipeline in Gitea auf einer Caddyserver-Instanz auch für den Shop nutzen und mit minimalen Anpassungen eine Optik aus einem Guss für Blog und Shop zaubern. Klingt doch schon einmal prima.

Snipcart wird von einer kanadischen Firma in Québec entwickelt. Es bezeichnet sich als “Shopping Cart Platform”. Für die Installation wird ein Account benötigt und man muss die eigene Shopping-Domain ähnlich wie bei der Google Search Console oder Google Analytics im Web-Frontend von Snipcart angeben, um einen sogenannten API-Key zu erhalten. Nur mit diesem wird der JavaScript-Blob später auch korrekt funktionieren.

Und damit kommt das erste größere Problem: Snipcart schränkt meine Freiheit ein.

<link rel="preconnect" href="<https://app.snipcart.com>" />
<link rel="preconnect" href="<https://cdn.snipcart.com>" />

Mir zeigt dies, dass Snipcart die Daten gern bei sich haben will. Ich muss deren content delivery network für die Abwicklung des Bestellprozesses verwenden und bei mir einbinden. Es ist also mitnichten so, dass alle Verbindungen bei mir bleiben und ich den JS-Code von Snipcart “kaufe” und im Browser des Kunden bzw. eine dahinter liegende Datenbanklösung auf meinem Server betreibe.

Wenn einem also volle Autonomie und Kontrolle über die eigene Site nicht super wichtig ist, kann Snipcart eine sehr elegante Shopsystem-Lösung sein. Dies lohnt sich vor allem für bereits bestehende Seiten. Für mich jedoch ist sie damit raus.

OpenCart

OpenCart bietet eine PHP-basiertes Shopmodul kostenlos und quelloffen an. Es kann sowohl als “Software as a Service” über Drittanbieter gebucht wie auch per Github heruntergeladen und auf eigenen Servern bereitgestellt werden.

Installation und Administration geschehen über eine Weboberfläche und ist meines Ermessens nach unkompliziert möglich. Auch im DockerHub findet man ein paar Images, mit welchen man direkt loslegen kann.

OpenCart ist vollständig an die eigenen Bedürfnisse anpassbar. Auch vorgefertigte Themes können eingebunden werden. Aus Neugier habe ich mal ein paar Webseiten angeschaut, die OpenCart einsetzen: Das Shopsystem ist aus meiner Sicht gut strukturiert und einfach zu bedienen. Jedoch ist die Ladegeschwindigkeit der von mir besuchten Beispielseiten nicht immer super schnell.

Im Gesamtpaket halte ich OpenCart mit seiner anpassbaren, leichtgewichtigen Shoplösung in PHP auch durch die immer noch aktive Community (13+ Jahre!) für eine gute Lösung.

Django

Django ist ein Webframework für Python. Es bietet viele Funktionen, ermöglicht Erweiterungen durch schlichtes Einbinden von Python-Modulen und man kann auch als Programmier-Einsteiger schnell funktionierende Lösungen erzeugen. Obwohl es eine Menge Bibliotheken beispielsweise für Websites, Shops wie z.B. django-SHOP, Datenbankeinbindungen, Einbindung von Zahlsystemen usw. gibt, muss alles noch selbst zusammen gesteckt und konfiguriert werden.

Dadurch erhält man zwar volle Kontrolle und eine perfekt an die eigenen Bedürfnisse anpassbare Lösung - doch es gibt auch einen gewichtigen Nachteil: Lernzeit. Die Sicherheit der Datenbank muss selbst hergestellt werden, Validierung von User inputs muss selbst programmiert oder zumindest korrekt konfiguriert werden. Das Abspeichern von Kundenstammdaten passiert standardmäßig erst einmal im Klartext. Zugriffs- und Löschkonzepte müssen selbst erstellt und implementiert werden bzw. man sollte Zeit einplanen, passende Module ausfindig zu machen und zu integrieren.

Sollen Frameworks verwendet werden, empfiehlt es sich vorab eine aktive Wartung durch die Community zu prüfen. Für mich sieht es beispielsweise so aus, als wäre bei django-SHOP bereits seit dem Jahre 2021 keine große Bewegung mehr auf dem Github-Repo. Eine kurze Suche hingegen offenbart eine Menge Alternativen - hier gilt es nun, etwas Passendes ins Auge zu fassen oder gleich selbst das Rad neu zu erfinden 😃

Die Alternative für Anfänger wie mich: ohne Shopsystem

Was ist mit “Ohne Shopsystem” gemeint? Ein formularbasierter Ansatz. Hier schaut sich der User eine statische Website an, die Katalog- und Produktseiten enthält. Zusätzlich sind ein paar Elemente eingeblendet wie ein Dropdown-Menü für Variante und ein Feld für die Stückzahl. Daneben ein schlichter Button. Wird dieser geklickt, so öffnet sich ein Formular, welches automatisch die geklickten Inhalte überträgt und nach Kontaktdaten des Users fragt.

Wird alles ordnungsgemäß ausgefüllt, so erzeugt das Formular beim Absenden eine PGP-verschlüsselte Mail an mich. Ich kann dann die Order analog zu manuell erstellten Bestell-Mails sichten, eine Bestellbestätigung senden und die Zahlung anfordern.

So lässt sich mit wenigen Produkten bei wenigen Kunden ohne großen Aufwand ein Shop-Äquivalent datensparsam umsetzen. Natürlich nicht so bequem wie mit einer Ecommerce-Lösung. Aber für den Anfang reicht das vielleicht trotzdem.

Im nächsten Artikel

Auswahl und Implementierung

Webshop selber aufsetzen - Teil1

Schallbert — Tue, 15 Apr 2025

Dies ist Teil eins der Artikelserie über den Aufbau meines eigenen Webshops. Ich liste Anforderungen und Wünsche für meine Ecommerce-Lösung auf und grenze mich damit auf ein paar passende Software-Lösungen ein, die ich dann für meinen Webshop verwenden könnte.

Was mein Webshop können muss

Für mich als Betreiber soll der Webshop möglichst schlank, transparent und automatisiert operieren. Ich möchte nur wenig Zeit mit Betrieb, Wartung und Pflege verbringen. Zahlungsabwicklung, Verwaltung des Bestellstatus, Kundenregistrierung, Versenden von Kundeninformation sowie eine große Anzahl Schritte im Versandprozess wie Frankieren und Einpflegen von Versandbestätigungen soll automatisiert stattfinden oder zumindest für die Automatisierung vorbereitet werden.

Aber auch für Kunden muss der Webshop verständlich aufgebaut sein: Simpel und mit wenigen Klicks von der Startseite bis zum Checkout, leicht zu bedienen, ähnlich zu anderen gängigen Webshops, mit unkomplizierter Zahlungsabwicklung. Dabei sollen so wenige Daten vom Kunden wie möglich erhoben werden.

Der Webshop muss nur wenige Produkte darstellen. Daher kann die Navigation sehr einfach gehalten werden. Durch die geringe Anzahl Produktkategorien kan möglicherweise komplett auf ein Baumsystem verzichtet werden.

Schauen wir uns mal schnell im Detail an, welche Funktionen der Webshop am Ende bereitstellen muss.

Funktionen für Admins

Produkt anlegen

Titel
Tags
Kurzbeschreibung
Beschreibung
Bilder
Videos
Preis
Steckbrief / Datenblatt / Anleitung

Produkt editieren
Produkt entfernen
Bestellungen verwalten

Schritt quittieren
Schritt erneut starten
Prozess stornieren

Kunden verwalten
- anlegen (sandbox)
- löschen (Datenschutz)

Funktionen für Käufer

Webshop durchstöbern
Produkt(e) konfigurieren oder Produktvariante auswählen (z.B. Farbe, Qualität)
Produkt(e) in einen Warenkorb legen
Warenkorb verwalten
Registrierung vornehmen (optional, nur zur Kundendatenablage und Bestellverwaltung)
Versand wählen
Zahlung vornehmen

Automatische Funktionen

Zahlungsregistrierung
Rechnungserstellung und -Versand
Inventarverwaltung
Versandbenachrichtigung

Nichtfunktionale Anforderungen

Hier liste ich auf, was der Webshop “nebenbei” noch so alles können soll. Alles, was nicht unmittelbar zur Auftragsabwicklung benötigt oder für Kunden sichtbar wird.

Usability Betreiberseite

Der Shop soll mit möglichst geringen Abhängigkeiten zu Software Dritter auskommen und nur diejenigen Module einbinden, die unbedingt benötigt werden. Beispiele:
- Zahlungsabwicklung
- Warenkorb
- Kundenkonto / Adressdaten
- Lagerbestände
- Bestellabwicklung (Mailer) für Käufer
- Rechnungsstellung.
Der Shop soll nur so viele dynamisch erzeugte Elemente enthalten wie unbedingt nötig.

Usability Käuferseite

Der Webshop soll sich wie aktuelle übliche ECommerce-Lösungen anfühlen: Flink, übersichtlich, einfach.
Kein Zwang zum Kundenkonto.
Der Shop soll gängige Zahlungsmöglichkeiten unterstützen (Debit, Kredit, PayPal, Apple/GooglePay etc.). Dabei sind nur lokale (in Deutschland ansässige) Zahlungsdienstleister akzeptabel.
Für den User sollen Lagerbestände bzw. Fertigungszeiten transparent angezeigt werden.

Datenschutz

Der Shop soll nur für die Geschäftsabwicklung notwendige Daten erfassen.
Falls technisch und rechtlich möglich soll der Shop ohne Cookie-Banner auskommen können.
Kundenkonten sollen automatisch nach 2 Jahren der Nicht-Nutzung (mit Ankündigung 2 Wochen vorher) gelöscht werden.

Look & Feel

Hier einige Beispiele für Shopdesigns:

Davon abgeleitete Anforderungen:

Der Webshop soll von Aufbau und Farbgebung her an meine Blogseite erinnern und eine einheitliche Optik bieten.
Es sollen nur statische Fonts ohne Nachladen verwendet werden.
Produktbeschreibungen sollen als Markdown-Dokumente (oder Ähnlich) hochgeladen werden können.

Datenbank- oder Dateilösung?

Es muss nicht immer gleich eine Datenbank sein. Für viele Anwendungen werden nur Bruchteile der Funktionalität gängiger Datenbanklösungen benötigt, doch erhöht sich die Komplexität des Gesamtsystems erheblich. Sollte z.B. gleichzeitiges Schreiben selten oder nie vorkommen und keine starke Verkettung von Daten vorliegen, so kann eine Dateilösung einfacher, schneller und effizienter sein Link zu einer passenden Engineering Kiosk Podcast-Episode.

Andererseits kommen viele Shopsysteme “with batteries included”, verfügen also schon von sich aus über eingebaute und für die Programmierer nahezu transparente Datenverwaltung.

Dateilösung (statische Website)

Auf Betreiberseite soll sich der Webshop so anfühlen wie ein Git-Projekt (everything is a file).
Änderungen im Angebot, Artikelbeschreibung, Preise etc. sollen per git push auf den Server gespielt werden können - wie bei einer statischen Webseite.
Wird ein Pull Request nach main gemerged, so soll der Webshop neu bauen (CD-Pipeline) und die Änderungen auf dem Server veröffentlichen.
Für Inventarverwaltung, Warenkorb, Kundeninteraktion und automatisierte Funktionen sind dynamische Elemente erforderlich. Hier gilt zu entscheiden, was direkt in Javascript und welche Elemente besser per Automatisierungspipeline gelöst werden sollen.

Datenbanklösung (dynamische Website)

Produkte werden in der Datenbank gehalten.
Die Verwaltung des Webshops geschieht per Web-Oberfläche.
Die Datenbankverwaltung soll teilautomatisiert erfolgen, dabei sind Backups und Verschlüsselung für Kundendaten vorzusehen.
Die Datenbank ist transparent für den Admin: Alle Einträge hier erfolgen über eine Web-Schnittstelle.

Im nächsten Artikel

Vergleich verschiedener Ecommerce-Lösungen für meinen Webshop

PeerTube im Fediverse

Schallbert — Tue, 01 Apr 2025

Kurze Begriffsklärung

Fediverse?

Das Fediverse nennt etwas Fediverse, wenn mehrere durchaus unterschiedliche Anbieter dasselbe Protokoll nutzen, um Nutzer dieser Anbieter frei miteinander interagieren zu lassen - und das in Bezug auf digitale Medien. Somit entsteht stark vernetzte aber dabei stets dezentrale Dienste, bei dem freie Anbieterwahl zum Konzept gehört. The Verge geht hier einmal ins Detail und gibt einen Ausblick.

PeerTube?

PeerTube ist eine dezentrale Videoplattform, bei der sich mehrere Server die Last teilen und auch Zuschauer beim Verbreiten von Videos helfen können. Grob gesagt steht PeerTube zu YouTube wie Mastodon zum Kurznachrichtendienst X.

Der Anlass

Dieser Artikel beginnt mit einer E-Mail.

“You’re receiving this non-automated email because you’re one of the handful of people who has a video hosted on this PeerTube instance. I have decided to shut down this service […]” - Tom, scitech.video administrator

Es tue ihm wirklich leid, aber der Weiterbetrieb der Instanz koste zu viel Zeit, Wartungsaufwand und Geld. Zudem sei die Plattform im Moment nur wenig genutzt, sodass der Aufwand unverhältnismäßig erscheine.

So weit, so verständlich.

Toms Geschichte: scitech.video

Da ich dort allerdings alle meine Videos hochgeladen und verlinkt hatte, war ich sehr an den Hintergründen interessiert. Also hakte ich nach. Meine Nachfrage wurde ausführlich und prompt beantwortet.

Die Anfänge

Tom setzte seine PeerTube-Instanz im Jahr 2019 auf. Ursprünglich, um eigene Inhalte zu teilen. Bereits wenig später öffnete er das Hosting-Angebot, wenn auch mit leichtem Unwohlsein, für andere.

Aus der Admin-Perspektive wirke so eine Videoplattform wie der “wilde Westen”. Seinem Angebot ein gesundes Wachstum angedeihen zu lassen, stellte sich als recht schwierig heraus - vor allem, weil viele Bots und Werbetreibende unterwegs sind.

“Growing the service turned out to be challenging. Every time I opened registrations spambots started creating accounts easily and uploading videos with advertisements in the video descriptions […]” - Tom, scitech.video administrator, via E-Mail

Viele Bots und unerwünschte User unterwegs

Diese unerwünschten Spammer, Scammer, Advertiser konnte er zwar stets davon abhalten, scitech.video zu verseuchen. Dennoch bedeutete dies ständige Arbeit und manuelle Überwachung der automatischen Tools zum Ablehnen und Moderieren.

An dieser Stelle möchte ich Tom beipflichten. Ich habe im Schnitt etwa 340 fehlgeschlagene und dann von mir weggeblockte Verbindungen externer IP-Adressen auf meinen Server pro Tag. Allein auf dem ssh-Port. Und mein Server ist weder besonders groß, bekannt oder kann als lohnenswertes Ziel durchgehen. Ganz zu schweigen von zahllosen Versuchen, auf meine Gitea-Nutzeroberfläche zu kommen, die Website nach verborgenen Links zu crawlen und vieles mehr.

Für Betreiber eines Portals, welches auch externen Usern Schreibzugriff gibt (Videos, Beschreibungen, Tags, Kommentare), potenziert sich das Problem natürlich nochmal. Hier gehört anders als bei meiner Seite ja zum Konzept, sich zu beteiligen.

Copyright?

Genau, grundsätzlich fällt aus Sicht des Plattformbetreibers erst einmal jedes Video unter das Urheberrecht oder verwandte Schutzrechte. Aber ist der Nutzer, der gerade dieses Video veröffentlichen will auch der Urheber? Oder hat dieser Jemand Nutzungsrechte erworben?

Je nach Land und zugehöriger Rechtslage müssen sich Admins mit diesem Thema sehr genau auseinandersetzen. Es können hohe Strafen sowohl für die Betreiber als auch für die User fällig werden, sollte eine Urheberrechtsverletzung vorliegen.

Ersteres ist zumindest in Deutschland einem Urteil des Bundesgerichtshofes vom 23.10.2024, wie folgt aufzulösen: “[… sind] nach einem klaren Hinweis auf eine Rechtsverletzung die dort eingestellten Angebote im Rahmen des technisch und wirtschaftlich Zumutbaren auf gleichartige Verletzungen zu überprüfen und rechtsverletzende Inhalte zu sperren oder zu löschen”.

Durch die starke Fokussierung der Instanzen auf bestimmte Themenbereiche fallen Verletzungen jedoch meist schnell auf - denn auch User können Beiträge “reporten”.

Die Rechtslage für soziale Netzwerke

Einige Länder bereiten im Moment Gesetze vor, die Kinder und Jugendliche vor der Nutzung sozialer Netzwerke und damit verbundenen Gefahren schützen soll. Als Referenz hier ein Link zur Bundeszentrale für Jugend- und Medienschutz. Auch hier sind die Admins gefragt, diese Regeln umzusetzen - doch wie?

Dies jedenfalls fragt sich Tom angesichts der zunehmend vielfältiger werdenden Rechtsauffassungen unterschiedlicher Länder.

Updates und Wartung

“PeerTube upgrades were a bit of a drag because everything was tightly coupled with their specific nginx configuration, with breaking changes that had to be adjusted every couple of minor versions.” - Tom, scitech.video administrator, via E-Mail

Die Arbeiten seien nicht besonders schwierig auszuführen, dennoch kosten sie eine Menge Zeit. Wie bei anderer Software auch könne es passieren, dass ein PeerTube-Server zum Beispiel nach Betriebssystemupdates sich nicht mehr hochfahren lässt oder es zu Inkompatibilitäten verschiedener Softwarestände oder Modulen untereinander kommt.

Aus Leistungsgründen stellt sich das Testen als schwierig heraus, sodass oft direkt in “Prod” gearbeitet wird. Im Fehlerfalle leidet der Livebetrieb.

Die Konfiguration sei relativ aufwendig und müsse auf die Hardware angepasst werden. Größere PeerTube-Updates erfordern auch hier Änderungen.

Fazit

“I’m also disillusioned about the fediverse generally as a communication medium. A constant battle against spam/LLMs, so much anger, so much focus on follows, likes and boosts.” - Tom, scitech.video administrator, via E-Mail

Tom ist frustriert, dass auch hier die Aufmerksamkeitsökonomie durchschlägt. Obwohl werbefrei gedacht und als kleine Graswurzelbewegung ausgerollt, werden aus Idealismus heraus erstellte Instanzen schnell für Werbung und Selbstdarstellung missbraucht. Die Kosten beliefen sich zudem auf mehrere hundert Dollar im Jahr, was die Kosten-Nutzen-Bilanz weiter verschlechtere.

Eine Lösung könne hier “die Rückkehr zu Web1.0 oder geschlossene Gemeinschaften” darstellen, wie es sie zum Beispiel bei Meatspace, Matrix, Discord etc. bereits gebe.

Auch alle anderen Faktoren machen Tom den Weiterbetrieb seiner Instanz schwer: Die Nutzerbasis ist nie besonders groß geworden und es gibt nur wenige Menschen, die ihre Inhalte hier noch hochladen. Als Vater hat er nun viel weniger Zeit zur Verfügung und muss Projekte priorisieren. Somit beendet er nun seine immerhin sechs Jahre betriebene Reise als Anbieter im Fediverse.

Ich wünsche Tom für die Zukunft weiterhin viel Kraft, Idealismus und Enthusiasmus.

Jans Geschichte: makertube.net

Da ich nun nach einer neuen Hosting-Plattform für meine Videos Ausschau halten musste, bemühte ich die Suche für “video-maker” auf der PeerTube-Website. Da meine Inhalte einen klaren Tech-Fokus haben und von Forschung, Produktentwicklung bis in den Vorserienbau reichen, war es nicht schwer, schnell passende Kandidaten ausfindig zu machen.

So kam ich dann zu meinem Kanal auf MakerTube.

Nach erfolgreicher Anmeldung schrieb ich eine Mail an die Admins mit ähnlichen Fragen, die ich Tom bereits gestellt hatte.

Motivation - warum MakerTube?

“Ich habe einen kleinen Youtube-Kanal und die permanente Werbung und der Fokus auf die großen Kanäle, Klickbait etc. und wie die Leute gezwungen werden sich der Content-Maschine anzupassen ging mir auf die Nerven. […]” - Jan, MakerTube administrator, via E-Mail

Jan war bereits im Fediverse unterwegs und beschäftigt sich auch beruflich mit Webdiensten, die stark skalieren müssen. Daher erschien es für ihn logisch, selbst eine Instanz aufzusetzen - dann aber natürlich mit den wirklich interessanten Themen dieser Welt. Es sei ja nicht als Konkurrenz zu YouTube gedacht und fokussiere sich daher auf Maker, Musikerinnen, Künstler etc.

Ist der Einstieg leicht?

Es bedeute schon einiges an Aufwand, so eine Instanz hochzuziehen und performant zu halten. Framasoft, welche die PeerTube-Software entwickeln, machten einen Superjob und unterstützen die Hoster-Community wo sie können.

Ich persönlich kann bestätigen, dass sich PeerTube in den neueren Versionen ganz anders anfühlt als noch vor ein paar Jahren und sich mit praktischen Features wie automatisch generierten Untertiteln immer näher an den Funktionsumfang von YouTube heranrobbt.

Das Fediverse, so Jan, sei nach wie vor eine Nische. Daher falle das Wachstum seiner Instanz eher moderat und sehr organisch aus. PeerTube sei im Moment noch etwas für enthusiastische Videomacher; am normalen Publikum laufen die Inhalte größtenteils ungesehen vorbei.

Wie groß ist der Zeitaufwand?

Jan legte den Fokus auf niedrige laufende Kosten bei gleichzeitiger Skalierbarkeit, falls die Sache plötzlich doch groß werden sollte. Jetzt, da das System reibungsfrei läuft, liege der Aufwand bei ein paar Stunden pro Woche für Moderation von Usern, Inhalten und Support.

Ausnahmen: Größere Updates, Upgrades und technische Probleme.

Was sagen die Leute?

“Es gibt positive Rückmeldungen und die Leute sind dankbar, dass ich die Seite betreibe und ich mir die Arbeit mache, aber ich würde sagen nicht sehr viele.” - Jan, MakerTube administrator, via E-Mail

Aber natürlich gebe es auch immer mal wieder Entrüstung darüber, dass das halt nicht YouTube wäre und nicht jeder sofort einen Account aufmachen könne.

Wie erkennt ihr Urheberrechtsverletzungen?

“Bezüglich Copyright gibt es da keine direkten Hilfsmittel. Es gibt die Report-Funktion an den Videos, um auf Verstöße gegen Copyright oder Instanzregeln hinzuweisen. Das wird auch von Benutzern genutzt.” - Jan, MakerTube administrator, via E-Mail

Verantwortung und Haftung lägen bei so kleinen Anbietern wie MakerTube in erster Linie beim User. Wenn allerdings auf Verstöße hingewiesen wird, müssen die Admins tätig werden und Inhalte löschen. Auf MakerTube sei dies allerdings im Alltag kein Problem: Die Registrierungen neuer User wird genau geprüft und im Zweifel werde nachgefragt, um welche Inhalte es gehe. Bei den meisten Verletzungen gehe es um Hintergrundmusik der Videos, da gebe es scheinbar weniger Bewusstsein für Urheberrecht wie bei Uploads von Videokopien.

Und wie finanziert sich das Ganze?

MakerTube finanziert sich über Spenden. Gerade zu Anfang ging laut Jan viel Zeit dafür drauf, dies den Leuten klar zu machen und genügend Budget für einen flüssigen Betrieb zu erhalten. Eine Videoplattform sei ressourcenintensiv: Viel CPU-Power für Transkodierung und Streaming, einen Haufen Plattenplatz für die ganzen Assets bei gleichzeitig hohen Anforderungen an die Bandbreite, gerade in “Stoßzeiten”.

Fazit

Ich bin mit MakerTube bis jetzt zufrieden: Transkodierungen gehen flott, Videos laufen flüssig. Sogar der Heise-Verlag hat nun ein erstes Video auf die Instanz hochgeladen. Es ist allerdings deutlich schwieriger, ohne “Fanbase” auf die Landing Page zu kommen, was bei scitech.video für mich nie ein Problem darstellte 😅.

Lasst mich mit einem weiteren Zitat von der Site selbst schließen:

“MakerTube is here to stay.” - MakerTube, March 2025, about MakerTube.

Danke, Jan. Auf die Zukunft!

MakerTube

Schallbert — Mon, 17 Mar 2025

Ich bekam eine Mail mit dem Hinweis, dass die von mir genutzte PeerTube-Instanz scitech.video Mitte April 2025 ihren Betrieb einstellen würde. Als Begründung nannte der Host unter anderem den hohen Zeit- und Kostenaufwand für den Betrieb sowie die geringe Anzahl Nutzer. Dazu gibt es inzwischen sogar einen eigenen Artikel, der sich mit den Vor- und Nachteilen als Betreiber im Fediverse beschäftigt.

Als Nachfolgeportal für meine Videos habe ich MakerTube ausgewählt. Dorthin migriere ich nun sämtliches Material. Stück für Stück in den kommenden Wochen.

MakerTube wird in Deutschland über Hetzner gehostet und hat viel, viel mehr Rechenpower als scitech. Daher laufen die Videos deutlich reibungsloser als vorher.

Abschließend werde ich alle Videolinks auf dieser Site umbiegen müssen, damit sie auch weiterhin funktionieren.

Für Nutzende von schallbert.de ändert sich nichts 😀

Schallbert

Gitea: Suchmaschinenindexierung stoppen

Schallbert — Wed, 12 Mar 2025

Nach ewigen Zeiten habe ich nur zum Spaß mal wieder einen Ausflug auf die Google Search Console gemacht. Normalerweise interessiert die mich überhaupt nicht, weil ich selbst Google gar nicht nutze und davon ausging, dass die Suchmaschinen ihre Arbeit aus Eigeninteresse schon gut machen würden.

Ich war etwas irritiert, als ich feststellte, dass es das Gros meiner Seiten nicht mal durch den Indexer geschafft hat.

Das Problem

Wie sollen denn Leute meine Webpräsenz finden? Selbst wenn sie die korrekten Suchbegriffe wüssten, würden sie über Google kaum etwas angezeigt bekommen. Immerhin stand klar drin, dass keiner meiner Blogartikel im Indexer vorkam. Auf meiner Gitea-Instanz hingegen waren mehrere tausend Seiten dem Indexer bekannt. Ein klares Missverhältnis. Wieso überhaupt erzeugt Gitea ein so hohes Dateiaufkommen?

Googles crawler (ein Programm, welches das Netz nach Inhalten durchsucht und für die Suche indexierbar macht) findet anscheinend jeden noch so kleinen Commit in öffentlichen Repositories sowie die dahinter liegenden Dateien. Auch Automationsläufe und andere Metadaten werden indexiert.

Das ist natürlich vollkommen unnötig und verbraucht mir an einer Stelle Energie, die ich viel lieber in der Präsentation meines Blogs hätte. Also muss eine Lösung her.

Lösungsansätze

Mir fielen direkt ein paar Möglichkeiten ein:

Den Crawler für jedes Repository so konfigurieren, dass nur die oberste Ordnerebene durchsucht wird.
Suchindexierung für git.schallbert.de komplett abschalten.
Per Search Console so lange Korrekturen fahren, bis der Indexer auf meinen Blogbeiträgen korrekte Zuordnungen anzeigt.

Die naheliegendste Lösung für mich war, den Indexer für meine Gitea-Instanz komplett abzuschalten. Korrekturschleifen greifen bei Googles Crawler erst Tage oder Wochen später und waren mir zu langwierig. Eine eigene robots.txt für jedes Repository hielt ich für zu aufwendig.

Meine Umsetzung

Hierfür nahm ich die Gitea-Dokumentation zur Hand. Der Vorschlag mit einer robots.txt leuchtete mir sofort ein, ebenso ihr Inhalt:

User-agent: *
Disallow: /

Hiermit wird Crawlern von jedem Anbieter * gesagt, dass ab dem Stammverzeichnis / überhaupt nicht indexiert werden soll.

Leider nur war mir überhaupt nicht klar, wie Gitea diese Datei in seiner Instanz bereitstellt:

To make Gitea serve a custom robots.txt (default: empty 404) for top level installations, create a file with path public/robots.txt in the custom folder or CustomPath.

Giteas Konfigurationsverzeichnis

Also probierte ich ein Wenig herum. Erstellte mal einen public-Ordner mit entsprechender Datei, dann einen custom-Ordner auf verschiedenen Ebenen innerhalb der Gitea-Ordnerstruktur. Jedes mal startete ich den Container neu und schaute nach, ob die robots-Datei auch auf dem Server erschien.

Nichts.

Doch dann löste ich mich von den Ordnernamen und packte die Datei schlicht in das Konfigurationsverzeichnis von Gitea - die niedrigste Ebene, auf der gitea als Ordnername schon gar nicht mehr vorkommt. Und dies war die Lösung.

Test

Nach Neustart konnte ich die Datei im Browser erfolgreich anzeigen.

Inzwischen beginnt auch Google, die unerwünschten Seiten aus dem Indexer zu entfernen. Meine Blogartikel werden über die nächsten Wochen hoffentlich auch in der Google-Suche verfügbar.

Repo-Lookout: Sicherheitslücke beheben

Schallbert — Fri, 20 Dec 2024

Repo-Informationen öffentlich zugänglich

Eines schönen Tages bekam ich eine E-Mail von Repo Lookout. Darin stand, dass eines meiner Repositories für Zugriffe aus dem Internet freigegeben sei. Dies stelle ein potentielles Sicherheitsrisiko dar, da möglicherweise geheime Quelldateien, versteckte Funktionen oder sogar Passwörter enthalten sein könnten.

Zuerst hielt ich diese “Ihr-Repo-ist-nicht-sicher”-Warnung für einen Phishing-Versuch. Doch durch einfaches Eingeben der darin enthaltenen Links wurde klar, dass Repo Lookout Recht hatte und mein Lectures-Repo nicht nur wie von mir gewünscht öffentlich war, sondern dass auch die Metadaten zur Versionskontrolle offen auf dem Webserver lagen.

Ist das schlimm?

Normalerweise sollen innere Struktur und Konfiguration (Actions, Diskussionen, Wiki etc.) hinter einem Repository nicht öffentlich bleiben. Erst recht nicht, wenn das Repository als private angelegt ist. Doch auch bei öffentlichen Repos sollte niemand auf die Struktur dahinter zugreifen können.

Daher die Mission von Repo-Lookout:

“Find source code repositories that have been inadvertently exposed to the public and report them to the domain’s technical contact.” - Repo Lookout /about (Crissy Field GmbH)

In diesem Falle unkritisch, aber unerwartet und unschön.

Schadet mir nicht, weil mein Webserver die Dateien lediglich zum Abruf dort liegen hat und sie selbst bei Manipulation keine Rückwirkung auf mein Repository gehabt hätten. Außerdem hatte ich alle Secrets wie in diesem Artikel beschrieben in eigens angelegte Dateien ausgelagert, sodass sie nicht mehr in den Konfigurationsdateien auftauchen. Das Repository liegt zudem getrennt auf der Gitea-Server-Instanz. Dennoch sollte nur am Internet hängen, was ich bewusst freigeben möchte.

Der Bildausschnitt von Gitea zeigt denselben Commit wie die Warnung von Repo Lookout.

Wie es dazu kam

In der Deploy-Pipeline für meine Subdomain lectures.schallbert.de und Landing Page schallbert.de habe ich einen direkt-Checkout von der Gitea-Instanz zum Webserver Caddy. Dieser läuft automatisch an, sobald die main-Branches ein Update erhalten. Der Runner startet eine Checkout-Action, welche das Repository ins entsprechende Verzeichnis des Webservers kopiert.

Checkout-Action kopiert auch den `.git`-Ordner

Dabei wird der .git-Ordner einfach mit aufgesetzt. Dort drin liegen alle von der Versionskontrollsoftware benötigten Daten zur Zustandsverwaltung des Repos. Den Kopiervorgang selbst kann ich auf Gitea nicht sehen, denn dort taucht der versteckte .git-Ordner gar nicht erst im Verzeichnis auf. Verständlich, denn auf Basis dieses Ordners findet die gesamte Darstellung auf Gitea statt.

So blieb das unerwünschte Verhalten unter meinem Radar - und laut Repo Lookout bin ich bei Weitem nicht der Einzige, dem es so geht.

Option 1: Fix auf dem Webserver

Die naheliegendste Lösung ist, den Zugriff auf die Datei serverseitig zu blockieren. Dies kostet nur wenige Ressourcen und ist leicht einzurichten.

Dieser Foreneintrag zeigt, wie das geht: hide-entire-folder-caddyfile. Für meine zu schützenden Dateien füge ich also folgende Einträge der Caddyfile hinzu:

# /caddy2/Caddyfile

# [...]
respond /.git/* "Access denied" 403
respond /.gitea/* "Access denied" 403

Damit sage ich Caddy, dass es bei Aufruf einer beliebigen Datei /* im Ordner /.git mit dem Fehlercode 403 “Forbidden” antworten soll. Dabei ist die Wildcard (*) unbedingt erforderlich, denn sonst wird lediglich der Ordner selbst und nicht die enthaltenen Dateien gesperrt.

Zur Kontrolle prüfe ich was passiert, wenn ich die Git Logs anfrage:

# Terminal
curl <lectures.schallbert.de>/.git/logs/HEAD
Access denied

Funktioniert prima!

Option 2: Fix in der Checkout-Action

Es gibt allerdings eine noch viel elegantere Lösung: bereits vorher in der Pipeline dafür sorgen, dass der Ordner gar nicht erst auf dem Server auftaucht.

Variante 1: Mit Hilfe von `sparse-checkout`

sparse-checkout ermöglicht die Auswahl von Ordnern und Dateien, die zum Checkout gehören sollen. Alle anderen Dateien im Repository bleiben unberührt und tauchen im Branch nicht auf. Dies spart vor allem bei großen Repositories Zeit und Speicherplatz. Macht aber natürlich nur Sinn wenn bereits vorher bekannt ist, dass nicht alle Dateien angefasst werden müssen.

Negativliste für `sparse-checkout`

In meinem Falle will ich die oben erwähnten Ordner gerade nicht per Checkout auf den Server kopieren, den ganzen Rest aber schon. Wie ich das hinbekomme? Mit Hilfe der Negation im no-cone mode.

“The user has explicitly said ‘I want these directories and not those directories.’” - Derrick Stolee, Microsoft, auf Github

In der Anleitung zu Checkout-Action steht, dass sparse-checkout auch für die vom Runner automatisierte Aktion unterstützt wird.

Nun programmiere ich mit Hilfe des Github Actions Cheet Sheet:

# /.gitea/workflows/deploy-lectures.yml

# [...]
steps:
 - name: --- CHECKOUT ---
 uses: actions/checkout@v4
 with:
 path: ./tmp
 sparse-checkout: |
 /*
 !.git
 !.gitea
 sparse-checkout-cone-mode: false
 # [...]

Zur Erläuterung: Das Skript zum Veröffentlichen auf meinem Webserver verwendet die Aktion checkout, Unterfunktion sparse-checkout und bezieht sämtliche Dateien im Ordner im Stammverzeichnis tmp und darunter ein bis auf .git und .gitea.

Was ist der `No-Cone Mode`?

Standardmäßig erwartet sparse-checkout eine Liste von Ordnern, die für den Checkout erfasst werden sollen. Im no-cone Modus wird stattdessen eine Liste von Patterns erwartet. Hier sind sämtliche Operatoren möglich, die auch in der .gitignore zum Spezifizieren von Dateien, Ordnern, Auslassungen etc. verwendet werden können. Dies ermöglicht mir den Ausschluss bestimmter Ordner, hat aber einige gewichige Nachteile. Durch viel höhere Komplexität der Pattern-Befehle, die damit einhergehende Fehleranfälligkeit sowie die deutlich rechenintensivere Auswertung bei größeren Repositories wird die Verwendung des no-cone Mode nicht empfohlen und ist in der Dokumentation als “deprecated” (überholt) angegeben. Dennoch, probieren geht über Studieren!

Test mit `sparse-checkout`

Nun lade ich die Action auf meine Gitea-Instanz hoch und lass meinen runner einmal drüber laufen. Anschließend logge ich mich auf dem Webserver ein und schaue, ob der .git-Ordner erstellt wurde oder nicht:

lectures# ls -la
[...]
drwxr-xr-x 8 root root 4096 Dec 20 10:41 .git
[...]

Mist, der Ordner ist ja immer noch da. Ich schaue in den Logs der Action auf meiner Gitea-Instanz nach:

[...]
hint: 	git branch -m <name>
Initialized empty Git repository in /workspace/schallbert/lectures/tmp/.git/
[...]
::group::Setting up sparse checkout
[command]/usr/bin/git config core.sparseCheckout true

An sparse-checkout liegt es also nicht. Dafür aber an der Art und Weise, wie checkout funktioniert: Offensichtlich wird für ein ordentliches Aufsetzen des Repository auf meinem Webserver der .git-Ordner zwingend benötigt. Also bleibt mir nur übrig, ihn nach dem Auschecken automatisch zu löschen.

Variante 2: `rm -rf`

Und so probiere ich es mit Gewalt:

# /.gitea/workflows/deploy-lectures.yml

# [...]
steps:
 - name: --- CHECKOUT ---
 uses: actions/checkout@v4
 with:
 path: ./tmp
 - name: --- REMOVE TEMPORARY FILES ---
 run: |
 rm -rfv ./tmp/.git ./tmp/.gitea
# [...]

Nun endlich taucht der .git-Ordner auf meinem Webserver nicht mehr auf und mein “Repo-Leak” ist geflickt. Nochmal danke an Repo Lookout!

Fazit

Ich hatte hier das Problem, dass der versteckte .git-Ordner, wo Konfiguration und Struktur von Repositories gespeichert werden, unbeabsichtigt und ohne mein Wissen auf meinem Webserver veröffentlicht waren.

Ich habe hier zwei funktionierende Optionen zur Lösung des Problems vorgestellt:

Ein Zugriffsverbot auf dem Webserver einrichten
Die Pipeline so umbauen, dass sie den .git-Ordner nach erfolgtem Ausrollen selbstständig löscht.

Die zweite Option ist zwar etwas aufwendiger einzubauen, doch packt sie das Problem bei der Wurzel, anstatt lediglich die Symptome zu beheben. Außerdem entspricht sie dem ersten Grundsatz aus dem Datenschutz: Datenminimierung geht vor Schutzmaßnahmen.

“Was nicht existiert, kann nicht verloren gehen” - Schallbert

Logrotate-Rekursion

Schallbert — Mon, 18 Nov 2024

Was funktioniert nicht?

Eigentlich wollte ich logrotate nutzen, um meine Logs täglich zu bereinigen und so Datensparsamkeit umzusetzen: So können IP-Adressen, die ich für’s Banning brauche, einheitlich und automatisiert nach kurzer Zeit gelöscht werden. Die Server-Logs interessieren mich ansonsten überhaupt nicht und stehlen mir nur Speicherplatz.

Mit meiner aktuellen Konfiguration erstellt logrotate zwar eine Logdatei am Tag, nennt sie aber xyz.log.1, xyz.log.1.1, xyz.log.1.1.1 anstatt der erwarteten xyz.log.1, xyz.log.2, xyz.log.3. Somit funktioniert die Löschroutine nicht mehr und die Anzahl der Logs wächst stetig.

Und warum?

Ich vermute, dass meine logrotate-Konfiguration fehlerhaft ist. Im Moment sieht sie wie folgt aus:

## LOGROTATE file named 'blog'
blog/* {
# it's ok if the file doesn't already exist
missingok
# Sets the logs to rotate in intervals
daily
# Tells the system to remove old logs and only keep the most recent rotated logs
rotate 7
# Rotated logs will be compressed and kept on disk if they are 10 MB or less.
size 10M
# compress and delaycompress: These two options are used together and indicate that 
# rotated logs should be compressed (gzip) except for the most recent one.
compress

delaycompress
}

Wie üblich nehme ich als Erstes die Bedienungsanleitung zur Hilfe, die ich mittels man logrotate in der Konsole aufrufe. Dort steht, dass die zu rotierende Datei direkt angegeben (und nicht nur per “Wildcard” gewählt *) werden kann. Außerdem kann ein Logverhalten auch auf mehrere Dateipfade angewendet werden, indem sie durch Leerzeichen getrennt vor die geschweifte Klammer gesetzt werden.

Das Sternchen scheint genau mein Problem mit den kaskadierenden Logs zu erzeugen: Dadurch wird nicht nur die eigentliche Zieldatei access.log rotiert sondern auch alle bereits rotierten Dateien nochmal angefasst.

Die Lösung

Entsprechend der Bedienungsanleitung schreibe ich die Bearbeitungsvorschrift für Logrotate so um, dass ich statt fünf eigenen Vorschriften für die jeweiligen Logs nur zwei Dateien erzeuge. Diese sind zudem einfacher und kürzer als die obige Ausgangsversion.

Beispiel:

# rotate webserver log files.
gitea/access.log
blog/access.log
landing/access.log
lectures/access.log
{
 # Sets the logs to rotate in intervals
 daily
 # Tells the system to remove old logs and only keep the most recent rotated logs
 rotate 7
 # compress and delaycompress: These two options are used together and indicate that 
 # rotated logs should be compressed (gzip) except for the most recent one.
 compress
 delaycompress
}

Konfigurations-Update

Dies kann ich durch meine vorhandene Server-Konfigurations-Pipeline durch einfachen Push ins Repository auf dem Server ausrollen. Nun muss ich die Dateien dort nur noch händisch nach /etc/logrotate.d kopieren.

Logrotate testen

Jetzt wäre es noch schön, wenn ich ausprobieren könnte, ob die von mir vorgenommenen Änderungen auch tatsächlich funktionieren. Dafür nehme ich erneut die Bedienungsanleitung von logrotate zur Hilfe und tippe:

logrotate -d -v <LOGROTATE-DESCRIPTOR-FILE>

Mit aktivierten debug und verbose Flags wird logrotate die in der Konfigurationsdatei angegebene Rotationsvorschrift anwenden und Rückmeldung geben, tatsächlich auf dem Dateisystem aber keine Änderungen oder Rotationen durchführen. Bei mir sieht das Ergebnis des Tests dann etwa so aus:

lectures/access.log 
 after 1 days (7 rotations)
empty log files are rotated, old logs are removed
considering log gitea/access.log
 Now: 2024-11-28 17:19
 Last rotated at 2024-11-27 00:00
 log needs rotating
considering log blog/access.log
 Now: 2024-11-28 17:19
 Last rotated at 2024-11-16 00:00
 log needs rotating
considering log landing/access.log
 Now: 2024-11-28 17:19
 Last rotated at 2024-11-07 00:00
 log needs rotating
considering log lectures/access.log
 Now: 2024-11-28 17:19
 Last rotated at 2024-09-21 00:00
 log needs rotating
rotating log gitea/access.log, log->rotateCount is 7
[...]
renaming lectures/access.log.7.gz to lectures/access.log.8.gz (rotatecount 7, logstart 1, i 7), 
renaming lectures/access.log.6.gz to lectures/access.log.7.gz (rotatecount 7, logstart 1, i 6), 
renaming lectures/access.log.5.gz to lectures/access.log.6.gz (rotatecount 7, logstart 1, i 5), 
renaming lectures/access.log.4.gz to lectures/access.log.5.gz (rotatecount 7, logstart 1, i 4), 
renaming lectures/access.log.3.gz to lectures/access.log.4.gz (rotatecount 7, logstart 1, i 3), 
renaming lectures/access.log.2.gz to lectures/access.log.3.gz (rotatecount 7, logstart 1, i 2), 
renaming lectures/access.log.1.gz to lectures/access.log.2.gz (rotatecount 7, logstart 1, i 1), 
renaming lectures/access.log.0.gz to lectures/access.log.1.gz (rotatecount 7, logstart 1, i 0)
[...]

Die Ausgabe zeigt mir, dass sowohl alle gewünschten Logdateien von logrotate berücksichtigt werden und auch, dass die Rotation korrekt und täglich durchgeführt wird.

Wieder etwas gelernt 😃

Neue Startseite

Schallbert — Tue, 01 Oct 2024

Oktober-2024 — Neues Website-Design —

schallbert.de hat jetzt endlich die “Baustellenphase” überwunden. Ab jetzt steht nicht nur dieser Blog zur Verfügung, sondern auch die zusätzlichen Kategorien Shop und Vorträge.

Shop

Dieser Bereich befindet sich noch in einer frühen Planungsphase. Ich überlege hier, meinen Seifenbutler, Rohlinge für CNC-Gravuren und ein paar meiner Software-Projekte wie zum Beispiel QR-Codengrave als App zum Kauf anzubieten.

Ich habe mich bis jetzt weder auf ein Webshop-Framework festgelegt, noch bin ich momentan in der Lage, viel Zeit in den Aufbau der Seite oder die Fertigung von Produkten zu stecken. Von daher stellt der Shop ein Langfristiges Ziel dar. Als Bezugsquelle für Seifenbutler steht weiterhin Mopemasters Onlineshop zur Verfügung.

Vorträge

Diese Subdomain habe ich erstellt, um meine Vorträge zu sammeln. Sie nutzen ein anderes Framework als mein Blog und sind daher besser separat untergebracht.

Schallbert

NVME-Festplatte kaputt?

Schallbert — Tue, 10 Sep 2024

Das Ereignis

Mitte April 2024:

Nach einem Systemupdate fährt mein Laptop plötzlich nicht mehr hoch. Der Bootloader grub-core meldet, er habe Probleme beim Schreiben von Sektoren.

error: ../grub-core/efi/efidisk.c:638: failure writing sector 0xXXXXXXXX

Beim Reboot bleibt mir der Bildschirm nach Anzeige des Firmenlogos mit blinkendem Cursor schwarz. Wenn ich hinter die Maske schaue, dann schlägt das Laden diverser Services fehl:

Your browser does not support the video tag.

Boot errors due to read-only nvme

Erste Analyse

Ich vermutete ein Problem beim Update des Rechners und führte aus dem UEFI von Lenovo heraus einen Festplattentest durch. Ergebnis:

The media check is complete, the result is: FAIL

Eher kein Problem mit dem Betriebssystem sondern eines mit der Platte. Mist. Muss ich um meine Daten bangen? Ich habe zwar Backups herumliegen, das letzte ist aber drei Wochen alt und somit sind einige Stunden Arbeit auf der Kippe. Zudem kostet mich ein Wiederaufsetzen einiges an Zeit. Daher probiere ich erst einmal, ob sich noch etwas retten lässt.

Selbsttest

Ich lasse also die SMART Tests für die Platte mit smartctl -x /dev/nvm0 durchlaufen und weiß nun, dass sie etwa 7600 Betriebsstunden hinter sich und 240GB nutzbare Kapazität hat. Die unter dem Namen nvme0n1 eingesetzte Disk meint, sie sei nun “read-only”. Und zwar sämtliche Partitionen inklusive Kernel. Na klasse. Das Ergebnis meiner Online-Suche war in etwa:

Die Platte ist irreparabel beschädigt. Es muss eine Neue her.

Reparaturversuch

Man muss ja nicht alles glauben, was im Netz steht. Also nehme ich das Lenovo-eigene Reparaturwerkzeug für Festplatten zur Hand. Es lässt sich aus dem UEFI heraus aufrufen und firmiert unter dem Namen Bad Block Recovery Tool. Das Programm scannt die Platte auf defekte Sektoren und versucht, betroffene Blöcke wiederherzustellen. Der Durchlauf benötigt für die letzten 10% fast eine halbe Stunde.

Ergebnis: Wiederherstellung fehlgeschlagen. Ich führe das Werkzeug erneut aus. Und noch ein drittes Mal im langsamen pedantic-Modus. Immer wieder ohne Erfolg. Ständig bekomme ich critical medium error angezeigt.

Ob dies alles nicht klappt, weil sich die Platte in den Read-only mode gesetzt hat?

Da ich nicht mehr booten kann und keine Konsole zur Verfügung habe, sind meine Möglichkeiten mit Bordmitteln nun erschöpft.

Einwurf: Der Read-only mode bei SSDs

Laut Internet (DiskTuna) ist der read only mode zur Schadensbegrenzung vorhanden. Stellt der Controller des Speichergerätes einen schwerwiegenden Fehler fest, versetzt er die Platte in Nur-Lesezugriff. Somit wird das Risiko minimiert, dass weitere Blöcke korrumpiert oder mit in den Tod gerissen werden.

Im Forum Superuser beschreibt jemand einen identischen Fehler zu meinem, und tatsächlich ist da wohl nichts mehr zu machen.

Datenrettung per Boot-Stick

Weiter geht’s mit einem USB-Stick, den ich von einem anderen Rechner aus zum Linux-Boot-Stick mache. Ich stopfe ihn an meinen Laptop und kann ihn endlich wieder hochfahren. Als Medium zur Datenrettung schließe ich eine externe Festplatte an.

Übersicht verschaffen mit fdisk

Zuerst schaue ich, ob alle Platten und Partitionen auftauchen. Dafür tippe ich das Kommando sudo fdisk -l in die Konsole.

Glück gehabt, alles ist noch da! Vielleicht kann ich die Dateien ja einfach von der defekten Festplatte herunter kopieren?

Kopieren mit cp

Probieren wir’s aus.

sudo cp -r -v /mnt/nvme0n1p3/Documents/my/important/files /mnt/externalHdd/save

Ein paar Sekunden denke ich, dass alles glatt geht. Doch dann bricht cp mit Fehlermeldung ab, das Volume sei nicht verfügbar. Tatsächlich ist die Platte nicht mehr gemountet. Ich kann sie allerdings direkt wieder finden und mounten. Ein paar Versuche später habe ich meine wirklich wichtigen Daten gesichert, der Kopiervorgang bricht aber stets nach ein paar Sekunden ab. Für die ganze Platte würde mir dieses Vorgehen viel zu lange dauern.

Genau dieses Verhalten - mounten, ein paar Sekunden kopieren, Platte verschwindet - habe ich online in ein paar Foreneinträgen bestätigt bekommen.

Also muss eine andere Lösung her.

Daten retten mit ddrescue

Nach kurzer Online-Suche installiere ich das Programm ddrescue.

In der zugehörigen Dokumentation stehen einige Dinge sehr klar drin. Dass man z.B. verstanden haben sollte was es genau tut, bevor man es verwendet. Oder das Folgende:

“Never try to repair a file system on a drive with I/O errors; you will probably lose even more data. " - ddrescue Manual

Jetzt stellt sich für mich die Frage, ob ich oben mit dem Block-Reparaturversuch genau so einen Fehler begangen habe. Oder bin ich mit der Bad Block Recovery auf der sicheren Seite, da hier von Datenblöcken auf der Platte und nicht vom “darüber liegenden” Dateisystem die Rede ist? Hier steht auch, dass die sogenannte Mapfile eine Kernfunktion des Programmes ist. Nach Abbruch, Neustart, für die Zusammenführung von Backups und zum Verkürzen der Datenrettung bietet sie einen großen Zeitvorteil. Daher sei es keine schlechte Idee, sich die Mapfile schon bei Erstellung einer Offlinhe-Sicherheitskopie zu erzeugen und gut wegzulegen. Insgesamt fand ich das Tool extrem hilfreich, effektiv und leicht zu bedienen und kann es an dieser Stelle nur weiterempfehlen.

Zurück zur Sache: Ich finde einen ganz einfachen Befehl, die komplette Datenpartition meines beschädigten NVME-Speichers auf eine externe Festplatte zu kopieren:

ddrescue --sparse /dev/nvme0n1p3 /run/media/liveuser/myExternalHDD/datapartition

Die --sparse-Option überspringt mit Nullen belegte Bereiche der Quellplatte und kann so eine Menge Platz auf dem Zieldatenträger einsparen. Das Programm benötigt eine Viertelstunde für den kompletten Durchlauf. Es kann wie oben im Bild zu erkennen tatsächlich 99.6% der Daten retten und auch mehrere Monate später habe ich die restlichen 0.4% noch nicht vermisst. Glück gehabt.

Überprüfung: Output von ddrescue ansehen

Jedenfalls legt das Programm am Ende eine einzige Datei auf meiner externen Platte ab: datapartition.img Dieses Image kann ich mit fdisk -l anschauen:

datapartition.img: 236.89 GiB, 254356226048 bytes, 496789504 sectors
Units: sectors of 1 * 512 = 512 bytes
Sector size (logical/physical): 512 bytes / 512 bytes
I/O size (minimum/optimal): 512 bytes / 512 bytes

Alles da, das ist ja schon einmal gut. Ob denn nun auch alles drin ist?

Dafür mounte ich die Partition mal und schaue mich per cd und ls -l darin um:

sudo mkdir /mnt/olddisk # Mount point of the rescued data image
sudo mount /run/media/liveuser/myExternalHDD/datapartition.img /mnt/olddisk

Zum Glück war alles drin, was drin sein sollte. Nun konnte ich das Image unmounten, den Rechner herunterfahren und eine neue Festplatte einbauen lassen.

Die neue Festplatte

Auch hier habe ich noch einmal Glück gehabt: Auf meinem Gebrauchtlaptop war noch Garantie und so bekam ich ihn binnen einer Woche mit einer neuen (und doppelt so großen) Festplatte zurück gesendet. Da ich so große Angst vor Datenklau bekam, hatte ich meine alte Platte vor dem Versenden ausgebaut. Dabei kam ich mir ganz schön paranoid vor.

Diese Arbeit hätte ich mir aber vielleicht sparen können, denn ddrescue hat auch für paranoide Leute wie mich eine Software-Lösung parat: Die Option --fill-mode. Hiermit können nach erfolgter Rettung die “noch guten” Blöcke und Sektoren gelöscht werden. Nur die ohnehin defekten Sektoren bleiben erhalten. Aus der Online-Dokumentation:

ddrescue --fill-mode=+ --force /dev/zero bad_drive mapfile

Ob dies allerdings auch einer Platte wie meiner funktioniert hätte, die der On-Board-Controller auf “read-only” gesetzt hat, ist mir nicht klar. Egal.

Ich kann jetzt jedenfalls mit einem voll funktionsfähigen Laptop weiter Blog-Einträge verfassen ☺️.

Giteas act_runner: Startprobleme

Schallbert — Fri, 30 Aug 2024

Das Problem

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

Die Fehlermeldung ist immer dieselbe:

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

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

Die kurzfristige Lösung

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

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

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

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

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

Ursachenforschung

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

Lösung: Abhängigkeiten abbilden

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

depends_on

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

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

Healthcheck

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

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

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

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

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

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

Fehler-Logdateien versenden

Schallbert — Tue, 20 Aug 2024

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

Worum geht es hier?

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

Verifikation und Überwachung

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

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

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

Was zeichnet ein gutes Monitoring für mich aus?

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

Methoden automatischer Berichterstattung

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

Mail per Konsole - curl

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

curl https://blog.schallbert.de

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

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

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

Mail per Konsole - mail, mailx, mailutils, swaks

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

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

RSS Feed erzeugen

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

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

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

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

borgmatic

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

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

fail2ban

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

Gitea

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

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

Server

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

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

Die Auswahl des Berichtsprogramms

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

Berichtsprogramm

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

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

Kommunikationsweg

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

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

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

Logging

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

Wann sollen Logs gesendet werden?

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

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

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

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

Eine Benachrichtigung sieht dann etwa so aus:

TIMESTAMP APPLICATION PRIORITY MESSAGE EFFECT DETAIL

Rohfassung eines Berichts

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

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

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

Durchführung

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

borgmatic

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

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

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

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

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

Server

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

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

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

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

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

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

Server-Konfiguration

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

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

# server-config-action.sh

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

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

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

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

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

# action commands...

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

# server-config-action.sh

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

# action commands ...

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

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

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

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

Gitea

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

Ergebnis

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

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

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

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

Server-Konfiguration ausrollen

Schallbert — Wed, 31 Jul 2024

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

Worum geht es hier?

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

Wege und Möglichkeiten

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

Automatisierungsdienste Ansible, cdist, Kubernetes

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

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

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

Mein Weg

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

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

Risiko Zirkelbezug

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

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

Vorbereitung: Ordnersystem und Skripte erstellen

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

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

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

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

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

Durchführung: Shell-Script zum Abhandeln des Updates

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

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

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

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

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

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

Erster Test und Einhängen in den “Autostart”

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

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

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

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

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

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

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

Sicherungskopie

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

Zustand und Daten einfrieren

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

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

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

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

Borgmatic: Trigger-Handler Mechanismus #2 und #3

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

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

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

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

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

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

Das Backup anlegen

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

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

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

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

Diese Zeile füge ich dem Automationsskript hinzu.

Zweiter Test zum Anlegen des Backups

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

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

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

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

Fehlerbehebung für “failed to acquire the lock”

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

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

Übertragen der Konfiguration

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

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

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

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

Umstieg auf rsync

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

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

Doch plötzlich startet gitea nicht mehr. Fehlermeldung:

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

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

Alle Anwendungen neu starten

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

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

Die fertige Automation

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

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

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

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

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

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

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

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

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

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

Server-Konfiguration mit Git

Schallbert — Mon, 15 Jul 2024

Worum geht es?

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

Hintergrund

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

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

Vorüberlegungen

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

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

1. Hardlink

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

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

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

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

2. Repo und auto-deploy auf den Server

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

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

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

Probleme

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

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

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

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

Auswahl meiner Lösung

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

Frisch ans Werk

Konfigurations-Repo anlegen

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

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

Secrets in `docker-compose.yml`

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

BORG_PASSPHRASE="<redacted>"

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

- BORG_PASSPHRASE=${BORG_PASSPHRASE}

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

Secrets in Giteas `app.ini`

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

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

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

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

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

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

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

Mal ganz grob testen

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

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

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

Dennoch, einen ersten Fehler finde ich:

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

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

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

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

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

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

Eine Deploy-Pipeline erstellen

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

Setup

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

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

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

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

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

Merkwürdige Volumefehler

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

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

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

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

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

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

Anschließend bekam ich Folgendes zu lesen:

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

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

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

Verteilen der Konfiguration auf dem Server

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

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

'redir' im Caddyserver

Schallbert — Tue, 30 Jan 2024

Als ich meine Website weg von Github Pages auf einen eigenen Server umzog, hatte ich einige Probleme und offene Fragen bezüglich automatischer Weiterleitungen. Mein Blog ging nämlich von der root-Domain in eine Subdomain (blog.schallbert.de) über.

Anforderungen an die Weiterleitung

Bereits auf meine Blogartikel unter altem Namen referenzierte Links z.B. auf schallbert.de/about sollen korrekt auf die Subdomain weiterleiten (kein 404)
Die Stammseite unter schallbert.de soll vollständig nutzbar sein
Daten und Dateien für Domain und Subdomains sollen unabhängig voneinander sein
Die Webserver sollen für verschiedene Unterseiten unterschiedliche Technologien verwenden können

Umsetzung

Zuerst hatte ich gedacht, dass ich die Weiterleitungen im DNS-provider über A und CNAME Einträge erreichen könnte. Schnell wurde mir jedoch klar, dass ich a) keine Ahnung hatte, wie DNS überhaupt funktioniert und b) der richtige Weg über die Konfiguration meines Webservers führt.

Erster Versuch: redir bei ‘/’

Auf meinem Webserver (Caddy) werden Weiterleitungen in der Caddyfile per redir spezifiziert. Dabei kann das permanent (als sogenannte http 301) oder temporary per 302 (Standardeinstellung) geschehen.

Mein erster Gedanke war, dass ich schallbert.de unmodifiziert lasse und alles hinter einem eventuellen / weiterleite. Dies sieht dann in der Caddyfile wie folgt aus:

schallbert.de {
 # Define webserver
 root * /www/landing
 encode gzip
 file_server

 # Redir to subdomain if domain has a slash
 @redirect path_regexp /*
 redir @redirect https://blog.schallbert.de{uri}
}

In der Folge hat Caddy schlicht alles an die Subdomain weitergeleitet. Der Haken dabei war, dass die Subdomain selbst ja auch wieder Slashes bzw. eine URI hinter dem Slash enthält und dann wiederum weitergeleitet wird. Beispiel:

schallbert.de/post -> blog.schallbert.de/post -> blog.schallbert.de/post -> blog.schallbert.de/post -> [...]

Somit bekam ich eine rekursive Endlosweiterleitung. Ich habe meinen Server damit komplett lahmgelegt 😅

Zweiter Versuch: Filterung per Regexp

Ich brauche also eine bessere Filterung, sodass nur Slashes mit weiteren Zeichen dahinter auch wirklich weitergeleitet werden und die Weiterleitung nicht rekursiv ablaufen kann. Zum Glück hatte ich Hilfe von einem guten Freund, sodass kurze Zeit darauf folgendes Caddyfile entstand:

schallbert.de {
 # Define webserver
 root * /www/landing
 encode gzip
 file_server

 # Redir to subdomain to maintain links for blog
 @redirect path_regexp ^/[^/]+(/.*)?$
 redir @redirect https://blog.schallbert.de{uri}
}

Die Regexp prüft ab, ob ein Slash hinter der Domain URL vorliegt und dahinter zumindest ein weiteres Zeichen folgt. Hier funktioniert die Weiterleitung nun wie gewünscht und mein Blog ist auch unter den alten Links weiterhin vollständig erreichbar.

Trotzdem war ich noch nicht ganz zufrieden. Denn als ich mir eine schöne “Landing Page” auf meiner Root Domain erstellte, war von ihr plötzlich nur noch das reine HTML zu sehen. Kein favicon, keine Bilder, kein CSS.

Ein kurzer Blick in die Entwickleroptionen brachte schnell die Erkenntnis dass die Pfade aller Assets, die ich auf meiner Landing Page hinterlegt hatte, durch die Ordnerstruktur mit / gekennzeichnet, an die Subdomain weitergeleitet wurden. Wo sie natürlich nicht liegen.

Dritter Versuch: Regexp plus Dateisuche

Zum Glück bin ich wieder mal mit dem Problem nicht allein, sodass im Forum von Caddy die Lösung zu finden war:

Mit dem not file Marker kann ich in der Caddyfile Weiterleitungen definieren, falls Ressourcen auf der aktuellen Seite unauffindbar sind.

Somit sieht meine Lösung jetzt wie folgt aus:

schallbert.de {
 @filenotfound {
 path_regexp ^/[^/]+(/.*)?$
 not file
 }

 # show Caddy where to find page resources
 root * /www/landing
 encode gzip

 route {
 # Redirect to subdomain if article cannot found on root
 redir @filenotfound https://blog.schallbert.de{uri}

 # else, define webserver and show page
 file_server
 }
}

Hier ist wichtig, dass ich die Seite mit root * /www/<pagelocation> definiere, bevor ich die route anlege. Denn sonst werden die Assets erst verfügbar, nachdem ich bereits aus Ermangelung vorhandener Dateien weitergeleitet habe.

Erfolg!

Jetzt endlich wird meine Baustellenseite korrekt dargestellt.

Automatische Updates für alles!

Schallbert — Sat, 20 Jan 2024

Wie der Titel schon sagt, möchte ich Sicherheitsupdates gern installiert haben, sobald sie erscheinen. Dies gilt gleichsam für das Ubuntu meines Cloud-Servers wie auch für alle Applikationen, die ich in Docker betreibe. Da ich faul bin, möchte ich diese Sicherheitsupdates nicht manuell vornehmen, sondern vollautomatisch ablaufen lassen.

Für Funktionsupdates und -Erweiterungen hingegen ist es auch weiterhin OK für mich, von Zeit zu Zeit manuell einzugreifen. Beginnen wir also mit den Systemupgrades.

Sicherheitsupdates per `unattended-upgrades`

Ubuntu stellt - wie eine kurze Suchmaschinenabfrage ergibt - bereits ein konfigurierbares Werkzeug für solche automatisierten Updates zur Verfügung: unattended-upgrades. Ich prüfe zuerst, ob es bereits auf meinem System vorhanden ist:

Installation

schallbert:~# which unattended-upgrades
/usr/bin/unattended-upgrades

Prima, es ist bereits da. Ansonsten hätte ich die Installation schnell mit apt install unattended-upgrades nachgeholt.

unattended-upgrades konfigurieren

Hier hilft das Debian Wiki weiter: Die Konfigurationsdateien liegen in /etc/apt/apt.conf.d.

Zuerst gehe ich sicher, dass automatische Updates aktiviert sind. Hierfür prüfe ich die Datei 20auto-upgrades und stelle sicher, dass Paketindex-Updates und Upgradeinstallation aktiviert sind:

APT::Periodic::Update-Package-Lists "1";
APT::Periodic::Unattended-Upgrade "1";

Sehr gut. Jetzt sollte ich noch festlegen, zu welchem Zeitpunkt das Tool loslaufen und welcher Typ Updates installiert werden soll. Hierfür öffne ich die Datei 50unattended-upgrades und entferne die Kommentare bei den entsprechenden Zeilen.

Updatequellen festlegen

Der erste Abschnitt der Konfigurationsdatei widmet sich der erlaubten Quellen für die Updates. Hier sollten selbstverständlich nur vertrauenswürdige Provider stehen. Meine Konfig sieht hier wie folgt aus:

Unattended-Upgrade::Allowed-Origins {
 "${distro_id}:${distro_codename}";
 "${distro_id}:${distro_codename}-security";
 "${distro_id}ESMApps:${distro_codename}-apps-security";
 "${distro_id}ESM:${distro_codename}-infra-security";
};

Erlaubt werden hier Quellen für die von mir verwendete Linux-Distribution im Allgemeinen und Sicherheitsupdates inklusive ESM, was für “Extended Security Maintenance” steht.

Updates auch für Dev Releases?

Die folgende Zeile legt fest, ob auch Vorabversionen von Ubuntu Updates erhalten sollen. Bei mir steht der Wert auf auto.

Unattended-Upgrade::DevRelease "auto";

Automatischer Neustart

Einige Sicherheitsupdates (z.B. den Kernel betreffend) erfordern einen Neustart der Maschine. Sie werden daher nur in Kraft treten, wenn man in der Datei entsprechende Werte gesetzt hat. Dabei ist WithUsers natürlich Geschmackssache, denn man wird ausgeloggt, falls zufälligerweise gerade ein Update installiert wurde, was einen Neustart erfordert. Um das praktisch auszuschließen, habe ich unter Reboot-Time eine Zeit eingetragen, bei der ich sicher nicht an der Maschine hocke.

Unattended-Upgrade::Automatic-Reboot "true";
Unattended-Upgrade::Automatic-Reboot-WithUsers "true";
Unattended-Upgrade::Automatic-Reboot-Time "03:45";

Unangekündigte Neustarts haben natürlich Rückwirkung auf alle Programme, die ich verwende. Daher stelle ich in meinen docker-compose.yml Dateien sicher, dass dort bei restart: auch wirklich always oder unless-stopped notiert ist.

Benachrichtigungen

Automatische Mails oder anderweitige Push-Benachrichtigungen habe ich erst einmal nicht eingeschaltet, da ich mich noch im Testbetrieb befinde und keine große Lust auf einen Haufen weiterer Nachrichten habe. Sobald ich dies ändere, gibt es hier ganz bestimmt ein Update.

Funktionsprüfung

Um zu sehen, ob unattended-upgrades tut was es soll, schaue ich ein paar Tage später mal in die Logs unter /var/log/unattended-upgrades. Hier steht in der Datei unattended-upgrades.log zum Beispiel folgendes:

# [...]
2024-01-12 06:17:59,781 INFO Starting unattended upgrades script
2024-01-12 06:17:59,781 INFO Allowed origins are: o=Ubuntu,a=jammy, o=Ubuntu,a=jammy-security, o=UbuntuESMApps,a=jammy-apps-security, o>
2024-01-12 06:17:59,781 INFO Initial blacklist:
2024-01-12 06:17:59,782 INFO Initial whitelist (not strict):
2024-01-12 06:14:33,956 INFO Packages that will be upgraded: libc-bin libc-dev-bin libc-devtools libc6 libc6-dev locales python3-twisted
2024-01-12 06:14:33,956 INFO Writing dpkg log to /var/log/unattended-upgrades/unattended-upgrades-dpkg.log
2024-01-12 06:14:54,578 INFO All upgrades installed
# [...]

Die Datei unattended-upgrades-shutdown.log ist allerdings noch leer. Ich werde zu einem späteren Zeitpunkt prüfen, ob hier auch alles funktioniert.

Container-Updates mit `Watchtower` automatisieren

Nun zu den Updates meiner Applikationen. Ein kurzes Gespräch mit ein paar Admins ergab:

Es ist mühsam, alle Programme von Hand auf Stand zu halten
Für Anwendungen im Container gibt es Dienste, die diese Aufgabe zentral lösen
Es gab bereits schlechte Erfahrungen, wenn in der docker-compose.yml auf den aktuellsten Release referenziert wird
Bei image: <application>:latest seien hier nicht alle Anwendungen stabil bzw. erzeugten Probleme mit Abhängigkeiten

Einer Lösung für dieses Problem bietet Watchtower, welches in meinem Falle selbst wieder in einem Container läuft.

Installation

Wie üblich schreibe ich mir in einem neuen Ordner unter opt/watchtower eine docker-compose.yml:

# copied from https://containrrr.dev/watchtower/notifications/

# watchtower/docker-compose.yml
version: "3"
services:
 watchtower:
 image: containrrr/watchtower
 restart: unless-stopped
 volumes:
 - /var/run/docker.sock:/var/run/docker.sock

Watchtower benötigt docker.sock, um die Updates zu ziehen und auf den vorhandenen Containern anzuwenden. Ansonsten habe ich hier erst einmal nichts weiter unternommen. Keine Benachrichtigungen (aus obengenannten Gründen), keine Logs, nichts. Ich hoffe, dieses Setup bleibt geräuschlos und ich muss mich hier lange nicht mit einem Update zu Wort melden.

Weitergehende Schritte für die Validierung der Funktion von Watchtower finden sich z.B. in einem Tutorial von DigitalOcean.

Ablauf

Watchtower prüft die Installierten Docker images lt. Doku täglich auf Updates. Sollte des ein neues Image-release geben, schickt Watchtower ein SIGTERM-Signal an upzudatende Container, worauf sich selbige herunterfahren (Quelle). Anschließend werden die Container wieder hochgefahren.

Unfreiwillige Funktionsprüfung

Ein paar Tage nach Start des Containers wählte ich mich nochmal in meinen Server ein und sah auf gut Glück ein paar Logs durch. Ich wollte nur kurz nach dem Rechten schauen.

In den fail2ban Logdateien sah ich zu einem bestimmten Zeitpunkt, Uhrzeit 14:42:56 plötzlich seitenweise Einträge. Mehr davon, als ich die Tage vorher insgesamt gesehen hatte. Als ich zum Beginn dieser Kette von Einträgen hochscrollte, sah ich, dass fail2ban mir wohl kurz ausgestiegen war.

 2024-01-26 14:42:50,817 <container_id> INFO Shutdown in progress...
 2024-01-26 14:42:50,817 <container_id> INFO Observer stop ... try to end queue 5 seconds
 2024-01-26 14:42:50,837 <daemon_id> INFO Observer stopped, 0 events remaining.
 2024-01-26 14:42:50,878 <container_id> INFO Stopping all jails
 2024-01-26 14:42:50,879 <container_id> INFO Removed logfile: '/var/log/auth.log'
 2024-01-26 14:42:50,879 <container_id> INFO Removed logfile: '/var/log/caddy2/gitea_access.log'
 2024-01-26 14:42:50,879 <container_id> INFO Removed logfile: '/var/log/caddy2/server_access.log'
 2024-01-26 14:42:51,052 <daemon_id> NOTIC [sshd] Flush ticket(s) with iptables
 2024-01-26 14:42:51,063 <container_id> INFO Jail 'sshd' stopped
 2024-01-26 14:42:51,137 <daemon_id> NOTIC [caddy-status] Flush ticket(s) with iptables-multiport
 2024-01-26 14:42:51,137 <container_id> INFO Jail 'caddy-status' stopped
 2024-01-26 14:42:51,138 <container_id> INFO Connection to database closed.
 2024-01-26 14:42:51,139 <container_id> INFO Exiting Fail2ban
 2024-01-26 14:42:56,173 <new_container_id> INFO --------------------------------------------------
 2024-01-26 14:42:56,173 <new_container_id> INFO Starting Fail2ban v1.0.2
 2024-01-26 14:42:56,173 <new_container_id> INFO Observer start...
[...]

Die ganzen Log-Einträge zur selben Uhrzeit beginnen am Ende des oben gezeigten Abschnitts. Ein ganzer Haufen IP-Adressen wird dort zur Vorbereitung des Banns in Fail2ban geladen. Leicht beunruhigt schaute ich ins Syslog von Ubuntu:

Jan 26 14:42:55 schallbert systemd[1]: docker-<ID>.scope: Deactivated successful
Jan 26 14:42:55 schallbert systemd[1]: docker-<ID>.scope: Consumed 21:05 CPU time
Jan 26 14:42:55 schallbert dockerd[690]: time="2024-01-26T14:42:55.228607617Z" level=info msg="ignoring event" 
Jan 26 14:42:55 schallbert containerd[639]: time="2024-01-26T14:42:55.229864632Z" level=info msg="shim disconnected" 
Jan 26 14:42:55 schallbert containerd[639]: time="2024-01-26T14:42:55.230125409Z" level=warning msg="cleaning up after shim disconnected" i>
Jan 26 14:42:55 schallbert containerd[639]: time="2024-01-26T14:42:55.230145478Z" level=info msg="cleaning up dead shim"
Jan 26 14:42:55 schallbert containerd[639]: time="2024-01-26T14:42:55.240586557Z" level=warning msg="cleanup warnings time=\"2024-01-26T14:>
Jan 26 14:42:55 schallbert dockerd[690]: time="2024-01-26T14:42:55.241839655Z" level=warning msg="ShouldRestart failed
Jan 26 14:42:55 schallbert containerd[639]: time="2024-01-26T14:42:55.870912387Z" level=info msg="loading plugin \"io.containerd.event.v1.p>
Jan 26 14:42:55 schallbert containerd[639]: time="2024-01-26T14:42:55.870997689Z" level=info msg="loading plugin \"io.containerd.internal.v>
Jan 26 14:42:55 schallbert containerd[639]: time="2024-01-26T14:42:55.871007368Z" level=info msg="loading plugin \"io.containerd.ttrpc.v1.t>
Jan 26 14:42:55 schallbert containerd[639]: time="2024-01-26T14:42:55.871150831Z" level=info msg="starting signal loop" namespace=moby path>

Hm, cleaning up dead shim. Das klingt ja bedrohlich. Eine kurze Recherche zeigt, dass die Shim eine Zwischenschicht zwischen Containermanager und dem Container selbst bildet und Ein-und Ausgaben des Containers weiterleitet. Ihre Laufzeit ist an die des Containers gekoppelt.

Also war dies ein normales Herunterfahren mit anschließendem Neustart. Zum Glück kein Einbruch! Bleibt nur noch der Grund für den Neustart von Fail2ban herauszufinden. Da fällt mir ein, dass ich noch gar nicht weiß, wann Watchtower genau die Updates fährt…

Also mal schnell in die Logs von Watchtower geschaut mit docker container logs <container_id> und siehe da:

time="2024-01-26T14:42:47Z" level=info msg="Found new lscr.io/linuxserver/fail2ban:latest image (9bda077d765e)"
time="2024-01-26T14:42:50Z" level=info msg="Stopping /fail2ban (e0317a105d53) with SIGTERM"
time="2024-01-26T14:42:55Z" level=info msg="Creating /fail2ban"
time="2024-01-26T14:42:55Z" level=info msg="Session done" Failed=0 Scanned=6 Updated=1 notify=no

Damit habe ich den Beweis: Watchtower tut was es soll. Es zieht Container auf eine neue Version hoch, sobald Updates verfügbar werden. Prima!

PS: Da ich Watchtower nicht groß konfiguriert habe, nehme ich anhand der in den Logs befindlichen Zeitstempel an, dass die Updates täglich zur Zeit des Starts von Watchtower gefahren werden. Bald werde ich von latest für meine Container wohl auf ein älteres Tag release umschwenken.

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. ↩︎

Jekyll build: defekte relative Links

Schallbert — Fri, 29 Dec 2023

Das Problem

Jetzt bin ich nach ewigem Probieren nun endlich in der Lage, meinem Caddyserver die gebauten Dateien per Docker-Volume zur Verfügung zu stellen. Leider sieht die Seite aber wie folgt aus:

Die Analyse

Zuerst hatte ich den Webserver in Verdacht. Wenn ich die Website aber testweise in meinem Browser aufrufe¹, zeigt sich dasselbe Verhalten. Merkwürdig.

Offensichtlich fehlen sämtliche Stylesheets. Sieht man genau hin, sind aber auch Bilder und andere Medien nicht geladen worden, sondern lediglich ihre Beschreibung. Dann klicke ich wild auf ein paar Links zu Artikeln und Unterseiten. Dabei fällt auf, dass die Pfade anders aussehen, als ich erwartet hätte:

# --- Erwartung ---
# Bilddatei
/assets/images/test.jpg
# Artikel
/this-is-a-post

Stattdessen sehe ich:

# --- Beobachtung ---
# Bilddatei
/pages/<username>/<repositoryname>/assets/images/test.jpg
# Artikel
/pages/<username>/<repositoryname>/this-is-a-post

Dies zeigen auch die mit F12 zugeschalteten Entwickleroptionen des Browsers (siehe Bild oben): sämtliche per relativen Link eingebundene Quellen können nicht geladen werden. Übrigens ist es im Allgemeinen eine klare Empfehlung, die Entwickleroptionen bei Problemen mit der Darstellung von Webseiten aktiviert zu haben.

Liegt ja irgendwie nahe, dass meine Jekyll-Konfigurationsdatei _config.yml oder meine Übersetzungsheader i10.yml Fehler enthalten. Dafür gibt es zum Glück bereits hervorragende Hilfeseiten.

Ein Test zeigt jedoch schnell, dass ich die Angabe repository, woher der Build <username>/<repositoryname> herbezieht, nicht einfach leer lassen kann:

# bundle exec jekyll serve
Generating... 
 Jekyll Feed: Generating feed for posts
 Liquid Exception: No repo name found. 
 Specify using PAGES_REPO_NWO environment variables, 'repository' in your configuration, 
 or set up an 'origin' git remote pointing to your github.com repository. in /_layouts/default.html
 ERROR: YOUR SITE COULD NOT BE BUILT

Und, verflixt, wo kommt der Unterordner /pages plötzlich her?

Die Lösung

Durch das /pages im Pfad liegt die Vermutung nahe, dass die Ursache in einer Kombination aus Jekyll-Bauoptionen und dem Github-Pages Gem zu finden ist.

Natürlich bin ich mit diesem Problem nicht allein, und nach längerer Recherche finde ich tatsächlich eine Dokumentation der Lösung.

Also ändere ich die Umgebungsvariable JEKYLL_ENV (steht für die Bauumgebung) von production auf development, so wie es normalerweise für das lokale Bauen vorgesehen ist.

# workflows/jekyll-build-action.yml
env:
 JEKYLL_ENV: development # I had "production" here before

Und, was soll ich sagen: Kaum macht man es richtig, schon funktioniert’s!

Die Website offline darstellen funktioniert wie folgt: Die gebauten Dateien (den _site-Ordner) auf den eigenen Rechner ziehen und die index.html mit dem Browser öffnen. ↩︎

🗸 Gitea Actions Teil2 - Jekyll-Dockerimage

Schallbert — Sat, 09 Dec 2023

Die Vorgeschichte

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

“Set up job”

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

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

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

bundle install

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

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

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

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

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

act_runner: Kein Schreibzugriff auf `Gemfile.lock`

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

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

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

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

Abhängigkeiten: `sass-embedded`

Nach weniger als 20 Sekunden die nächste Fehlermeldung:

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

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

Nun endlich läuft bundle install erfolgreich durch:

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

jekyll build

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

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

Und jetzt direkt nochmal probieren, ob Jekyll erfolgreich baut:

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

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

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

Artefakte transferieren

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

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

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

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

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

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

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

Aber man kann doch `upload-artifact` verwenden!

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

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

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

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

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

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

Sackgasse.

Auch Docker `cp` funktioniert in diesem Falle nicht

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

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

Dies schlägt wieder fehl:

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

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

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

Transferieren per SFTP würde klappen

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

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

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

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

Dem Action-Container ein Volume zur Verfügung stellen

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

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

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

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

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

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

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

und schon schlägt die Aktion wieder fehl:

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

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

OK, also schnell der Action hinzugefügt:

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

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

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

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

# runner/config.yml

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

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

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

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

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

Und endlich:

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

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

Noch ein letzter Tipp

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

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

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

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

🗙 Gitea Actions - Jekyll Workflow

Schallbert — Thu, 30 Nov 2023

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

Gewünschter Ablauf

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

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

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

Ausgangspunkt: Github Actions

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

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

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

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

Probleme mit der Ruby-Installation

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

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

Na, das ist doch mal eine hilfreiche Fehlermeldung!

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

Möglichkeiten zur Fehlerbehebung

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

Den Runner mit Ubuntu22 statt Node16 betreiben

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

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

Den Runner direkt auf der Hostmaschine (Ubuntu22) laufen lassen

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

Gitea act_runner direkt auf dem Host laufen lassen

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

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

Ruby im Cache vorinstallieren

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

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

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

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

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

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

Probleme mit prebuilt-Ruby

Das Log zeigt das Problem:

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

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

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

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

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

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

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

Noch immer Fehler beim Bauen mit dem Github-Acitons script

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

💬 ::debug::isExplicit: 3.1.4

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

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

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

Docker volume überprüfen

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

docker exec -it <containerID> bash

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

Misserfolg anerkennen

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

einen anderen Ansatz.

Problemursache

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

Mehrsprachige Webseiten - l10n

Schallbert — Tue, 14 Nov 2023

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

Motivation

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

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

Jekyll plugin

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

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

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

Polyglot: Installation

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

Umstrukturierung der Website

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

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

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

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

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

Sprachauswahl

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

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

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

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

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

Veröffentlichung

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

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

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

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

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.

QR-codengrave V1.1 / V1.2

Schallbert — Sun, 12 Feb 2023

Kurze Fakten des Updates

Schnellerer Gravuralgorithmus und -Pfadoptimierung
Diverse Bugfixes
Bedienbarkeit verbessert

Demo Video

QR-codengrave Quick Demo↗

Version 1.1

Algoritmusoptimierung

Die Zeilen des QR-Codes werden nun horizontal eingelesen
Die Ausgabe der Pfade verläuft nun “rechts nach links”, danach “links nach rechts” und reduziert damit Maschinenbewegungen
Linien werden Punkten vorgezogen, da sie schneller gefertigt werden können
Linien werden nun vertikal und horizontal berechnet, die längere Linie bekommt den Vorzug
Eilgänge werden nun per XY-Vektor gefahren und nicht mehr nur eindimensional, was Zeit spart
Der neue Pfadalgorithmus benötigt 20% weniger Maschinenzeit

Bugfixes

Bei nicht vorliegendem Datensatz Persistence.dat wird das Startbild nicht angezeigt (qruwu.jpg)
Crash bei Klick auf Stop Draw wenn zuvor keine Zeichnung angefragt wurde
Crash bei Hinzufügen eines Werkzeuges bei leerer Werkzeugliste
Wird das Programm ohne Werkzeugauswahl gestartet, ist das dropdown-Menü gesperrt
Fehler in der QR-Code Größenschätzung
Fehler in der Blockbreitenberechnung bei Verwendung von V-Fräsern
Das gegenwärtig ausgewählte Werkzeug wird bei Start der Anwendung nicht im Dropdown-Feld angezeigt
QR-codes können größer dargestellt werden der Anzeigebereich

Bedienbarkeit

Default Werkzeugname geändert von name nach default zur besseren Verständlichkeit
Fräser mit geraden Schneiden (also kein V-cut) ist jetzt das Standardwerkzeug
Erstellen eines Offsets für den XY-Nullpunkt ist jetzt intuitiver gelöst (Y- nach unten, X+ nach Rechts)

Version 1.2

Kleine Änderungen zu 1.1, am Wichtigsten die Behebung eines Bugs, bei dem die Aufforderung zum Werkzeugwechsel verloren gehen kann. Außerdem werden die Winkel von V-Fräsern jetzt bei Berechnung von Pixelbreite und Größe der QR-Codes mit einbezogen.

Bugfixes

Werkzeugauswahl Tx und Werkzeugwechselkommando M06 befinden sich nun in derselben Zeile G-Code wie üblich und können so wie gewünscht Makros auslösen.
Das beim letzten Speichern verwendete Werkzeug wird nicht angezeigt, stattdessen das erste Werkzeug der Liste
Programmabsturz wenn versucht wird, den Jobstatus zu aktualisieren obwohl keine Gravurparameter vorliegen

Bedienbarkeit

Versionsnummer als Kommentar in G-code hinzugefügt
Prefix qr_ der Zieldatei im Datei-Speichern-Dialog hinzugefügt
Genauigkeit der Maschinenzeitabschätzung verbessert

Download

Der aktuelle Release ist hier zum Download verfügbar. Das Programm ist für die private Anwendung sowie Schulungszwecke kostenlos. Für weitere Informationen und Projektdokumentation stehen die readme sowie eine Projektseite zur freien Verfügung.

Upgrade von einer früheren Version

Es wird empfohlen, die Persistenzdatei von der alten Version in die neue Version zu übernehmen. Auf diese Weise werden gespeicherte Werkzeuglisten, Gravurparameter und XY-Offsets portiert. Und so geht’s:

Wechseln Sie in den Ordner, wo sich das QR-codengrave Programm befindet. Anschließend navigieren Sie zu src/assets.
Kopieren Sie die Datei Persistence.dat in einen temporären Ordner oder z.B. auf Ihren Desktop.
Entfernen Sie die alte Version durch Löschen des QR-codengrave Ordners.
Laden Sie die letzte Version herunter und verschieben Sie sie zur gewünschten Position auf Ihrem Rechner.
Verschieben Sie nun die vorab zwischengespeicherte Persistence.dat in den src/assets Ordner des aktualisierten Programms.

Videos mit dem VLC player konvertieren

Schallbert — Wed, 27 Oct 2021

Website: Medienerstellung

Für diese Website habe ich viele Mediendateien konvertiert. Die selbstgemachten Fotos sind sehr groß, was zu langen Ladezeiten der Seite und bildschirmfüllenden Bildern führt. Während es recht einfach ist, ihre Größe zu reduzieren und die JPEG-Komprimierung zu erhöhen, ist dies bei Videos schwieriger.

Das Problem

Hä, VLC?! Ich verwende den beliebten vlc player und irgendwie habe ich einige Grundkonzepte nicht richtig verstanden. Entweder wird mein Video nicht wie geplant in Graustufen angezeigt, die Ausgabedatei ist leer (Verwendung von H.264 statt H.265 behebt das Problem), das Seitenverhältnis scheint verzerrt zu sein, oder das Video hat sich plötzlich gedreht, was ich weder wollte noch erwartet habe.

In diesem Beitrag

Eine Reihe von Schritten hilft mir, wie man einfache Aufgaben zur Konvertierung und rudimentäre Bearbeitung von Videos mit vlc umsetzt.

Wie funktioniert das mit den Filtern?

Vorschau der Filter

VLC verfügt über eine Schnellvorschau für die gängigsten Filter im Menü “Werkzeuge -> Effekte und Filter”. Dies wirkt sich direkt auf das Video aus, das Sie ansehen, aber nicht auf Ihre gespeicherte Datei. Sie dient lediglich dazu, eine Vorschau zu erstellen und die Auswirkungen dieser Filter auf Ihr Video zu kontrollieren. In diesem VideoProc-Blogeintrag finden Sie ausführliche Anleitungen - und, was noch wichtiger ist, viele Bilder, die Sie dabei unterstützen. Für die ungeduldige Fraktion: weiterlesen 😉

Gefiltertes Video in Datei speichern

Um einen Filter zu speichern, den Sie für Ihre Vorschau ausgewählt haben, müssen Sie ihn zum Konvertierungsprofil hinzufügen. Solange sie angekreuzt bleiben, wird jedes Speichern mit diesem Profil Ihr Video verändern, auch wenn Sie alle Änderungen, die Sie in der Vergangenheit an den Vorschaufiltern vorgenommen haben, rückgängig gemacht haben!

Wie kann ich die Farben in meinem Video ändern?

Öffnen Sie die Videodatei, die Sie ändern möchten.
Klicken Sie auf “Werkzeuge -> Effekte und Filter” (oder drücken Sie “Strg+E”)
Es öffnet sich ein Dialogfeld mit drei Registerkarten. Wählen Sie die Registerkarte “Videoeffekte”.
Markieren Sie unter “Essentials” die Option “Bildanpassung”.
Nehmen Sie Ihre Änderungen vor und klicken Sie auf “Speichern” und dann auf “Schließen”. Eine Vorschau des Effekts wird im Hauptfenster angezeigt.
Öffnen Sie die Wiedergabelistenansicht durch Drücken von “Wiedergabeliste umschalten” (Strg+L).
Klicken Sie mit der rechten Maustaste auf Ihr Video und wählen Sie “Speichern…” im Kontextmenü.
Drücken Sie das Schraubenschlüssel-Symbol “Ausgewähltes Profil bearbeiten” und wählen Sie auf der Registerkarte “Videocodec” die Unterregisterkarte “Filter”.
Markieren Sie den Filter “Bildeigenschaften”. Dadurch wird Ihre Änderung durchgeführt, sobald Sie Ihre Datei speichern.
Geben Sie eine Zieldatei ein und klicken Sie auf “Start”.
Vergessen Sie nicht, den Filter “Bildeigenschaften” in Ihrem Profil zu deaktivieren, wenn Sie damit fertig sind. Nehmen Sie auch die Änderungen zurück, die Sie auf der Registerkarte “Videoeffekte” vorgenommen haben (Schritt 4).

Wie drehe ich mein Video?

Öffnen Sie die Videodatei, die Sie ändern möchten.
Klicken Sie auf “Werkzeuge -> Effekte und Filter” (oder drücken Sie “Strg+E”)
Es öffnet sich ein Dialogfeld mit drei Registerkarten. Wählen Sie die Registerkarte “Videoeffekte”.
Wählen Sie unter “Geometrie” die Option “Transformieren”.
Nehmen Sie Ihre Änderungen vor und klicken Sie auf “Speichern” und dann auf “Schließen”. Eine Vorschau des Effekts wird im Hauptfenster angezeigt.
Öffnen Sie die Wiedergabelistenansicht durch Drücken von “Wiedergabeliste umschalten” (Strg+L).
Klicken Sie mit der rechten Maustaste auf Ihr Video und wählen Sie “Speichern…” im Kontextmenü.
Drücken Sie das Schraubenschlüssel-Symbol “Ausgewähltes Profil bearbeiten” und wählen Sie auf der Registerkarte “Videocodec” die Unterregisterkarte “Filter”.
Markieren Sie den Filter “Videotransformation”. Dadurch wird Ihre Änderung durchgeführt, sobald Sie Ihre Datei speichern.
Geben Sie eine Zieldatei ein und klicken Sie auf “Start”.
Vergessen Sie nicht, das Häkchen beim Filter “Bildeigenschaften” in Ihrem Profil zu entfernen. Nehmen Sie auch die Änderungen zurück, die Sie auf der Registerkarte “Videoeffekte” vorgenommen haben.

Wie kann ich mein Video zuschneiden?

Öffnen Sie die Videodatei, die Sie ändern möchten.
Klicken Sie auf “Werkzeuge -> Effekte und Filter” (oder drücken Sie “Strg+E”)
Es öffnet sich ein Dialogfeld mit drei Registerkarten. Wählen Sie die Registerkarte “Videoeffekte”.
Spielen Sie unter “Zuschneiden” mit den Pixelwerten herum und beobachten Sie das Vorschaufenster genau, bis Sie mit dem Zuschnitt zufrieden sind. Notieren oder merken Sie sich die Einstellungen, die Sie anwenden möchten. Schließen Sie den Dialog.
Klicken Sie auf “Werkzeuge -> Voreinstellungen” (oder drücken Sie “Strg+P”)
Wählen Sie auf der Registerkarte Interface (Start) die Optionsschaltfläche Show Settings - All.
Scrollen Sie nach unten zum Element “Video” und öffnen Sie “Filter”.
Wählen Sie den “Video-Zuschneidefilter”.
Suchen Sie das Element Cropadd in der Filterliste auf der linken Seite. Geben Sie die Werte ein, die Sie sich in der Vorschau gemerkt/aufgeschrieben haben. Klicken Sie auf “Speichern”.
Öffnen Sie die Wiedergabelistenansicht, indem Sie auf “Wiedergabeliste umschalten” (Strg+L) drücken. Klicken Sie dann mit der rechten Maustaste auf Ihr Video und wählen Sie “Speichern…” aus dem Kontextmenü.
Drücken Sie das Schraubenschlüssel-Symbol “Ausgewähltes Profil bearbeiten” und wählen Sie auf der Registerkarte “Videocodec” die Unterregisterkarte “Filter”.
Aktivieren Sie den Filter “Videoschnitt”. Dadurch wird die Änderung durchgeführt, sobald Sie Ihre Datei speichern.
Geben Sie eine Zieldatei ein und klicken Sie auf “Start”.
Vergessen Sie nicht, das Häkchen bei “Video-Zuschnittfilter” in Ihrem Profil zu entfernen. Nehmen Sie auch die Änderungen zurück, die Sie in den Einstellungen unter “Filter” vorgenommen haben.

Wie kürze ich mein Video?

Hinweis: Eine ausführlichere Version dieses Themas findet sich in diesem Beitrag von movavi.

Öffnen Sie die Videodatei, die Sie ändern möchten.
Zeigen Sie die Schaltfläche “Aufnehmen” im VLC Player an (markieren Sie “Ansicht->Erweiterte Steuerelemente”).
Springen Sie an die Stelle, an der das geschnittene Video beginnen soll.
Drücken Sie die rote Schaltfläche “Aufnehmen”.
Spielen Sie die Videosequenz ab. Halten Sie an der Stelle an, an der der Zuschnitt enden soll.
VLCs Standardspeicherort für die Videoausgabe: C:\Benutzer\Benutzername\Video

Wie ändere ich die Videoauflösung?

Öffnen Sie die Videodatei, die Sie ändern möchten.
Öffnen Sie die Wiedergabelistenansicht, indem Sie “Wiedergabeliste umschalten” (Strg+L) drücken. Klicken Sie dann mit der rechten Maustaste auf Ihr Video und wählen Sie “Speichern…” aus dem Kontextmenü.
Drücken Sie das Schraubenschlüssel-Symbol “Ausgewähltes Profil bearbeiten” und wählen Sie auf der Registerkarte “Videocodec” die Unterregisterkarte “Auflösung”.
Geben Sie die Videogröße ein, in die Sie konvertieren möchten, und klicken Sie auf “Speichern”.

Favicon und Sammlungsgenerator

Schallbert — Sun, 13 Jun 2021

Hinzufügen eines “Tab”-Symbols - Favicon

Ich war besorgt über eine merkwürdige Fehlermeldung, die Jekyll bei jedem Refresh meiner Seite ausgab: [2021-06-13 22:07:43] ERROR '/favicon.ico' not found. Einige Online-Recherchen ergaben, dass dies weder ein Jekyll- noch ein Theme-Fehler ist, sondern ein Dateifehler. Siehe hier wie ich das Icon für diese Seite implementiert habe.

Erzeugung von Kollektionen

Ich habe herausgefunden, dass irgendwie die Sammlungserzeugung auf meiner Seite nicht funktioniert. Trotzdem geht das Layouting-Skript aber davon aus, dass es die Seiten vorbereitet hat. Wenn ich nun versuche, die Seite durch Drücken der Schaltfläche “Zurück” aufzurufen, erhalte ich einen 404-Fehler. Bis jetzt war ich nicht in der Lage, dies zu beheben, weil die Erzeugung stillschweigend fehlschlägt und ich nicht weiß, wo. Ich schalte sie vorerst komplett ab.

Markdown zu PDF konvertieren

Schallbert — Wed, 09 Jun 2021

Die Software

Ich habe die Visual Studio Code-Erweiterung Yzane’s Markdown PDF gewählt. Einfach zu installieren, einfach zu benutzen, gute Dokumentation. Nur die Bilder… naja… wurden nicht angezeigt.

Auch die Bilder werden konvertiert

Die relativen Links zu den Bildern unterscheiden sich zwischen Jekylls Interpretation und der Vorstellung des PDF-Generators. Ich musste die Markdown-Zieldatei in das Stammverzeichnis der Website verschieben und ein . vor meinem /assets hinzufügen, damit es funktioniert. Die Seitenumbrüche sind … meh… aber ich bin im Moment nicht bereit, mehr Arbeit hineinzustecken, also ist das gut genug für meine Zwecke.

Ein Problem mit Posts, die nicht angezeigt werden?

Gerade als ich diesen sechsten Beitrag von mir veröffentlicht habe, sehe ich, dass irgendwie nur Seite 2 der Beitragsübersicht angezeigt wird (sieht aus wie 5 Beiträge pro Seite) und ich kann nicht zu Seite 1 mit den “neuesten” Beiträgen wechseln:

. Hm.

Jekyll: Bilder

Schallbert — Mon, 07 Jun 2021

Der Trick

Als ich einige Bilder zu meinen Inhalten hinzufügte, war alles in Ordnung, bis ich sie auf GitHub veröffentlichte. Die meisten Bilder waren verschwunden und ich konnte nicht herausfinden, warum. Eine Suche ergab, dass Github zwischen Groß- und Kleinschreibung unterscheidet und einige meiner Bildpfade nicht alle kleingeschrieben waren. Dahinter vermute ich Unterschiede zwischen Windows/Unix, da sich die beiden Betriebssysteme hier unterschiedlich verhalten.

Ändern von Ordnernamen in Git

Es funktionierte danach immer noch nicht, weil Git meine Umbenennung nicht erkannte. Ich musste zuerst den umbenannten Ordner in einem anderen Unterverzeichnis erstellen, git mv folder/tArGet* target verwenden, um diesen an einen temporären Ort zu bringen, tArGet löschen und target an die Stelle verschieben, an der tArGet vorher war. Nur dies hat das Problem behoben und jetzt sind github und meine lokalen Dateien wieder synchron.

Jekyll Inhaltsverzeichnis

Schallbert — Sun, 06 Jun 2021

Inhaltsverzeichnis

Es gibt eine einfache Lösung, um das Inhaltsverzeichnis der Seite zu fixieren: toc_sticky: true zu den Standardeinstellungen oder dem Inhaltsverzeichnis der jeweiligen Seite hinzufügen. Wie ich das Schlüsselwort gefunden habe? Durch die Suche nach “toc” im Stammverzeichnis des Themes und ein wenig Scrollen durch die Layout-Skizzen. Ich änderte die ursprüngliche Seitennavigation in der linken Seitenleiste und tauschte sie gegen eine Dummy-Implementierung einer Galerie / Audio / Video-Inhaltsanzeige aus.

ToC auf der linken Seite

Um zu verstehen, wie man das Inhaltsverzeichnis anders als in diesem Theme vorgegeben auf der linken Seite erstellt, lesen Sie bitte dieses Kapitel des mySite-Projekts weiter.

Profil des Autors

Ich habe beschlossen, dass mein author_profile nur auf Seiten wie about, legal info und nicht auf den typischen Inhaltsseiten angezeigt werden soll. Also schrieb ich author_profile: false für die Seiten, auf denen es nicht angezeigt werden sollte - ohne Erfolg. Warum? Ich hatte es in der config.yml, Abschnitt type defaults gesetzt, aber es sollte eigentlich in der Frontmatter der einzelnen Dateien stehen.

Jekyll `-incremental` Option

Schallbert — Thu, 03 Jun 2021

die Kategorie “Neueste Beiträge”

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

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

Die Bilder

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

MinimalMistakes theme - Seitendesign

Schallbert — Wed, 02 Jun 2021

Die “Landing Page”

Endlich. Indem ich den Layout-Typ auf single änderte, konnte ich ein Header-Bild als Typ overlay einfügen! Die Schaltflächen werden jetzt innerhalb des Bildes angezeigt. Das Bild ändert sich automatisch mit der Displaygröße und -ausrichtung aufgrund der im Ordner _sass definierten visuellen Designs.

Bild der Hauptseite

Ich war dabei zu verzweifeln: meine “Landing Page” zeigte einfach kein Bild mehr an, egal wie sehr ich versuchte, die home.md Datei zu ändern. Der Grund dafür war, dass es eine Standard-“index.html”-Datei gab, die mit der Vorlage geliefert wurde und die anscheinend Vorrang hatte. Nun habe ich meine Änderungen einfach direkt dort eingefügt - funktioniert einwandfrei. Übrigens, die Höhe des Overlay-Bildes wird automatisch in Abhängigkeit von Inhalt und Höhe des Overlay-Textes gewählt.

Hinzufügen einer Seitennavigation

Einfache Lösung:toc: true in die YAML-Struktur des Markdown-Dokument für den gewünschten Artikel einfügen. Leider wird das Inhaltsverzeichnis statisch auf der Webseite angezeigt, sodass es beim Herunterscrollen verschwindet.
Schwierige Lösung: Fügen Sie die Seitennavigation in die linke Seitenleiste ein. Wie das geht? Siehe hier.

Neueste Beiträge

Im Moment erscheinen meine Artikel nicht in der Spalte “Neueste Beiträge” auf der Hauptseite. Das liegt daran, dass ich den Dienst neu starten müsste, weil die Beiträge statisch generiert werden Richtig, Jekyll ist ein statischer Seitengenerator.

ClickEncoder

Schallbert — Mon, 01 Jan 0001

Projekt-Steckbrief

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

Überblick

Bibliothek für das Arduino Framework, geschrieben in C++.

Der Quellcode selbst besteht nur aus ein paar hundert Zeilen. Er ist leichtgewichtig und leistungsfähig, da der verbesserte Algorithmus weniger Berechnungen benötigt und gleichzeitig eine bessere Zustandsinterpretation bietet als das ursprüngliche Projekt, von dem sie abgezweigt ist. Die Bibliothek ist offiziell auf PlatformIO IDE veröffentlicht und wird auf Github gehostet und gepflegt. Sie enthält Beispiele sowohl für Arduino- als auch für PlatformIO-IDEs und bietet Unittests, die nach der Anpassung an die spezifische Anwendung ausgeführt werden können.

Motivation

Ich habe zunächst die von 0xPIT veröffentlichte Originalbibliothek verwendet, aber diese verursachte bei mir einige Compiler-Warnungen, außerdem waren die Messwerte des Encoders nicht einwandfrei und manchmal gab es Jitter oder zurückspringende Werte, was ich nicht akzeptieren wollte.

Lösung

Da das Archiv ungepflegt aussah und meine Anfrage für Verbesserungen nicht beantwortet wurde, beschloss ich, diese Probleme selbst zu beheben. Ich habe also behutsam einen Teil des Codes umgeschrieben. Für mein damaliges Projekt benötigte ich auch ein “Wiederholungssignal”, wenn eine Taste kontinuierlich gedrückt wird, also fügte ich auch dies hinzu. Schließlich trennte ich den Encoder-Algorithmus von der Tastenbehandlung und stellte separate Klassen bereit, so dass nun bei Bedarf jede beliebige Kombination aus Taste und Encoder verwendet werden kann, jeweils mit konfigurierbarem Verhalten.

Encoder Algorithmus erklärt

API

Die API von ClickEncoder ist einfach und leicht zu verstehen: service() führt die Geschäftslogik aus und die Zustandsinterpretation durch. Diese Methode muss regelmäßig ausgeführt werden, um zu überprüfen, ob der Encoder seit seinem letzten Aufruf bewegt wurde, in welche Richtung, wie viele Schritte, und diese Werte dann in einer Akkumulatorvariablen speichern. getIncrement() gibt die Schrittänderungen des Encoders seit dem letzten Aufruf zurück. getAccumulate() gibt die Summe der Inkremente seit dem Start zurück. getButton() gibt den aktuellen Button-Status zurück.

void service();
int16_t getIncrement();
int16_t getAccumulate();
Button::eButtonStates getButton();

Encoder-Status

Der Encoder verwendet einen Gray Code zur Kodierung der Schritte. getBitCode() wandelt diesen Code, der über die Hardware-Pins A und B des Encoders übertragen wird, in eine “0…3”-Rasten-Interpretation um, wobei die Zahlen bei einer Rechtsdrehung ansteigen und bei einer Linksdrehung abfallen. Dies geschieht effizient ohne Verwendung von if() oder anderer Verzweigungslogik.

uint8_t Encoder::getBitCode()
{
 // GrayCode convert
 // !A && !B --> 0
 // !A && B --> 1
 // A && B --> 2
 // A && !B --> 3
 uint8_t currentEncoderRead = digitalRead(pinA);
 currentEncoderRead |= (currentEncoderRead << 1);
 
 // bit0 of result to be inverted if set
 currentEncoderRead ^= digitalRead(pinB);
 return currentEncoderRead;
}

Ich habe hier mit einem Trick gearbeitet, sodass man sich den Code-Schnipsel oben möglicherweise mehrfach ansehen muss. Der Zustand von PinA wird auf Bit1 von currentEncoderRead geschrieben, indem ich es mit der <<-Operation nach links schiebe. Gleichzeitig bleibt der Status des 0. Bits durch |= aber erhalten. Würde ich jetzt PinB einfach logisch &= anbinden, dann würde ich den Gray-Code verletzen, nachdem A&&B=2 sein sollte und nicht 3.

Sind A und B also beide nicht gesetzt, bleibt das Ergebnis 0, denn 00^00=00=0. Ist nur A gesetzt, B aber nicht, so lautet das Ergebnis 11^00=11=3. Wenn B gesetzt ist, A aber nicht, ergibt sich 00^01=01=1. Sind beide gesetzt, schließlich 11^01=10=2.

Für weitere Informationen zum Thema logische Binäroperationen siehe mein Steckbrett-Lagerfeuer Projekt

Zustandsinterpretation

Nachdem der Bitcode gelesen wurde, wird die Variable rawMovement gesetzt, die uns sagt, wie weit der Encoder zwischen zwei Durchläufen der service() Routine gedreht wurde. Hier sieht man, dass dieser Schritt zeitkritisch ist: Es kommt zu Aliasing-Fehlern, wenn der Geber schneller einmal alle Positionen wechselt, als dass service() erneut aufgerufen wird. In diesem Falle würden Schritte verloren gehen.

void Encoder::handleEncoder()
{
 uint8_t encoderRead = getBitCode();
 // bit0 set = status changed, bit1 set = "overflow 3" where it goes 0->3 or 3->0
 uint8_t rawMovement = encoderRead - lastEncoderRead;
 lastEncoderRead = encoderRead;
 // This is the uint->int magic, converts raw to: -1 counterclockwise, 0 no turn, 1 clockwise
 int8_t signedMovement = ((rawMovement & 1) - (rawMovement & 2));

 encoderAccumulate += signedMovement;
 encoderAccumulate += handleAcceleration(signedMovement);
}

Hier ein weiterer Trick: signedMovement wird berechnet, indem die Bewegung in eine vorzeichenbehaftete Ganzzahl umgewandelt wird, die 0 als “nicht gedreht”, -1 als “links gedreht” und 1 als “rechts gedreht” darstellt. Dabei wird das Verhalten bei Integer-Überlauf ausgenutzt, in Kombination mit der Interpretation von “signedness”.

Abschließend wird die Akkumulation durchgeführt und die Beschleunigung, sofern konfiguriert, dem Akkumulator hinzugefügt, je nachdem, wie schnell der Geber gedreht wird.

Um diese beiden Methoden ohne Verzweigungen zu programmieren, habe ich mehrere Abende Grübelei und praktisch einen halben Block kariertes Papier benötigt. Offen gesagt haben mich diese paar Zeilen Code an den Rande der Leistungsfähigkeit meines Hirns gebracht. Ich habe das Programmieren eben nicht von der Pike auf gelernt 😅

Die Methode getAccumulate()

Sie ist wirklich einfach. Sie gibt nur den internen akkumulierten Wert zurück, der der Konfiguration des Encoders entspricht, wie viele Ticks einen Schritt ausmachen.

int16_t Encoder::getAccumulate()
{
 return (encoderAccumulate / stepsPerNotch);
}

Die Methode getIncrement()

Gibt zurück um wie viele Ticks sich der Encoder seit dem letzten Aufruf dieser Methode bewegt hat.

int16_t Encoder::getIncrement()
{
 int16_t accu = getAccumulate();
 int16_t encoderIncrements = accu - lastEncoderAccumulate;
 lastEncoderAccumulate = accu;
 return (encoderIncrements);
}

Ermittlung des Tasterzustands

Die Methode handleButton()

Alle Tasterzustände leiten sich von zwei Basiszuständen ab: gedrückt oder nicht gedrückt. Dies spiegelt sich in der Logik wider:

void Button::handleButton()
{
 if (lastGetButtonCount < ENC_BUTTONINTERVAL)
 {
 return;
 }
 lastGetButtonCount = 0;

 if (digitalRead(pinBTN) == pinActiveState)
 {
 handleButtonPressed();
 }
 else
 {
 handleButtonReleased();
 }

 if (doubleClickTicks > 0)
 {
 --doubleClickTicks;
 }
}

Der Taster kann so konfiguriert werden, dass er seltener ausgelesen wird als der Encoder. Wenn dies der Fall ist, bleibt diese Methode zwischenzeitlich ohne Aktion.

Taste gedrückt:

handleButtonPressed() kann entweder Closed, Held oder LongPressRepeat zurückgeben, je nachdem wie der Taster konfiguriert ist und wie lange er bereits gedrückt wurde.

Taste nicht gedrückt:

handleButtonReleased() kann entweder Clicked, Released oder Doubleclicked zurückgeben, abhängig von der Konfiguration des Tasters und der Anzahl der Klicks innerhalb einer bestimmten Zeit.

Konfiguration der Bibliothek

Das Verhalten der Encoder/Tastenerkennung kann in der Datei encoder.h mit Hilfe der unten aufgeführten Konstanten geändert werden. Die Werte wurden bereits optimiert und fühlen sich, zumindest für mich, natürlich an. Sie sollten geändert werden, wenn Sie ein anderes Serviceintervall als 1ms verwenden möchten, da diese Werte alle dieses Intervall als Referenz nehmen.

// ----------------------------------------------------------------------------
// Acceleration configuration (for 1ms calls to ::service())
//
constexpr uint8_t ENC_ACCEL_START = 150; // The smaller this value, the quicker you must turn to activate acceleration.
constexpr uint8_t ENC_ACCEL_SLOPE = 75; // the smaller this value, the stronger the acceleration will manipulate values.

// Button configuration (values for 1ms timer service calls)
//
constexpr uint8_t ENC_BUTTONINTERVAL = 20; // check button every x ms, also debouce time
constexpr uint16_t ENC_DOUBLECLICKTIME = 400; // second click within x ms
constexpr uint16_t ENC_LONGPRESSREPEATINTERVAL = 200; // reports repeating-held every x ms
constexpr uint16_t ENC_HOLDTIME = 1200; // report held button after x ms
// ----------------------------------------------------------------------------

Verwenden Sie sie in Ihrem Projekt!

Die Bibliothek ist eine Open-Source-Software, die unter der MIT-Lizenz steht.
PlatformIO-Benutzer? Ganz einfach, suchen Sie sie in der Ansicht ‘Bibliotheken’, die Tags sind Arduino, Encoder, Schallbert. Dann ist es nur noch ein Klick, um sie zu Ihrer Lösung hinzuzufügen.
Alternativ können Sie auch das repository klonen oder forken und die Header/Cpp-Datei nach eigenem Ermessen verwenden.
Sie möchten etwas beitragen? Vielleicht haben Sie eine effizientere Zustandsberechnung für die Taster? Ich würde mich freuen, Ihren Pull Request in meinem Posteingang zu finden.

Diese Website programmieren

Schallbert — Mon, 01 Jan 0001

Projekt-Steckbrief

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

Die Idee

Die Idee entstand durch mein MobFobAmp-Projekt, für das ich kein Github-Repository hatte, da es keinen Code oder ähnliche Dokumentation gab. Also beschloss ich eine Website einzurichten, auf der ich Anleitungen für dieses Open-Hardware-Projekt bereitstellen kann, damit andere das Projekt nachbauen können. Ich wollte eine einfach zu hostende Lösung, die nicht zu viel Arbeit beim Einrichten erfordert. Da ich keinen eigenen Server habe, habe ich um Hilfe gebeten. moritzmar empfahl mir, für den Anfang “Github-Pages” als Site-Host zu verwenden, um eine einfache automatische Bereitstellung und globale Reichweite zu gewährleisten. Also habe ich das mal ausprobiert.

Erste Schritte

Eine statische Site kam mir genau Recht. Ohne die Notwendigkeit einer Datenbank oder eines großen Content-Management-Frameworks bleibt mein Site-Layout einfach und minimalistisch; ich wollte am Anfang nur dieses eine Projekt hosten. Github empfiehlt die Verwendung von Jekyll

Jekyll Logo ^[1]

als Website-Generator. Ich hatte einige Probleme mit dem Windows Subsystem für Linux (WSL), da es meine Terminaleingaben nicht akzeptierte, also folgte ich der Anleitung und verwendete den RubyInstaller, der bei mir sofort funktionierte.

Einrichtung der Site

Mir wurde klar, dass ich vielleicht mehrere meiner Projekte dokumentieren möchte. Deshalb kam ich auf die Idee, Projekte in Gruppen zusammenzufassen, jede mit einer Überschrift, einem kleinen Text und einem Miniaturbild. Wenn man darauf klickt, kommt man auf die jeweilige Projektseite. Das würde eine Menge Programmierarbeit für die Seiteneinrichtung und das Layout bedeuten, mit der ich nicht allzu viel Zeit verbringen wollte - meine anderen Projekte warten…

Erster Versuch mit Themes

Also folgte ich einer weiteren Anregung von Github-Pages: Die Verwendung von vordefinierten “Themes”. Zuerst habe ich das Agency Theme verwendet. Es hat eine tolle Landing Page mit einem großen Bild und unterstützt Sammlungen, die das von mir gewünschte Gruppieren von Projekten ermöglichen. Leider ist das Thema ein “Remote-Thema”, so dass die Anpassungsmöglichkeiten begrenzt waren, z. B. konnte ich eine Sammlung nicht auf eine andere Seite verweisen lassen, sondern es öffnete sich immer ein “Popup”, und das wollte ich einfach nicht. (Später habe ich herausgefunden, dass Remote-Layouts überschrieben werden können, aber da war es zu spät, denn ich hatte bereits zu einem anderen Theme-Anbieter gewechselt…) Das Theme, das ich derzeit verwende, ist das “Minimal Mistakes Theme” (siehe Fußzeile der Website), das sehr gut dokumentiert ist. Nach dem Herunterladen und ein paar ersten Schritten kämpfte ich mit benutzerdefinierten Farben (_sass) und den Kollektionen - wieder einmal - da ich zunächst nicht verstand, wie Jekyll die Bindungen hinter den Kulissen durchführt. Einige meiner Schwierigkeiten sind in den Blog-Beiträgen vom Juni 2021 zu finden.

Seitenlayouts: Hero Screens

Um die Navigation einfach und intuitiv zu gestalten, sollte man sich ein paar Gedanken darüber machen, wie das Layout der Seite aussehen soll. Die Herangehensweise wird sich bei jedem Seitentyp aufgrund der unterschiedlichen Komplexität und Dokumentstruktur unterscheiden.

Auf der Landing-/Homepage zum Beispiel soll die Navigation mitlaufen, so dass die Kategorien der Website immer sichtbar sind. Sie soll ein großes, breites Overlay-Bild mit der Seitenbeschreibung erhalten. Darunter sollen die neuesten Beiträge aufgelistet werden. Dies ist das Beispiel für die “Hero Pages” der Kollektion:

Die Projekte und ihre Inhalte enthalten eine Seitennavigation in der linken Seitenleiste, können ein scrollbares Panoramabild enthalten und haben eine breite Einstellung, um eine große Menge an Text im Inhaltsbereich anzuzeigen.

Die “hero screen”-Skizzen für die Layouts dieser Website finden Sie hier.

Sammlungen / Kollektionen

Sammlungen (englisch “Collections”) sind eine gute Möglichkeit, Inhalte zu gruppieren. Sehen Sie sich meine Open Hardware Projekte Seite an. Sie können alle Projekte in dieser Kategorie mit einem kleinen Teaser-Bild und einer Beschreibung finden, um einen Überblick zu bekommen.

So kann die Konfiguration der Sammlung aussehen:

Überlegen Sie sich einen passenden Namen für Ihre Sammlung, z.B. electronics.
Der Name der Sammlung wird in _config.yml als collections: electronics definiert.
Der Sammlungsname muss in #defaults als type: electronics gesetzt werden, damit Jekyll weiß, wie der tatsächliche Inhalt zu interpretieren ist.
Eine Sammlungsseite muss erstellt werden (z.B. im Ordner _pages) mit dem Attribut collection: electronics. Dies ist die Seite, die die Übersicht der Artikel in der Sammlung anzeigt.
Es muss ein Ordner mit demselben Namen wie der Name der Sammlung mit führendem Unterstrich erstellt werden: _electronics.
Alle Dokumente in diesem Ordner werden nach einem vollständigen Bauvorgang automatisch auf der Sammlungsseite angezeigt.
Diese Dokumente sollten ein “front matter” (Abschnitt vor dem eigentlichen Inhalt in der Datei, gekennzeichnet mit ---) erhalten, damit sie wie in der entsprechenden _layouts-Datei beschrieben angezeigt werden können, z.B. collection. Vergisst man dies, wirft einem Jekyll in der Konsole seitenlange, unverständliche Fehlermeldungen um die Ohren.

Mehr als das Standard-Theme

Ich habe zwar einige Theme-Standardeinstellungen überschrieben, verwende aber zumeist die bestehendenTheme-Infrastruktur. Dennoch hat meine Seite ein paar spezielle Anforderungen, so dass ich das Theme anpassen und neue Funktionen hinzufügen musste. Diese werden in den folgenden Abschnitten beschrieben.

Da der Navigationsbaum meiner Website ziemlich flach ist und ich nicht viele Seiten habe, zu denen ich navigieren muss, wollte ich, dass die linke Seitenleiste die Seitennavigation und nicht die Website-Navigation enthält. Daher bräuchte ich keine rechte Seitenleiste, so dass mehr Platz für den Seiteninhalt zur Verfügung stünde.

Inhaltsverzeichnis auf der linken Seite

Wie hier und dort geschrieben, war ich nie 100%ig zufrieden damit, wie meine Projektseiten aussahen:

Die ursprüngliche Idee des Themes ist, dass der Inhalt von zwei Seitenleisten eingerahmt wird. Die linke kann entweder Autoreninformationen, benutzerdefinierte Inhalte oder die Seitennavigation anzeigen. Der Inhaltsbereich ist zwischen breit und normal konfigurierbar, wobei in letzterem Fall Platz für eine zweite Seitenleiste auf der rechten Seite bleibt. Die rechte Seitenleiste ist so konfigurierbar, dass sie entweder gar nicht vorhanden ist oder das Inhaltsverzeichnis der Seite anzeigt.

Das Ziel war also die rechte Seitenleiste für mein Design zu eliminieren und statt der Seitennavigation in der linken Seitenleiste die Seitennavigation dorthin zu verschieben.

Es geht um den Ordner /_layouts, in dem Informationen darüber gespeichert werden, wie ein Seitenlayout aussehen soll. Das fragliche Seitendesign heißt single.html und ruft an einer bestimmten Stelle include sidebar.html auf, das sich in /_includes/sidebar.html befindet. Also habe ich mir einen neuen Parameter ausgedacht, mit dem ich die Anzeige des Inhaltsverzeichnisses in der linken Seitenleiste steuern kann, habe toc_left gewählt und eine Bedingung hinzugefügt:

<div class="sidebar sticky">
<!-- ...
{.% if page.toc_left %}
 {.% include toc_left nav=page.toc_left %}
{.% endif %}
... -->
</div>

(Trick: Ich musste jinja code auskommentieren und mit ... anführen, denn Liquid würde sie sonst selbst als Kommandos erkennen)

Implementierung des Inhaltsverzeichnisses

Es sollte in der linken Seitenleiste erscheinen. Also muste ich nur eine Datei namens toc_left erzeugen, die den Generator für das Inhaltsverzeichnis wie folgt aufruft:

<aside class="toc_left">
<nav class="toc" markdown="1">
<header><h4 class="nav__title"><i class="fas fa-{{ include.icon | default: 'file-alt' }}"></i>
<!-- ...
{.{ include.title | .default: site.data.ui-text[site.locale].toc_label }}</h4></header>
{.% include toc.html sanitize=true html=content h_min=1 h_max=6 class="toc__menu" skip_no_ids=true %} 
... -->
</nav>
</aside>

Audio-Einbettungen

Audio-Embeds sind diese kleinen Player-ähnlichen Dinger auf einer Website, die oft zu einer Streaming-Plattform oder ähnlichem weiterleiten. Ich brauche sie für einige meiner Audio-Projekte wie dieses mobfobamp: nur eine Überschrift und der Player darunter.

Dieser Beitrag hat mir sehr geholfen, so dass ich es einfach in das _include einfügen konnte, es ein wenig modifizieren konnte, und es funktionierte auf Anhieb.

Platzierung des Favicons

Ich folgte dieser Anleitung, um ein Favicon für die Website zu platzieren.

Der Pfad des Favicons muss unabhängig von dem Ordner, in dem sich die gerenderte Seite befindet, gültig sein. Ich musste ../ entsprechend der Tiefe der Seiten in der Ordnerstruktur der Website hinzufügen, um sicherzustellen, dass das Favicon nicht nur auf der Startseite, sondern auch auf Unterseiten angezeigt werden kann.

Optimierung für Suchmaschinen

Da meine Website einige Wochen lang nicht von Suchmaschinen gefunden wurde, beschloss ich, eine so genannte “SEO” (Suchmaschinenoptimierung) durchzuführen. Deshalb fügte ich jekyll-seo-tag hinzu und überarbeitete z.B. alle meine Links nach Juliette Sinibardy’s SEO 101. Danach habe ich meine Webseite dem Web-Analyse-Audit von Lighthouse unterzogen.

Für einen ersten Versuch sieht es meiner Meinung nach ziemlich gut aus. Das größte Problem auf der Leistungsseite scheint der CSS-Overhead zu sein.

Sicherheitsrichtlinie für Inhalte

Der Lighthouse-Audit hat gezeigt, dass es eine gute Idee wäre, externe Skripte - wie sie die Basisversion meines Themes enthält - einzuschränken. Also habe ich eine Content Security Policy (CSP) wie folgt eingeführt:

webrick:
 headers:
 Content-Security-Policy: 
 default-src 'self'; 
 script-src 'self'; 
 connect-src 'self'; 
 img-src 'self'; 
 style-src 'self' 
 font-src 'self;

Mit dieser strikten Auslegung werden Inhalte Dritter gar nicht mehr geladen (aber leider meine eigenen teils auch nicht).

Anfänglich wurde das Hintergrundbild meiner Homepage nicht angezeigt, meine eingebetteten Audiodateien konnten nicht abgespielt werden und alle Icons, die von extern geladen wurden, waren ebenfalls weg. Das Hinzufügen von media-src: 'self'; und etwas mehr Lektüre in Jakob Wilforss’ Blog und vor allem Lighthouses eigene Vorschläge halfen bei der Lösung dieses Problems. Mit Hilfe der Web developer Tools des Browsers habe ich die fehlenden Ressourcen ermittelt, die das Theme im Hintergrund zu laden versucht, so dass mein aktualisiertes CSP wie folgt aussieht:

webrick:
 headers:
 Content-Security-Policy:
 default-src 'self' 'unsafe-inline' https://cdn.jsdelivr.net/; 
 script-src 'self';
 connect-src 'self';
 img-src 'self' 'unsafe-inline' https://upload.wikimedia.org/wikipedia/commons/ https://raw.githubusercontent.com;
 style-src 'self' 'unsafe-inline' https://cdn.jsdelivr.net/;
 font-src 'self' 'unsafe-inline' https://cdn.jsdelivr.net/; 
 media-src 'self'; 
 object-src 'none';
 base-uri 'none';

Fehler

Hier sammele ich Fehler, deren Lösung trivial erscheint, die mich aber dennoch ganze Abende gekostet haben.

Jekyll serve: `UTF-8` incompatible character encoding

Man gibt bundle exec jekyll serve ein und erhält einen seltsamen UTF-8 “incompatible character encoding” Fehler? Die Ursache ist einfach: Eine der zu konvertierenden Dateien hat höchstwahrscheinlich keinen Header, der in das “Front matter” der Seite übersetzt werden kann, die aus dieser Datei generiert wird. Einfach die übliche Kopfzeile zur fraglichen Datei hinzufügen und schon funktioniert es wieder:

---
title: "Feeds and Speeds database"
description: "for (light) CNC milling machines"
header:
 image: "blah/testimage.jpg"
[...]
---

Webseite wird nicht dargestellt: `404`

Dieser Fehler war besonders fies versteckt, denn auf meinem Rechner als localhost wird die Seite einwandfrei dargestellt - nur “in Produktion” erscheint, wenn ich die Seite aufrufe, gar nichts.

Ursache: neuerdings verwende ich das permalink: Attribut in der Frontmatter von Seiten, die übersetzt werden sollen und auf einer tieferen Ebene liegen - für diese möchte ich die Links kurz halten, daher bekommen sie manuell erstellte Permalinks. Nur wenn ich ihnen ein “trailing slash” gebe, lassen sie sich auch online aufrufen. Beispiel:

# Falsch:
---
title: "This Page won't be displayed"
permalink: /projects/pageerror
# [...]
---

# Richtig:
---
title: "This Page will be displayed!"
permalink: /projects/nopageerror/
# [...]
# Wird auf dem deutschen Blog zu:
---

Website-Hosting

Diese Seite ist selbst ein normales Gitea-Repository. Es wird automatisch mit einer von Github Actions entlehnten Aktion gebaut, sobald Änderungen zum Main des Repositorys hinzugefügt werden.

Zusammenfassung

Sich damit vertraut zu machen wie Jekyll die Seite erstellt, wie das Theme mit meinen Befehlen interagiert und wie man das Verhalten des Themes überschreibt, hat einige Stunden gekostet. Aber ich denke, dass diese Seite eine klare Struktur und ein mehr oder weniger “professionelles” Aussehen besitzt - und ich musste nicht eine einzige Zeile JavaScript oder HTML schreiben, um das zu erreichen. Toll!

Inhalt in Markdown *.md geschrieben
Grundlegende Konfiguration der Seite in YAML _config.yml
Seitenlayouts in html und jinja *.html, abgelegt in _layouts und _includes
Seitenvariablen und Aussehen in SASS *.scss, automatische Generierung von css-Dateien

Lust mitzumachen oder Beiträge beizusteuern?

Sie haben Ideen, Kritik oder interessante Dinge, die Sie mir mitteilen möchten? Nehmen Sie gern über meine Diskussions-Seite Kontakt auf.

GoogleTest Demo

Schallbert — Mon, 01 Jan 0001

Projekt-Steckbrief

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

Motivation

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

Die Welt der “embedded controller”

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

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

GoogleTest direkt in PlatformIO verwenden

Hier gestaltet sich die Installation besonders einfach:

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

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

GoogleTest per GCC einsetzen

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

MinGW herunterladen und installieren

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

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

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

MinGW konfigurieren

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

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

PlatformIO konfigurieren

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

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

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

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

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

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

Tests ausführen

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

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

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

Tipps und Tricks

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

Ab diesem Punkt

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

Repository-Inhalte erklärt

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

Schnittstelle der Hardware-Abstraktionsschicht

Schauen wir uns das Interface und seine Struktur genauer an.

// hal_if.h
namespace hardwareAbstraction {

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

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

} // hardwareAbstraction

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

LoopInOut

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

// loopInToOut.h

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

 bool loopThrough(uint8_t inPin, uint8_t outPin);

private:
 hardwareAbstraction::Hal_IF& m_hal;
};

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

// loopInToOut.cpp

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

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

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

Modellierte Hardwareabstraktion (mock hal)

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

// hal_mock.h

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

Die Testvorrichtung (test fixture)

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

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

 virtual void TearDown()
 {
 delete m_loopInToOut;
 }

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

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

Der eigentliche Test

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

// unittest_loopInToOut.cpp

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

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

 m_loopInToOut->loopThrough(1, 2);
}

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

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

Implementierung des Hardwareverhaltens

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

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

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

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

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

#include "hal.h"

namespace hardwareAbstraction{

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

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

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

Gtest Schlüsselkonzepte

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

Dependency Injection

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

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

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

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

Hardware-Abstraktionsschicht

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

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

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

Der zweite Ansatz hat eine Reihe von Vorteilen:

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

Nachteile

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

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

Einige weitere Tipps

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

Schwieriges Thema!

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

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

QR-Codengrave

Schallbert — Mon, 01 Jan 0001

Projekt-Steckbrief

Schwierigkeitsgrad: Schwer 4/5
Kosten: 0€
Zeitaufwand: ~50h

Die Idee

Ein Freund bat mich, einen Bierdeckel für ihn anzufertigen. Ein eigenes Logo, ein paar Buchstaben. Nichts allzu Schweres. Auf der Rückseite wollte er einen QR-Code eingravieren lassen, der einen Link zu seiner Website enthält.

Ich habe also einen QR-Code mit einem Standard-Webtool erstellt und als .svg exportiert. Leider müsste ich in meinem CAM jedes einzelne Pixel anklicken und eine Carve-Action für dieses Pixel erstellen, was einige Minuten meiner Zeit für Auswahl-Klick-und-Parameter-Wähl-Prozeduren in Anspruch nehmen würde. Außerdem müsste ich einen Gravurstichel mit tiefenvariabler Gravur verwenden, um ein quadratisches Pixel zu erhalten, was viel mehr Bearbeitungszeit erfordert als eine runde Darstellung.

An diesem Punkt beschloss ich, viele, viele weitere Stunden meiner Zeit auf dieses Problem zu werfen und eine allgemeine Lösung für QR-Code-Gravuren zu entwickeln - eine Software namens QR-codengrave.

Erste Schritte

Spezifikation

Das, was ich mit dem Tool erreichen wollte:

Muss es können:

Texteingabe verarbeiten und in einen QR-Code konvertieren. Der Benutzer muss keine zusätzliche Konfiguration vornehmen.
Bietet die Option zur Verwaltung verschiedener CNC-Werkzeuge.
Ermöglicht Eingabe von Gravurparametern: Gravurtiefe, Eilgangbewegung im Job, Überflughöhe
Ermöglicht Eingaben für benutzerdefinierte XY0-Offsets für Werkstücke
Vektorisiert die Pixelausgabe des QR-Codes
Kann Pfade aus den Vektoren erstellen lassen, beginnt der Einfachheit halber mit einer Spirale nach innen
Übergabe der Pixellinien an ein Modul, das die Parameter des ausgewählten Werkzeugs verwendet, um Maschinenbahnen zu erstellen
Maschinenbahnen in G-Code konvertieren, der später von meiner Maschine interpretiert werden kann.
Gründliche Überprüfung der Algorithmen mit automatisierten Unit-Tests (bitte keine Abstürze in der realen Welt)
Bietet eine grafische Benutzeroberfläche, um die Parametereingabe so einfach wie möglich zu machen.

Optional

Eine Continuous-Integration-Pipeline sowohl für meine IDE als auch für Github-Aktionen erstellen
Eine Continuous-Deploy-Pipeline für meine IDE (PyInstaller) und Github-Aktionen (Artefakte, Releases) erstellen
Integrationstests für die GUI hinzufügen
Optimieren des Algorithmus zur Pfaderzeugung, da die “nach innen gerichtete Spirale” eine hohe Fertigungsqualität hat und schön anzusehen ist, aber nicht sehr effizient mit der Zeit umgeht.

Unbekannte

Zu Beginn dieses Projekts hatte ich einige offene Fragen und Risiken, die die Nutzbarkeit des Programms hätten einschränken oder sogar das gesamte Projekt undurchführbar machen können. Sie haben sich alle als falsch herausgestellt (zum Glück), aber dennoch sind hier die Risiken, die meine ganze Arbeit unbrauchbar hätten machen können:

Kameras lesen keine runden Punkt-als-Pixel-QR-Codes.
Der Kontrast, den meine Graviermaterialien bieten, ist zu gering, so dass das Lesen der Codes schlecht oder gar nicht funktioniert.
Die Bearbeitungszeit könnte sehr hoch sein, was das Projekt unwirtschaftlich machen würde.
Beschränkungen der Programmierwerkzeuge oder meiner Programmierfähigkeiten könnten die Entwicklungszeit so verlängern, dass es sich nicht lohnt, weitere Anstrengungen zu unternehmen.

Daher beschloss ich, Unit-Tests zusammen mit dem Code zu schreiben, um ein schnelles Feedback darüber zu erhalten, ob mein Code das leisten kann, was er soll. Außerdem habe ich die Funktionalität des Programms auf eine Gravurstrategie beschränkt und die GUI so gestaltet, dass sie nur eine Vorschau des QR-Codes anzeigt, nicht aber XY-Offsets oder anderen Schnickschnack.

Programmiersprache

Ich nahm einige Blätter Papier und notierte mir das Wesentliche.

Ein Modul soll sich um die Erstellung eines QR-Codes aus einer Texteingabe kümmern, ein anderes soll Vektoren und Pfade erzeugen, um diesen QR-Code zu gravieren, und eine GUI in der Mitte soll die Texteingabe, eine Bearbeitungsvorschau und Eingabemöglichkeiten für Fräswerkzeuge, Gravurparameter und Werkstückversätze enthalten.

Ich hatte ein paar Programmiersprachen zur Auswahl, die ich gut genug “spreche”:

C++ mit QT-Framework
Java
Python mit dem Tkinter-Framework

Ich entschied mich für die - meiner Meinung nach - einfachste Lösung, um so schnell wie möglich einen lauffähigen Prototyp zu haben: Python mit Tkinter. Ich kenne Tkinter von einem meiner früheren Projekte und obwohl es seine Einschränkungen hat, ist es immer noch leistungsstark genug und schnell zu verwenden.

Konzeptphase

Nach etwas Recherche fand ich eine ziemlich gute Open-Source-QR-Code-Bibliothek im Internet, die auch in Python verfügbar ist. Auf der Grundlage ihrer Ausgaben habe ich einen Vektorisierungsalgorithmus erstellt, der die QR-Code-Bibliothek abfragen kann, um die Werte der Pixel des QR-Codes in einer Scanzeile zurückzugeben:

 def _qr_bitstream_from_line(self, line):
 """Creates a bitstream from an input line of a QR-code data representation
 :param line: a QR-code data representation (line of bits within the QR-code)
 :returns bitstream: returns an array of bits reflecting the QR code's state at the respective
 point of the line."""
 bitstream = []
 if line.get_direction() == Direction.RIGHT:
 for x in range(line.get_p_start().x, line.get_p_end().x + 1):
 bitstream.append(self._qr.get_module(x, abs(line.get_p_start().y)))
 if line.get_direction() == Direction.LEFT:
 for x in range(line.get_p_start().x, line.get_p_end().x - 1, -1):
 bitstream.append(self._qr.get_module(x, abs(line.get_p_start().y)))
 if line.get_direction() == Direction.UP:
 for y in range(line.get_p_start().y, line.get_p_end().y + 1):
 bitstream.append(self._qr.get_module(line.get_p_start().x, abs(y)))
 if line.get_direction() == Direction.DOWN:
 for y in range(line.get_p_start().y, line.get_p_end().y - 1, -1):
 bitstream.append(self._qr.get_module(line.get_p_start().x, abs(y)))
 return bitstream

Dann musste ich aus diesen Linien Vektoren erstellen, so dass aufeinanderfolgende Pixel derselben Farbe zu einer Linie zusammengefügt werden konnten, die viel schneller herzustellen ist als einzelne Punkte:

 def _vectorize_bitstream(self, bitstream):
 """Creates a QrLineData object from an input bitstream
 :param bitstream: an array of bits = a line of the QR-code
 :returns line_vector: A list of QrLineData objects"""
 line_vector = []
 data = QrLineData(bitstream[0], True)
 for bit in range(1, len(bitstream)):
 if bitstream[bit] == data.get_state():
 data.add_length()
 else:
 line_vector.append(data)
 data = QrLineData(bitstream[bit])
 if not data.get_state():
 data.finalize()
 line_vector.append(data)

 return line_vector

Diese beiden Methoden würden nun von einer übergeordneten Methode aufgerufen werden, die einen spiralförmigen Pfad durch den QR-Code kennt. Meine erste GUI hatte nur drei Elemente: Ein Eingabefeld für den Text, der in einen QR-Code umgewandelt werden sollte, eine Schaltfläche, um den Algorithmus auszuführen, und eine Zeichenfläche, auf der der Gravurpfad des Algorithmus ausgegeben werden sollte.

Ich das Modul Turtle verwendet, um den vektorisierten QR-Code-Pfad zu zeichnen, ein Tool, das für Schülerinnen und Schüler geschrieben wurde, die sich in Programmiersprachen wie Python einarbeiten. Es ist zwar langsam, aber einfach einzurichten, so dass mir das für den Anfang genügte. Ich habe für’s Erste hart kodiert, um Zeit zu sparen, und meine Schleifen sind eher C-esk als pythonisch, aber egal.

 for vect in self._spiral_path[i].get_z_vector():
 if self._stop_draw:
 break
 length = vect.get_length()
 if vect.get_state():
 self.turtle.down()
 self.turtle.forward(self.pen_size * length)
 self.turtle.up()
 else:
 self.turtle.forward(self.pen_size * length)
 self.turtle.right(90)

Dieses sehr einfache Konzept sah für mich vielversprechend aus, aber ich musste ein paar Stunden daran feilen, weil meine anfängliche Ausgabe wie folgt aussah:

Your browser does not support the video tag.

QR-codengrave GUI test

Nach einer Weile konnte ich jedoch zuverlässig einen (21x21 Pixel) QR-Code auf den Bildschirm zeichnen und die Kamera meines Smartphones verwenden, um den Link zur Webseite zu erhalten. 🥳 Yeah!

Your browser does not support the video tag.

QR-codengrave Vektorerzeugung funktioniert

Unit-Tests

Die “Plattform”-Teile - Klassen vectorize_qr und machinify_vector - enthalten beide eine Menge überprüfbarer Berechnungen und Geschäftslogik. Deshalb sind meine Tests mit Pythons Standardmodul unittest schnell und einfach zu schreiben. In diesem Beispiel überprüfe ich, ob die von mir erstellte Linienklasse eine Länge (n+1 Stil) korrekt berechnet:

class TestLine(unittest.TestCase):

 def test_line_x_calculates_valid_length(self):
 line = Line(Point(0, 0), Point(5, 0))
 self.assertEqual(6, line.get_abs_length())

Aber es wurde schnell komplexer, als ich testen wollte, ob die Ausgabe der QR-Code-Generatorbibliothek in meinem Programm korrekt verarbeitet wird. Dazu musste ich die Bibliothek in meine zu testende Klasse einbinden, damit ich eine Mock-Implementierung einschleusen konnte, die dann im Test abgefragt wird.

Dieses Muster der Abhängigkeitsinjektion ist der Vorgehensweise in C++ sehr ähnlich, wo ich viel mehr Erfahrung habe (siehe ein Projekt hier oder ein anderes hier, zum Beispiel), nur dass in Python viel weniger Boilerplate-Code nötig ist, um dorthin zu gelangen. Ein paar Suchvorgänge im Internet und schon war der folgende Testfall geschrieben:

 def test_bitstream_qr_input_loop_xpos_correct(self):
 mock_qr = QrCode.encode_text("schallbert.de", QrCode.Ecc.MEDIUM)
 mock_qr.get_module = MagicMock()
 cam = VectorizeQr(mock_qr, 1)
 cam._qr_bitstream_from_line(self.test_line_x)
 mock_qr.get_module.assert_called_with(20, 0)

Ich injiziere die “echte” QrCode-Bibliothek, aber mit einer Mock-Methode, die für mich von Interesse ist, get_module(). In dem Test stelle ich sicher, dass die Methode mit den erwarteten Parametern aus meiner zu testenden Klasse aufgerufen wird.

Mit solchen Tests kann ich sichergehen, dass die Bausteine meines Algorithmus wie vorgesehen funktionieren und dass Regressionen schnell gefunden werden können.

Der lange Weg zum Produkt mit Minimalanforderungen

Beflügelt von diesem schnellen Erfolg, ging ich aufs Ganze. Vor der Implementierung des G-Code-Generators musste ich einen Werkzeugselektor entwerfen, da ich die Werkzeugeigenschaften zur Verfügung haben musste, bevor ich die Abmessungen und die Werkzeuggeschwindigkeit / den Vorschub für die QR-Code-Gravur einstellen konnte.

Nach einigen erfolglosen Versuchen im Hauptfenster entschied ich, dass das Werkzeugkonfigurationsfenster stattdessen ein Dialog sein sollte (den Tkinter Toplevel nennt), so dass die Werkzeugparameter eingegeben und nach Abschluss an die Haupt-GUI zurückgeschickt werden können. Ich habe den Dialog modal gemacht mit

 self._dialog.grab_set()

So hat er immer den Fokus, damit nicht mehrere Instanzen dieses Fensters gleichzeitig vorhanden sein können. Ich habe die konfigurierten Werkzeuge in einer nummerierten Liste gespeichert, so dass die Anwendung, sobald sie gefüttert wurde, die Liste zur Verfügung stellt, damit der Benutzer das gewünschte Werkzeug für den Job aus einem Dropdown-Menü auswählen kann.

In diesem Schritt musste ich zwei Dinge implementieren:

Überprüfungen für Wertetyp und -bereich
Ein Persistenzmodul, so dass die eingegebenen Tools einen Neustart der Anwendung überleben würden.

Überprüfungen von Wertetyp und -bereich

Dies könnte mit einem Ereignis-Auslöser innerhalb des Eingabefeld-Widgets wie folgt erreicht werden:

 reg = config_tool_frame.register(validate_number)
 tool_nr_entry.config(validate="key", validatecommand=(reg, '%P'))

Anschließend wird der eingegebene Wert an einen einfachen Validator übergeben, der lediglich versucht, den Eingabewert in einen Float-Wert umzuwandeln und False zurückgibt, wenn dies einen Fehler erzeugt,

def validate_number(entry):
 """Helper function that is used in validators to check
 that the entered keystroke is a number"""
 if entry == '':
 return True
 try:
 float(entry)
 return True
 except ValueError:
 return False

Eine Prüfung ob der Wert plausibel ist erfolgt erst, wenn die Schaltfläche “OK” gedrückt wird, um die eingegebenen Daten an die Anwendung weiterzuleiten. Bei Überschreitung des Bereichs würde ein Warn-Popup (Modul tkinter.messagebox) erscheinen, das auf das mögliche Problem hinweist.

Persistenz

Das Persistenzmodul war etwas schwieriger zu implementieren. Ich entschied mich dafür, ein Element zu erstellen, das C++-Kenner eine statische Klasse nennen würden, d.h. eine Klasse, die nicht instanziiert werden muss, um eine ihrer Methoden aufzurufen. Diese Klasse hat nur zwei Methoden namens load und save, die das tun, was ihr Name andeutet, indem sie Pythons pickle Modul zur Serialisierung von Objekten verwenden, die ich speichern wollte. In Python habe ich den Dekorator @classmethod verwendet, um die statische Natur dieser Klasse zu kennzeichnen.

So einfach kann die Serialisierung von Daten mit den richtigen Werkzeugen werden:

 with open(app_persistence_path, 'wb') as file:
 pickle.dump([cls._tool_list,
 cls._z_params,
 cls._xy0],
 file, protocol=2)

Als dies zuverlässig funktionierte, fügte ich ein Widget zur Konfiguration der Gravurparameter hinzu. Von Nachteil bei statischen Methoden ist, dass sie nur schlecht unit-testbar sind, weil Dependency Injection hier nicht funktioniert; sie sind ja instanzlos. Es bliebe mir nichts anderes üblich als “Fakes” zu schreiben, die im Testfalle die echte Speicher- bzw. Ladefunktion ersetzt.

Gravur-Parameter

Um den G-Code aus meinen QR-Code-Daten zu generieren, benötigte ich nicht nur Werkzeug- und Geschwindigkeits-/Vorschubdaten, sondern ich musste auch wissen, wie tief ich gravieren wollte, wie weit das Werkzeug bei Eilgängen über der Werkstückoberfläche schweben sollte und welche Sicherheitshöhe die CNC für die Rückkehr zum Ursprung oder zur Ausgangsposition verwenden sollte.

Es wird auf ähnliche Weise wie das Dialogfeld “Werkzeugkonfiguration” erstellt und verwendet dieselben Mechanismen zur Überprüfung von Typ und Bereich. Der einzige Unterschied besteht darin, dass er nicht über einen Klick auf eine Schaltfläche, sondern direkt über das zugehörige Textfeld gestartet wird, das den aktuellen Wert der Gravurparameter im Hauptfenster anzeigt.

Werkstück XY Nullpunktverschiebung

Der Konfigurationsdialog für den Werkstückversatz enthält einige Radiobuttons zur Auswahl der gängigsten Werkstückursprünge und eine benutzerdefinierte Option, mit der der Benutzer Werte für den X- und Y-Achsennullpunkt des Werkstücks eingeben kann. Eine Funktion im Hintergrund berechnet den erforderlichen Versatz relativ zum Startpunkt der Gravierspirale.

Normalerweise würde ich nicht wollen, dass die grafische Benutzeroberfläche Berechnungen durchführt oder viel Verzweigungslogik verwendet, da dies schwieriger zu verifizieren ist, weil die Test Fixtures damit größer und schwieriger zu warten werden. In diesem Fall habe ich mich jedoch entschieden, die Offset-Berechnung mit Hilfe einer Wertetabelle innerhalb des GUI-Moduls durchzuführen, um zu vermeiden, dass alle GUI-Module zur Plattform und zurück kommunizieren müssen (und das durch 4 Klassen hindurch).

 def _get_xy_offset(self, offset):
 """calculates an XY coordinate offset from a preset point, taking the selected tool diameter into account.
 :param offset the selected offset from the above enum class
 :returns a XY Point where XY0 is assumed for the engraving."""
 qr = self._qr_dimension
 d = self._tool_diameter
 offsets = {Offset.CENTER: Point((d - qr) / 2, (qr - d) / 2),
 Offset.TOPLEFT: Point(d / 2, -d / 2),
 Offset.TOPRIGHT: Point(d / 2 - qr, -d / 2),
 Offset.BOTTOMLEFT: Point(d / 2, qr - d / 2),
 Offset.BOTTOMRIGHT: Point(d / 2 - qr, qr - d / 2)
 }

 if offset in offsets:
 return offsets[offset]

Erstes Release V1.0

Die erste Version ist minimalistisch. Sie erfüllt ihren Zweck, hat aber noch einige Fehler (z.B. eine Fehlermeldung, wenn kein Werkzeug in der Auswahlliste ausgewählt ist) und Unzulänglichkeiten (z.B. ist das Zeichnen eines QR-Codes sehr langsam, beim erneuten Zeichnen kippt der QR-Code ein wenig usw.), aber sie sollte einfach funktionieren und dem Benutzer helfen, die schlimmsten Fehler auf seinem Weg zu vermeiden.

Ich habe die Ausführung auf meiner CNC-Maschine getestet und zumindest mein Handy ist in der Lage, zu einer Website zu navigieren, indem es einfach die Kamera auf das Werkstück hält 📱.

Automatisierte Integrationstests für die GUI: Frustrierende Arbeit

Als meine erste Version herauskam, wollte ich einige Tests für die grafische Benutzeroberfläche hinzufügen. Da ich es nicht geschafft habe, dort absolut keine Geschäftslogik zu haben, wollte ich zumindest Bereichsprüfungen sowie die Kommunikation mit der Plattform überprüfen, um sicherzustellen, dass alles wie vorgesehen funktioniert.

Aufgehängt in der Messagebox

Zu diesem Zweck schrieb ich einige Tests, die auf meinem lokalen Rechner liefen, mit dem Nachteil, dass, wenn der Test auf einen Warn- oder Fehlerdialog messagebox.showinfo / messagebox.showerror stieß, eine manuelle Benutzerinteraktion unbedingt erforderlich war, damit das Fenster geschlossen und der Test fortgesetzt werden konnte.

Ich habe keine einfache Möglichkeit gefunden, dieses Problem zu umgehen, da die Messagebox als unabhängiges Widget agiert, das nicht einfach manipuliert werden kann. Auch meine Versuche, einen Tastendruck als Seiteneffekt aus dem Test heraus auszulösen, waren nicht von Erfolg gekrönt (und wären am Ende wohl auch keine saubere Lösung gewesen).

Meine Lösung nach ein paar Stunden gemurmelten Fluchens ist, dass die Messagebox-Widgets in die GUI-Klassen injiziert werden, die sie verwenden:

@patch('src.gui.gui_tool_manage.GuiToolManager')
 def setUp(self, mock_guitoolmanager):
 tk.Tk() # required to have tk variables properly instantiated
 self.mock_guitoolmanager = mock_guitoolmanager
 self.mock_msg = MsgBox()
 self.mock_msg.showinfo = MagicMock()
 Persistence.set_mock_msgbox(self.mock_msg)
 self.config_tool = GuiConfigureTool(self.mock_guitoolmanager, self.mock_msg, {'padx': 5, 'pady': 5})

Auf diese Weise kann ich mock_msg in die Gui-Klasse werfen, so dass nicht die echte showinfo genommen wird, sondern das Mock weiß, ob er wie vorgesehen aufgerufen wurde. Ich könnte ihr zur Testvorrichtung hinzufügen, so dass mein Testcode selbst DRY bleiben könnte.

Es fügt dem Konstruktor mehr Argumente hinzu und delegiert die Instanziierung an eine Klasse höherer Ebene, aber die Verwendung innerhalb der zu testenden Klasse bleibt trivial. Im Einsatz unter Realbedingungen agiert die Schnittstelle wie ein Proxy, der dann die echte showinfo-Methode des Messagebox Objektes aufruft.

Probleme mit statischen Klassen

Da die Persistenzklasse, die ich oben erwähnt habe, statisch ist, d.h. keine Instanziierung erfordert, hatte ich das nächste Problem von Anfang an in meinen Code eingebaut: Ein Integrationstest würde nun versuchen, in eine tatsächliche “persistence.dat”-Datei zu schreiben, eine Abhängigkeit, die ich nicht haben wollte, insbesondere nicht in der kontinuierlichen Integration (CI) - denn dort würde das Programm die Rechte für das Schreiben auf Festplatte nicht besitzen.

Also habe ich Persistence in die Haupt-GUI-Datei verschoben, die nicht getestet werden würde, und folgte damit Steven Andersons großartigem Blogbeitrag. Die Haupt-GUI sollte ohnehin nur deklarativen Code enthalten, und die geladenen Daten werden dann in die Klassen kaskadiert, die sie verwenden, anstatt in die Persistenzklasse, die die eigentliche Lade-/Speicheroperation durchführt.

Zukünftige Versionen

Folgendes ist für spätere Releases geplant:

Die Zeichnungsgeschwindigkeit des QR-Codes muss erhöht werden
Grafikfehler (Skalierung, Kippen) und unscharfe Ränder des Zeichenbildschirms sollen behoben werden
CNC-Bahnen sollen optimiert werden, um die Fertigungszeit zu verringern
Fehlerbehebungen

Zumindest wenn es welche gibt; mal sehen, wie oft ich dieses Tool benutzen werde. Die Dinge, die mich am meisten stören, werden wahrscheinlich zuerst behoben werden.

Ach ja, noch etwas: Danke für’s Lesen des gesamten Artikels. Zur Belohnung gibt es eine Kopie QR-codengrave kostenlos zum Herunterladen. Es kann für den privaten Gebrauch gern verwendet werden. Falls Sie eine kommerzielle Nutzung planen, lassen Sie es mich bitte im Voraus wissen.

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.

Schaltplan

Umzug von Github Pages

Schallbert — Mon, 01 Jan 0001

Projekt-Steckbrief

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

Motivation

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

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

Überblick

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

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

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

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

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

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

Konfiguration meines Servers

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

SSH auf dem Server einrichten

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

Sodann erstelle ich mir ein neues Schlüsselpaar per Befehl

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

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

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

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

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

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

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

Docker installieren 🐳

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

caddy installieren 🛒

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

#caddy2/docker-compose.yml

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

networks:
 caddy-proxy:
 external: true

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

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

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

Sieht gut aus!

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

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

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

Test-Website erstellen 🧪

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

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

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

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

Und dort dann ein unverkennbares Hello World eintragen:

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

Speichern, fertig.

Das Stammverzeichnis von caddy sieht nun so aus:

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

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

docker compose up -d

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

[+] Running 1/1
 ✔ Container caddy Started

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

Gitea installieren 🍵

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

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

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

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

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

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

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

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

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

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

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

docker compose up

So sieht die Konsolenausgabe bei mir aus:

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

Webzugriff einrichten

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

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

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

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

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

Gitea per Web-Oberfläche konfigurieren

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

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

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

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

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

Jetzt schnell prüfen, ob auch alles funktioniert:

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

Perfekt.

Gitea-Konfiguration per `app.ini` fertigstellen

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

docker compose down

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

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

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

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

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

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

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

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

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

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

[attachment]
PATH = /data/gitea/attachments

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

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

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

[lfs]
PATH = /data/git/lfs

[mailer]
ENABLED = false

[openid]
ENABLE_OPENID_SIGNIN = true
ENABLE_OPENID_SIGNUP = true

[cron.update_checker]
ENABLED = false

[repository.pull-request]
DEFAULT_MERGE_STYLE = merge

[repository.signing]
DEFAULT_TRUST_MODEL = committer

[oauth2]
JWT_SECRET = <redacted>

[actions]
ENABLED = true

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

Nun kann der Container neu gestartet werden:

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

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

Action Runner einrichten 🏃

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

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

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

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

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

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

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

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

Funktionsprüfung Runner

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

Commit, push, und - nichts.

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

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

Wahnsinn! 🥳

Zwischenfazit

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

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

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

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

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

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

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

Code 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

PHP2shell: Kritische Sicherheitslücken

Schritt 1 Erkennen: Wir haben ein Problem.

Status 21.10.2026, 10:30 MESZ

Schritt 2 Sofortmaßnahmen: Nextcloud vom Netz trennen

Schritt 3 Vorläufige Eindämmung: Nextcloud-Instanz deaktivieren lassen

Status 21.10.2026 11:43 MESZ

Status 21.10.2026 12:01 MESZ

Schritt 4 Beobachten der Situation: Verfügbarkeit des Patches, Einspielen erster Betreiber

Status 21.10.2026 14:20 MESZ

Status 21.10.2026 16:34 MESZ

Status 21.10.2026 19:52 MESZ

Status 21.10.2026 22:40 MESZ

Status 21.10.2026 23:00 MESZ

Schritt 5 Erkenntnis und Schlussfolgerung

Schritt 6 Aktionen

Nachtrag: 22.10.2026 09:30 MESZ

Schritt 7 Erste Reflektion

Status 24.10.2026 16:30 MESZ

Status 27.10.2026 17:00 MESZ

Schritt 8 Beobachtungen analysieren und Informationskanäle justieren

Den POC verstehen

Härtung

Später am selben Tag

Status 28.10.2026 21:30 MESZ

Passwortmanager mit Security Keys verwenden

Der Passwortmanager

Kein Firefox Password manager

Kein Vaultwarden

KeePassXC

Einrichtung von KeePassXC mit einem HSK

Yubikey

Nitrokey

Kompatibilität Yubikey

Holzweg A: Einträge aus der Datenbank klonen

Holzweg B: Die ganze Datenbank kopieren und HMAC updaten

Lösung: Konvertieren des HMAC-Secrets

KeePassXC: Passwörter schön geordnet hinterlegen

Passwortfamilien

Gruppierung

Icons 🔑

Kritische Schwachstellen bei Gitea (und Forgejo)

Gewahrwerdung

Gitea als Angriffsziel

Warum ist Gitea ein attraktives Ziel?

Was ist eine RCE?

Das Gitea-Ökosystem

Verwundbarkeit durch offene Registrierung

Verwundbarkeit durch Standardkonfiguration für Reverse Proxies

Die Sicherheitslücken

Exkurs: Die CVSS-Bewertung

Bedeutung der CVSS-Einzelwerte

CVE-2026-20896: Authentication bug in Gitea through reverse-proxies

CVE-2026-59774: File-read flaw for anything the Gitea Service Account can read

CVE-2026-60004: RCE allowing attacker with ordinary user rights to execute arbitrary shell commands as the Gitea OS user.

Das Lagebild

Der Cryptominer

Noch größerer Schaden möglich

Wie entdecke ich einen Angriff?

Bei Befall: Quarantäne

Lösungen

Gitea Updaten!

Gitea und Runner rootless ausführen

Zusätzliche Maßnahmen (Härtung)

CVE-2026-20896: Netzwerkzugriff erschweren

CVE-2026-59774: Gitea updaten!

CVE-2026-60004: Falls möglich Self-Registration abschalten

Ausblick und Fazit

Sofort: Härtung durchführen

Kurzfristig: Automatische Updates

Mittelfristig: Her mit Monitoring

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

Gitea und Runner `rootless` ausführen