This Site on Schallberts Blog

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.

Giteas act_runner rootless: Startprobleme

Schallbert — Sat, 28 Mar 2026

Das Fehlerbild

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

Issue-Ticket bei Gitea

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

Problem mit Kernel-Berechtigungen?

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

Warum Container keine Container starten dürfen

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

Auswirkungen, falls trotz DinD etwas schief geht

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

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

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

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

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

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

Sackgasse: Nur unbedingt benötigte Rechte vergeben

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

Meine Vorgehensweise:

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

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

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

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

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

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

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

Zukünftige Lösung: Virtualisierung oder Daemonless

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

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

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

Linux Security Modules (seccomp, AppArmor, SELinux)

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

Apparmor

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

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

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

Einfache Lösung: Komplett abstellen

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

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

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

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

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

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

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

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

Richtige Lösung: Für jede Anwendung justieren

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

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

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

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

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

Entsprechend gut sieht jetzt auch das Logfile aus. Fertig!

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

Jekyll-dockerimage: Bundler und Gemfile

Schallbert — Fri, 14 Nov 2025

Was ist bundler?

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

Will ich lokal bauen, so tippe ich beispielsweise

bundle exec jekyll serve --incremental --future

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

bundler in der CI-Pipeline

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

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

Keine Schreibrechte

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

Spezifikationsdatei für bundler

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

Fehlerbehebung

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

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

bundle config set frozen true

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

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

`Gemfile.lock` für verschiedene Umgebungen optimieren

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

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

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

In meiner Lockfile taucht daraufhin folgender Eintrag auf:

nokogiri (1.18.10-x86_64-linux-musl)

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

Giteas act_runner 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

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

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. ↩︎

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.

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.

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.