Software on Schallberts Blog

Umzug von Jekyll zu Hugo

Schallbert — Sun, 06 Sep 2026 00:00:00 +0000

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 (Theme Terminal).

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;
 --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
│   ├── audio
│   ├── css
│   │   ├── fontawesome
│   │   ├── katex
│   │   ├── main.scss # <-- theme import, customization
│   │   └── webfonts
│   ├── docs
│   ├── images
│   ├── js
│   │   ├── lunr
│   │   ├── _main.js
│   │   ├── main.min.js
│   │   ├── plugins
│   │   └── vendor
│   └── video
├── banner.js
├── CNAME
├── _config.yml
├── _data
│   ├── de
│   │   ├── l10n.yml
│   │   ├── navigation.yml
│   │   └── ui-text.yml
│   └── en
│   ├── l10n.yml
│   ├── navigation.yml
│   └── ui-text.yml
├── en
│   └── index.html
├── Gemfile
├── Gemfile.lock
├── _includes # <-- Layouts (HTML), partials, 3rd-party
├── index.html # <-- Landing page
├── _layouts # <-- Page layouts
│   ├── archive.html
│   ├── archive-taxonomy.html
│   ├── categories.html
│   ├── category.html
│   ├── collection.html
│   ├── compress.html
│   ├── default.html
│   ├── home.html
│   ├── posts.html
│   ├── search.html
│   ├── single.html
│   ├── splash.html
│   ├── tag.html
│   └── tags.html
├── LICENSE
├── package.json
├── package-lock.json
├── _pages
│   ├── 404.md # <-- German version
│   ├── [...]
│   ├── en
│   │   ├── 404.md # <-- English version
│   │   ├── [...]
├── _posts/
│   └── en 
├── _projects/
├── Rakefile
├── README.md
├── _sass
│   ├── minimal-mistakes # <-- Styles (SCSS) for layouts and partials
│   ├── minimal-mistakes.scss
│   └── _video.scss
├── _site/ # <-- Build artifacts
├── staticman.yml
└── tags
 ├── en
 │   └── tags.md
 └── tags.md

Nachher

.
├── archetypes
├── assets
│   └── scss
│   └── landing.scss # <-- custom styling for my landing page
├── content
│   ├── de
│   │   ├── about.md
│   │   ├── announcements/
│   │   ├── posts/
│   │   └── projects/
│   └── en
│   ├── about.md
│   ├── posts/
│   └── projects/
├── data
├── hugo.toml
├── 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
│   └── video.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)

Hugo

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

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

Jekyll

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 (>768px).

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

{{ $src := .Get "src" }}
{{ $alt := .Get "alt" | default "" }}
{{ $position := .Get "position" | default "center" }}

<div class="image-wrapper {{ $position }}" >
 <img src="{{ $src }}" alt="{{ $alt }}" />
</div>

/* /static/terminal.css */

.image-wrapper.center img,
.image-wrapper.left img,
.image-wrapper.right img{
 max-width: 100%;
 border: 4px solid var(--accent);
 display: block;
 margin-left: auto;
 margin-right: auto;
}

@media (min-width: 768px){
 .image-wrapper.left img{
 float: left;
 margin-right: 1rem;
 max-width: 50%;
 }

 .image-wrapper.right img{
 float: right;
 margin-left: 1rem;
 max-width: 50%;
 }
}

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.

/* /static/terminal.css */

.media-wrapper{
 width: 100%;
 max-width: 100%;
 margin: var(--line-height) 0;
 display: flex;
 justify-content: center;
}

.media-container{
 width: 100%;
 max-width: 768px;
 display: block;
 border: 4px solid var(--accent);
 background-color: var(--accent);
 border-radius: var(--radius);
 overflow: hidden;
 text-align: center;
}

.media-container audio,
.media-container video{
 width: 100%;
 display: block;
}

.media-container iframe{
 width: 100%;
 min-height: 400px;
 aspect-ratio: 16/9;
 display: block;
}

.media-title{
 word-break: break-word;
 hyphens: auto;
 color: var(--background);
 font-weight: bold;
}

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>

links

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.

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… 🤔

Direkter Vergleich

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

Dabei entsteht die folgende Auflistung:

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

Größe

Ein anderes Diagramm erhalte ich, wenn ich ganz unten links auf die Stoppuhr klicke und damit eine performance analysis ausführe.

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

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

Insgesamt habe ich mit Hugo und Terminal deutliche Optimierungen vorliegen.

Manuell implementiert in Hugo hatte ich das bedingte Laden von Katex (90kB min.css), Größenbeschränkungen für Medien-Vorschaudateien und insgesamt weniger CSS.
Automatisch in Hugo sind Medien-Vorschaudateien von den hochauflösenden Dateien abgeleitet und per Bildprozessor auf die Darstellungsverhältnisse im gebauten Zustand platzoptimiert. Diese Optimierung spart bei vielen, klein dargestellten Bildern eine Menge Bandbreite.
Das Terminal-Theme zeigt anders als minimalmistakes keine Kärtchen für “weitere Posts” an. Dies spart erneut die Übertragung von vier Vorschaubildern. Der Javascript-Inhalt geht außerdem gegen null - eines der Ziele, das ich mir gesteckt hatte.

Komplexität

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

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

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

Für die tagtägliche Benutzbarkeit gefällt mir Hugo ganz klar besser als Jekyll.

Auslieferung/Continuous Deployment

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

Für Hugo muss ich mal schauen, ob ich am Ende nicht doch einen eigenen Post mache…

htmltest-Konfiguration für Hugo

Schallbert — Mon, 10 Aug 2026 00:00:00 +0000

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 00:00:00 +0000

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

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

Konfiguration

Grundlage für das Problem ist die folgende Einstellung:

# hugo.yml

defaultContentLanguage: "de"
defaultContentLanguageInSubdir: false
disableDefaultLanguageRedirect: true

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

Die Verzeichnisstruktur lautet:

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

Das Problem mit der Standardsprache

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

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

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

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

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

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

Lösung: Sprachabhängige Link-Prefixes

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

Standardsprache auslesen

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

Code für render-link.html

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

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

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

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

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

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

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

Zusatzfunktionen

Was der Code sonst noch macht:

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

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

Richtig auflösende Permalinks auf Überschriften

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

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

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

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

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

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

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

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

Funktioniert so noch nicht.

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

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

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

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

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

Scheitern von SSH-Verbindungen

Schallbert — Fri, 12 Jun 2026 00:00:00 +0000

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

Problem: “No Route To Host”

Die Konsolenausgabe zeigt (im lokalen Netz):

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

Oder (in einem entfernten Netz)

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

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

Problem: Connection Refused

Konsolenausgabe:

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

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

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

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

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

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

Problem: Too Many Authentication Failures

Konsolenausgabe:

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

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

Server-Anmeldelimit prüfen

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

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

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

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

Git-Config überprüfen

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

Beispiel:

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

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

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

Problem: Permission Denied (publickey,password)

Konsolenausgabe:

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

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

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

Die Ausgabe bei falschem Username sieht so aus:

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

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

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

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

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

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

Problem: Agent Refused Operation

Konsolenausgabe:

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

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

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

Hardware Security Key: SSH einrichten

Schallbert — Sun, 03 May 2026 00:00:00 +0000

Motivation

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

SSH-Zugriff für Hardware Security Keys einrichten

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

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

Was so nicht funktioniert

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

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

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

Bedeutung des Kommandos und der wichtigsten Optionen

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

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

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

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

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

-f ed25519-sk_ssh:github_schallbert_yubikey-main

⚠️ Obacht bei Nutzung von Windows: Dort ist der Doppelpunkt : nicht als Zeichen in Dateinamen erlaubt. Er wird durch den Unterstrich _ ersetzt, was in der config entsprechend abgebildet werden muss (strg+h -> : ersetzen mit _)

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

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

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

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

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

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

Woran hat es gelegen?

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

Was hingegen funktioniert

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

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

Was `verify-required` benötigt

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

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

Installation von ssh-askpass

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

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

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

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

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

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

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

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

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

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

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

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

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

Übertragung auf Windows-Systeme

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

Ich öffne die Kommandozeile und tippe

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

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

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

VPS: Vorsicht bei Schlüssel-Ersatz

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

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

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

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

Neue Schlüssel manuell auf VPS ablegen

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

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

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

Schlüssel erfolgreich übertragen?

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

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

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

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

Auf direktem Wege ohne ssh-copy-id

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

Überlegungen zu Komfort und Bedienbarkeit

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

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

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

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

Hardware Security Keys

Schallbert — Sat, 25 Apr 2026 00:00:00 +0000

Begriffsabgrenzung: TPM und HSK

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

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

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

Was bisher geschah

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

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

Zielvorstellung

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

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

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

Yubikey

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

Yubico Authenticator

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

Konzept des HSK

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

Zweitschlüssel

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

NFC

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

Was mir beim Umgang mit Yubikey fehlt

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

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

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

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

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

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

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

Funktionsumfang und kryptographische Landschaft

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

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

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

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

Gehen wir die Module mal durch.

2-Faktor-Authentisierung “Yubikey: Accounts”

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

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

Passkeys “Yubikey: Passkeys”

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

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

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

Keys & Certificates “Yubikey: Certificates”

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

Public/Private Key Pair

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

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

Certificates / PIV

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

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

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

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

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

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

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

Vortrag: Software-defined vehicle

Schallbert — Sun, 25 Jan 2026 00:00:00 +0000

— Dezember 2025 — Neuer Vortrag veröffentlicht

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

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

Jekyll-dockerimage: Bundler und Gemfile

Schallbert — Fri, 14 Nov 2025 00:00:00 +0000

Was ist bundler?

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

Will ich lokal bauen, so tippe ich beispielsweise

bundle exec jekyll serve --incremental --future

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

bundler in der CI-Pipeline

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

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

Keine Schreibrechte

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

Spezifikationsdatei für bundler

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

Fehlerbehebung

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

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

bundle config set frozen true

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

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

`Gemfile.lock` für verschiedene Umgebungen optimieren

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

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

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

In meiner Lockfile taucht daraufhin folgender Eintrag auf:

nokogiri (1.18.10-x86_64-linux-musl)

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

fail2ban: Update zerstört Konfiguration

Schallbert — Thu, 23 Oct 2025 00:00:00 +0000

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

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

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

schallbert@machine:~# iptables -n -L

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

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

Übersetzt lautet die Ausgabe etwa in etwa

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

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

“fail2ban ERROR Failed during configuration”

Also schaue ich zuerst mal bei Docker nach:

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

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

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

Die Fehlermeldung

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

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

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

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

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

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

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

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

# jail.local update Oct-2025

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

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

Überprüfen der Lösung mittels iptables

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

schallbert@machine:~# iptables -n -L

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

passtdas auf Github

Schallbert — Sun, 14 Sep 2025 00:00:00 +0000

— September 2025 — passtdas zum Download verfügbar

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

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

Link zum Projekt auf Github

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

Schallbert

passtdas - ein Hilfsprogramm für die CNC

Schallbert — Mon, 08 Sep 2025 00:00:00 +0000

Das Problem

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

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

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

Die Lösung

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

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

TODO: ADD VIDEO LINK

Die Software

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

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

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

Dieses Programm wird passtdas heißen.

Programmart

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

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

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

Eingabe

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

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

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

Definition Kreissegmente

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

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

Kommando:

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

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

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

Aber auch so kann ein Kreissegment definiert sein:

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

Kommando:

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

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

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

Extremwerte von Kreissegmenten berechnen

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

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

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

Datentabelle

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

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

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

Ausgabe

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

G90

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

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

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

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

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

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

Test und Verifikation

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

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

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

Open-source software

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

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

Giteas act_runner rootless ausführen

Schallbert — Sun, 10 Aug 2025 00:00:00 +0000

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 00:00:00 +0000

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!

⚠️ Update Oktober 2025

Wird fail2ban auf Services in Docker-Containern angewendet, kann mit der oben genannten Konfiguration des jails Gein Fehler auftreten. Die Behebung habe ich im folgenden Artikel dokumentiert: fail2ban-Fehler “Bad value substitution” for ‘action’

Rate limiter mit Caddy und fail2ban

Schallbert — Thu, 10 Jul 2025 00:00:00 +0000

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.

⚠️ Update Oktober 2025

In Verbindung mit diesem Artikel gibt es ein wichtiges Update, welches den fail2ban Fehler “Bad value substitution” for ‘action’ behebt. Dieses Problem kann auftauchen, wenn fail2ban Services prüfen soll, die in Docker-Containern laufen.

Gitea stürzt ab: Zu viele Anfragen

Schallbert — Mon, 30 Jun 2025 00:00:00 +0000

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 🙂

Repo-Lookout: Sicherheitslücke beheben

Schallbert — Fri, 20 Dec 2024 00:00:00 +0000

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 00:00:00 +0000

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 😃

Giteas act_runner: Startprobleme

Schallbert — Fri, 30 Aug 2024 00:00:00 +0000

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 00:00:00 +0000

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 aufwändiger 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 00:00:00 +0000

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 00:00:00 +0000

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.

CNC Tuning #3

Schallbert — Sat, 04 May 2024 00:00:00 +0000

Dies ist der letzte Teil meiner Reihe über die Optimierung der Fertigungszeit auf CNC-Fräsmaschinen. Er konzentriert sich auf den Pfadinterpreter der CNC-Steuersoftware.

Der Pfadinterpreter der Steuersoftware ist dafür zuständig, die Anweisungen aus dem G-Code zu lesen und in Maschinenbewegungen zu übersetzen. Soll beispielsweise G01 X100 Y200 Z-2.0 F2000 S18000 ausgeführt werden, so muss der Pfadinterpreter die akuelle Position der Maschine kennen und einen Fräsvektor erzeugen, der zur gewünschten Position mit den vorgegebenen Parametern zeigt.

Hierbei muss der Interpreter die kinematischen Parameter der Maschine berücksichtigen: Mit welcher Rampe auf Zielgeschwindigkeit F1000 beschleunigt wird ob der gewünschte Vorschub überhaupt zulässig ist, und ab welchem Punkt wieder gebremst werden muss um den Zielpunkt exakt zu erreichen. Die so gewonnenen Daten werden schließlich in eine Schrittfolge für die drei Schrittmotoren übersetzt, in einen Pufferspeicher geladen und schließlich in Echtzeit an die Motorendstufen ausgegeben.

Schritt 3: Optimierung des Pfadinterpreters

Viele Steuersoftware-Anbieter haben integrierte Fräspfadfilter programmiert, welche mittels Kommando G64 oder per Menü zu konfigurieren sind. Ich verlinke hier mal ein paar Beispiele verschiedener Hersteller, wo für spezifische Details nachgelesen werden kann:

Die Kunst ist nun, eine Konfiguration passend zum Fräsjob und der Maschinenkinematik zu finden. Es geht hier immer um einen Kompromiss zwischen Fertigungsgeschwindigkeit und Bahntoleranz. Soll also mit hohem Vorschub gefahren werden, werden eigentlich spitze Kanten verrundet, verbundene Liniensegmente in einem Toleranzband angefahren oder Pfade so vereinfacht, dass außerhalb der von der Maschine erreichbaren Beschleunigung befindliche Pfadpunkte nicht angefahren werden.

Grundlagen: Was ist “Look Ahead Feed”?

Hiermit ist gemeint, dass der Pfadinterpreter der Steuersoftware sich während des Ausführens einer Fräsoperation - z.B. G01 X* Y* (lineare Bewegung Punkt zu Punkt) - bereits die nächste(n) Operation(en) anschaut und herausfindet, ob und wie stark zwischen den Operationen abgebremst und wieder beschleunigt werden muss bzw. direkt durchgefahren werden kann. Die Physik dahinter erkläre ich im Artikel zum CNC-Setup.

Hierdurch kann teils massiv Zeit gespart werden, der Fräsvorgang wird flüssiger und die Maschine erfährt geringere Belastungen. Zusätzlich zur Vermeidung von Beschleunigungs- und Bremsvorgängen kann mittels Parameter G64 eingestellt werden, ob und wie Fräspfadfilter die geplante Trajektorie verändern dürfen, um weiter auf höhere Bahngeschwindigkeiten zu optimieren.

Ideal im Gravurbetrieb

Im Gravurbetrieb kann man sich solche Optionen hervorragend zu Nutze machen: Höhere Toleranzen sind hier meist OK, und leicht verrundete Kanten oft akzeptabel. Bei 3D-Gravuren dauert das Fräsen durch die vielen Pfade lang, und hier ist besonders viel Zeit herauszuholen.

Da ich Eding CNC benutze, kann ich nur für Parameter dieser Steuerung Tipps geben. Nun aber ab ins Detail zur Erklärung der Einstellungen!

Fräspfadtoleranz `G64 P*`

Dieser Parameter gibt der Steuersoftware die allgemeine Toleranz der Pfadgenauigkeit vor.

Ich habe meine Maschine so eingestellt, dass sie im Gravurbetrieb Abweichungen vom vorgegebenen Fräspfad von bis zu LAF blending tolerance = 0.3mm zulässt. Alternativ kann die Konfiguration per Kommando G64 P0.3 erfolgen. Im Bild habe ich skizziert, wie sich eine solche Einstellung in der Praxis auswirken kann: Der Fräspfad (weiß) besteht aus G01-Liniensegmenten. Die Toleranz ist mit Hilfe von Kreisen eingezeichnet. Der Pfadinterpreter der Steuersoftware kann nun eigenständig Kreissegmente so definieren, dass innerhalb der Toleranz eine möglichst hohe Bahngeschwindigkeit erreicht wird.

Die so ermittelte Bahn (türkis) ähnelt einer Spline-Kurve. Zu beachten ist hier, dass sämtliche Linien von dieser Einstellung betroffen sein können - auch solche, die strenge Toleranzanforderungen haben. Ist dies nicht gewünscht, so sollte hier ein kleinerer Wert verwendet werden.

Pfadverrundung `G64 R*`

Treffen zwei Liniensegmente im Winkel von bis zu LAF full speed blending angle threshold = 12° aufeinander, wird die Maschine ohne abzubremsen versuchen, dem Winkel genau zu folgen. Bei größeren Winkeln wird mit reduzierter Geschwindigkeit mit per G64 P* definierter Toleranz gefahren. Diese Konfiguration wird mit G64 R12 programmiert.

Die Werte hier sind mit großer Vorsicht einzustellen, weil sie zu Beschleunigungsspitzen auf der Maschine führen. Große Werte können Schrittverluste und höheren Verschleiß der CNC-Fräse verursachen. Dafür werden Bahngeschwindigkeit und Genauigkeit optimal gehalten.

Pfadverrundung bei reduziertem Vorschub `G64 S* D*`

Diese Konfiguration gibt der Steuersoftware die Möglichkeit, Kanten bis zum eingestellten Toleranzwert zu verrunden: LAF reduced speed path smoothing delta = 0.001mm. In Kombination mit der Verrundung muss der Winkel eingestellt werden, bis zu dem diese Verrundung durchgeführt werden soll: LAF reduced speed path smoothing angle threshold = 0°.

Programmiert wird diese Funktion am Besten in Kombination mit der Pfadverrundung bei vollem Vorschub als G64 R* S* D*. Der Vorteil hierbei ist, dass Liniensegmenten wie im Bild gezeigt sehr genau gefolgt wird, und die Kanten gleichzeitig aber fein justierbar abgerundet werden. Bis zum über R definierten Winkel wird sogar mit vollem Vorschub dem Pfad exakt gefolgt.

Werden bei S sehr große Winkel eingestellt, so findet entsprechend D auch eine stärkere Verrundung statt. Überschreitet der im Fräsprogramm vorgegebene Winkel jedoch den konfigurierten Wert, so fällt der Algorithmus auf die für P hinterlegten Werte bzw. in den exakten Pfadfolgemodus zurück.

Pfadvereinfachung `G64 Q*`

Enthält die G-Code Datei zahlreiche, sehr kurze Liniensegmente (wie sie oft bei der Erstellung von Pfaden aus Bilddateien entstehen), kann diese Funktion durch Vereinfachen der Fräspfade Abhilfe schaffen. Dabei gibt die Zahl hinter dem Parameter die Toleranz an, bis zu der Liniensegmente zu einer Linie verschmolzen werden.

Diese Einstellung entlastet den Pufferspeicher der Maschine und erhöht gleichzeitig die mittlere Bahngeschwindigkeit. Für den Gravurbetrieb halte ich diese Einstellung insbesondere für interessant, wenn mit “verrauschten” Daten gearbeitet wird und im CAD nicht die Möglichkeit bestand, die Anzahl der Pfade zu reduzieren.

Beschleunigungsfilter `G64 F*`

Mittels diesen Parameters können die durch Look Ahead Feed möglicherweise erzeugten Beschleunigungsspitzen abgemildert werden. Der minimal einzustellende Wert ergibt sich durch den Quotienten aus gewähltem Vorschub für die Operation und maximaler Geschwindigkeit der Maschine.

Beispiel: Fmin = Foperate / Fg00, bei Fg00 = 12000mm/min und Foperate = 5000mmm/min ist Fmin = 0.42

Also wird bei Vorschub von 5000mm/min die maximal mögliche Beschleunigung der Maschine abgerufen und Kurvenradien so eingestellt, dass sie bei konstanter Bahngeschwindigkeit gefahren werden. Alle Werte größer gleich Fmin = 1 sind inherent sicher, unabhängig vom gewählten Vorschub.

Dieser Parameter wurde entwickelt für die Bearbeitung von elastischen Materialien wie Gummi oder Kork, wo eine konstante Vorschubgeschwindigkeit extrem wichtig und die Bahntreue eher zweitrangig ist. Der Parameter wird in Kombination mit G64 R* verwendet. Die folgende Programmierung für das obige Beispiel würde die volle Kapazität der Maschine abrufen: G64 R120 F0.42, wobei mit F5000 gefahren wird, F12000 der Maximalvorschub der Maschine ist und spitze Winkel bis 120° ohne abzubremsen gefahren werden sollen.

Wende ich diese Werte auf meine Maschine an, entsteht das nebenstehende Bild. Hier soll ein Rechteck mit 25 x 100mm Kantenlänge gefertigt werden. Weiß ist wieder die Zieltrajektorie dargestellt. Die türkise Kurve zeigt die durch die Programmierung des Beschleunigungsfilters gefahrene Kurve mit konstanter Bahngeschwindigkeit. Je geringer der Vorschub im Verhältnis zum Maximalvorschub und je höher die Beschleunigung der Maschine eingestellt ist, desto kleiner wird der notwendige Radius.

Für den Gravurbetrieb und das Fräsen fester Materialien wird dieser Parameter meiner Erfahrung nach jedoch nicht verwendet.

Meine Konfiguration für die Hobbyline 4530

Ich habe im Gravurbetrieb viel mit den verschiedenen LAF-Parametern herumgespielt und eine Menge Rohlinge als Lehrgeld “verbraucht”. Die kürzesten Fertigunszeiten erhielt ich bei vorheriger Optimierung der kinematischen Parameter mit folgender Konfiguration:

G64 Q0.3 R12 D0.3 S120

Damit sage ich der Maschine folgendes:

“Verwende den Pfadvorschau-Algorithmus und versuche, kurze Liniensegmente unter 0.3mm Länge zu verschmelzen. Versuche, den Vorschub bei einem Winkel zweier Streckenabschnitte von bis zu 12° nicht herunterzuregeln. Bei größeren Winkeln bis 120° kann statt einem exakten Nachfahren mit bis zu r=0.3mm verrundet werden. Bei noch größeren Winkeln ist dem vorgegebenen Pfad zu folgen und, falls erforderlich, bis zum Stillstand abzubremsen.”

Fazit

Da mich die Parameteroptimierung für den Gravurbetrieb ziemlich weit vom Parametersatz für den normalen Fräsbetrieb weggebracht haben, habe ich mein Steuerprogramm einfach ein zweites Mal installiert.

Dort konnte ich dann Geschwindigkeit, Achsbeschleunigung und Pfadparametrierung getrennt festlegen. Nun habe ich das Beste beider Welten auf einer Maschine zur Verfügung:

Einen sehr genauen, weich operierenden Fräsbetrieb mit folgenden Parametern:

Fmax XY 12000mm/min
Fmax Z 4800mm/min
Amax X 1000mm/s²
Amax Y 1000mm/s²
Amax Z 1000mm/s²
G64 P0.1 R6

Und über die andere Verknüpfung einen überaus flinken Gravurbetrieb:

Fmax XY 12000mm/min
Fmax Z 4800mm/min
Amax X 4000mm/s²
Amax Y 3200mm/s²
Amax Z 1600mm/s²
G64 Q0.3 R12 D0.3 S120

Und wo ist der Beweis?

Das eingebettete Video zeigt dasselbe Gravurprojekt mit vier verschiedenen Optimierungsstufen:

oben links: Herstellerkonfiguration der Maschine, Standard-Fräspfade aus CAD/CAM
oben rechts: Geschwindigkeit und Beschleunigung auf Fräsbetrieb erhöht
unten links: Look Ahead feed eingeschaltet G64 P0.3, Fräspfade im CAM optimiert
unten rechts: Optimiert für Gravurbetrieb wie oben beschrieben, CAM Flyover auf 2mm reduziert und Leerfahrten minimiert

CNC-Tuning für den Gravurbetrieb

CNC Tuning #2

Schallbert — Sat, 27 Apr 2024 00:00:00 +0000

Dies ist der zweite Teil meiner Reihe über die Optimierung der Fertigungszeit auf CNC-Fräsmaschinen. Er konzentriert sich auf die kinematischen Maschinenparameter für den Gravurbetrieb.

Schritt 2: Tuning der kinematischen Parameter der CNC

Die theoretischen Grundlagen habe ich im Artikel zur CNC-Steuerungskonfiguration ausführlich erläutert. Meine Probleme damit und zugehörige Lösungen habe ich nach vielen Tests und Rücksprache mit dem Hersteller im Fazit zu einem Jahr CNC-Betrieb festgehalten. Die folgenden Abschnitte wenden die obigen Erkenntnisse auf eine Demonstrationsmaschine an, die ich mir habe leihen können.

Verfahrgeschwindigkeit im Eilgang

Für die Demomaschine konnte ich die Geschwindigkeit im Eilgang von den vorgeschlagenen Fxy = 4m/min und Fz = 2.4m/min auf Fxy = 12m/min und Fz = 4.8m/min erhöhen. Setze ich alle drei Achsen gleichzeitig in Bewegung, erhalte ich durch Steigung der Kugelgewindespindeln und Mikroschrittkonfiguration (8 pro Vollschritt) der Motoren eine kombinierte Schrittfrequenz von 96kHz, was unter der maximalen Schrittfrequenz von 125kHz der Steuerung liegt.

Beschleunigung im Eilgang

Die Herstellerangaben empfehlen hier aXY = 300mm/s² und aZ = 200mm/s².

Ich habe die Beschleunigung in mehreren Schritten hochgesetzt und bin in einer ersten Runde bei aXY = 1000mm/s² und aZ = 400mm/s² gelandet. Diese Werte sind für diese kleine und leichte Maschine mit nur 30x45x14cm Verfahrweg nach meiner Erfahrung für den Normalbetrieb ohne Weiteres möglich. Sie erhöhen die Fertigungsgeschwindigkeit stark, denn jeder Richtungswechsel, auch die im Materialeingriff bei G01, G02, G03, werden nun um Faktor 3 bzw. 2.5 schneller ausgeführt.

So habe ich die Maschine oft betrieben und auch auf der Messe bin ich mit diesen Werten stabil und sicher gefahren. Das folgende Video zeigt die Fräse im Gravurbetrieb mit den angegebenen Werten.

CNC-Tuning: Vorschau

Danach jedoch wollte ich wissen, wie weit ich es treiben kann. Getreu dem vorher beschriebenen Motto

“Wer die Grenze nicht überschreitet, weiß nicht, wo sie liegt”

habe ich erst einmal geprüft, wie sich massive Schrittverluste bei dieser Maschine anhören. Also habe ich eine Achse mit einem Holzbalken blockiert und bin vorsichtig dagegen gefahren:

Your browser does not support the video tag.

Massive step loss soundcheck

Das deutlich vernehmbare Rattern entsteht wenn der Motorhochlauf zwar klappt, in Richtung Zielgeschwindigkeit aber diverse Vollschritte verloren gehen. Wird der Rotor bereits bei Anlauf des Motors “verloren”, so fiept der Motor nur noch, ohne die Achse überhaupt in Bewegung zu setzen. Verliert der Motor nur wenige Schritte, befindet sich aber auf Zielgeschwindigkeit, so gibt es einen rauen und unter Umständen kratzenden Ton.

Ich habe für das Experiment die X-Achse gewählt, weil sie sich am einfachsten blockieren lässt. Des Weiteren habe ich sie in X+-Richtung blockiert. Begründung: diese Maschine besitzt kein professionelles Festlager zur Aufnahme von Druck- und Zugkräften der Kugelumlaufspindel. Stattdessen werden Druckkräfte in Richtung Schrittmotor sicher von einem auf der Spindel montierten Flansch abgefangen, der gegen in der Portalwange befindliche Kugellager drückt.

Zugkräfte hingegen werden hauptsächlich von den Motorlagern aufgenommen - da wollte ich kein Risiko eingehen. Nun ist also das Geräusch bei plötzlichem und ruckartigen Schrittverlust bekannt - das Übertakten kann beginnen!

Meine Vorgehensweise:

Die Beschleunigung einer Achse der Maschine verdoppeln
Die betreffende Achse umher joggen, dabei auf merkwürdige Geräusche achten und die Achsbewegung beobachten
Vorige Schritte wiederholen, bis massive Schrittverluste auftreten
Beschleunigung auf den Mittelwert zwischen “klappt” und “klappt nicht” zurückfahren
Den vorigen Schritt solange wiederholen, bis die Maschine sauber fährt
Alle Schritte auch für die anderen Achsen durchführen

So bin ich schließlich bei für eine solche Hobbymaschine unglaublichen aXY = 4000mm/s², aZ = 1600mm/s² gelandet. Dies liegt nun eine Größenordnung über den empfohlenen Werten.

Die kleine Fräse scheint auch hier stabil zu laufen und die gefertigten Gravuren sehen gut aus. Allerdings konnte ich mir nicht vorstellen, dass ich Schrittmotoren, Treiberstufen und Netzteil noch innerhalb ihrer Spezifikation betreibe. Daher habe ich gemessen.

Elektrische Messwerte

Das Netzteil ist mit 3.7A bei 36V angegeben. Ich darf diesen Wert also in der Summe weder im Eilgang G00 noch im Materialeingriff dauerhaft überschreiten. Wie oben erklärt, ist der Eilgang im Gravurbetrieb durch die geringeren Fräskräfte maßgeblich, sodass ich besonderes Augenmerk auf das Verfahren mehrerer Achsen gleichzeitig legen muss.

Die Motoren können je einen Dauerstrom von 3.0A verkraften, limitieren mir hier also nichts. In den elektrischen Tests schaue ich lediglich, ob ich mit der Energieaufnahme des Systems im Rahmen bleibe.

Messaufbau

Ich schließe das aus diesem Artikel bekannte Multimeter direkt am Ausgang des Netzteils an und nehme Spannung und Strom auf. Für das Experiment simuliere ich die Fertigung der oben im Video verlinkten Gravur und führe in zwei Durchläufen zuerst eine zeitlich grob aufgelöste Leistungsfaktoranalyse (2Hz) durch, gefolgt von einer fein aufgelösten Stromermittlung mit 20kHz.

Ergebnisse

Im obigen Bild sind Spannung, Strom, Wirk- und Blindleistung aufgetragen. Zu erkennen ist, dass die Blindleistung (grün) immer dann kurze Spitzen zeigt, wenn mehrere Achsen gleichzeitig in den Eilgang beschleunigen. Die Leistungsaufnahme einer Achse im Eingriff G01/G02/G03, blau beträgt im Schnitt etwa 45W und ist ähnlich hoch wie bei der Konstantfahrt im Eilgang.

Das Netzteil ist in der Lage, die Spannung (orange) ziemlich konstant zu halten und knickt selbst unter Volllast nur um knapp 0.2V ein. Einzig der Stromwert sah mir etwas zu glatt aus. Ich vermutete an dieser Stelle, dass die zeitliche Auflösung zu gering ist und beschloss, das Experiment mit Konzentration auf den Strom zu wiederholen.

Und tatsächlich. Die höhere zeitliche Auflösung zeigt, dass die Stromaufnahme bei Beschleunigung mehrerer Achsen Spitzen zeigt, die über den bereits bekannten Werten liegt.

Hier stechen Bewegungen auf der Y-Achse, welche das gesamte Portal in Bewegung setzen muss, besonders heraus. Und zwar genau dann, wenn die anderen Achsen noch in Bewegung sind oder gerade gehalten haben. Dies hängt mit den Schrittmotortreibern zusammen. Sie betreiben die Motoren nämlich noch etwa 0.5s nach Anhalten bei vollem Strom weiter. Die dadurch entstehende Überlagerung lässt die Spitzen noch dramatischer aussehen.

Benchmark Spitzenlast

Na dann treiben wir es mal auf die Spitze mit einem Beschleunigungs-Benchmark. Wird das Netzteil auch bei voller Last unter Beschleunigung aller Motoren gleichzeitig die Ausgangsspannung halten können?

Um dies zu testen, habe ich einen G-Code geschrieben, der alle Achsen gleichzeitig auf Höchstgeschwindigkeit beschleunigen und dann wieder abbremsen lässt. Anschließend wird unter gleichen Bedingungen zum Ausgangspunkt zurückgefahren und das Ganze wiederholt.

Auf diese Weise kann ich herausfinden, ob das Netzteil genügend Reserven hat, um Lastspitzen abzufangen und gleichzeitig schauen, ob die Motoren bereits im größeren Maße Schritte verlieren. Im Mittel liegt hier die aufgebrachte Leistung bei 95W und die Versorgungsspannung sinkt um 0.28V auf 35.72V ab. Dabei muss das Netzteil in der Spitze 5.14A abgeben, was knapp 40% über Nennstrom liegt.

Your browser does not support the video tag.

Benchmark

Hört man ganz genau hin, so klingt die Maschine direkt zu Beginn des Benchmarks etwas rau, fängt sich dann aber. So können auch Schrittverluste klingen. Es ist daher sehr wichtig, die Maschine mit allen Sinnen zu überwachen.

Mechanische Prüfung

Nun zur letzten Prüfung: Ich gebe beim Eilgang-Benchmark zusätzlich Last auf die Achsen, indem ich während des Programmablaufes mit meinem Arm an der jeweiligen Achse ziehe. Die Achsen Z und X laufen stabil weiter. Bei der Portalachse Y merke ich jedoch, dass die Maschine nun anders klingt. Irgendwie rau, als würde man mit mit einer Raspel leicht über eine Holzplatte ziehen.

Lege ich eine große Last an, so fährt der Schrittmotor auf dieser Achse nicht mal mehr an, sondern fiept nur noch. Er kann den Pulsen der Endstufe nicht mehr folgen. Ich reduziere nun also die Beschleunigung schrittweise, bis der Motor die Portalachse auch unter mittlerer Last wiederholbar und ohne hörbare Schrittverluste beschleunigen kann. Hier lande ich am Ende bei immer noch flinken [aX = 4000mm/s² aY = 3200mm/s² aZ = 1600mm/s²].

In einem letzten Schritt führe ich nach fünfmaliger Wiederholung des Benchmarks eine weitere Referenzfahrt durch und schaue mir die Logs der Steuersoftware an. Alle Achsen sind nun unauffällig hinsichtlich Schrittverlusten.

Appelle zum CNC-Tuning

Bitte geht beim Tuning eurer Maschine behutsam vor. Lernt sie richtig kennen, bevor ihr damit beginnt. Hört genau hin und optimiert Achse für Achse nacheinander. Nehmt euch Zeit für Tests, Prüfungen und Experimente.

Selbst wenn ihr eine sehr ähnliche Maschine wie meine besitzt, machen andere Abmessungen bereits einen riesigen Unterschied hinsichtlich Steifigkeit und damit auch möglicher Verfahrgeschwindigkeit bzw. Beschleunigung. Sogar Wartungszustand, leichtgängigere Wellen, andere Führungen o.Ä. können dazu führen, dass ihr am Ende mit anderen Werten fahrt als ich.

Es wird kein Profi-Equipment benötigt, um die Grenzen der Maschine auszuloten. Nicht einmal eine Messuhr, da Schrittverluste auch mit Hilfe der Referenzschalter hinreichend genau bestimmt werden können.

Alles was ich durch die elektrischen Messungen oben festgestellt habe, ist, dass der Hersteller bei der Auslegung der Maschine sauber gearbeitet hat und keine Komponente unterdimensioniert ist. Im Gegenteil, diese Maschine ist für die Übertaktung bestens geeignet.

Und nun weiter zum letzten Teil 3: Pfadinterpreter optimieren.

CNC Tuning #1

Schallbert — Sat, 20 Apr 2024 00:00:00 +0000

Dies ist der erste Teil meiner Reihe über die Optimierung der Fertigungszeit auf CNC-Fräsmaschinen. Er konzentriert sich auf den Einsatz von CAD- und CAM-Werkzeugen zur Erzeugung effizienteren G-Codes.

Es gibt diverse Maßnahmen zur Reduktion der Fertigungszeit mit einer CNC-Maschine. Erstmal jedoch sollte beleuchtet werden, warum so etwas gewünscht ist und welche möglichen Nachteile sich hierdurch ergeben.

Warum überhaupt?

Aus kaufmännischer Sicht sorgen geringere Fertigungszeiten für einen höheren Teiledurchsatz und ermöglichen damit einen höheren Umsatz in einer gegebenen Zeitspanne. Zudem ist die Investition der Maschine schneller amortisiert.

Als Hobbyist sind kürzere Fertigungszeiten vor allem dann interessant, wenn das Ziel die Herstellung sehr komplexer Geometrien oder die 3D-Fertigung ist. Hier können Fräszeiten durchaus mehrere Stunden betragen und die möglichen Einsparungen sind folglich besonders groß.

Bei mir steht wie auch in der Lehre der wissenschaftliche Gedanke im Vordergrund: Ich will herauszufinden, wo die Grenze der Maschine liegt. Ich möchte wissen, warum sie dort liegt. Ich werde versuchen, sie stabil innerhalb ihrer Grenzen zu betreiben. Dabei ist der Verschleiß unter Kontrolle zu halten.

Um diese Grenze jedoch genau zu kennen, muss sie zuerst übertreten werden. Woher sonst soll ich wissen, wo sie sich befindet?

Was sind mögliche Nachteile?

Bestimmte Komponenten einer “übertakteten” Maschine könnten schneller als üblich verschleißen. Dazu zählen etwa Netzteile und Motor-Endstufen, die höhere transiente Ströme verkraften müssen. Lager und Führungen werden durch höhere Beschleunigungen stärker beansprucht. Umlaufspindeln und Maschinenrahmen müssen die dadurch resultierenden, stärkeren und schneller wechselnden Kräfte und Vibrationen aufnehmen und können früher Ermüdungserscheinungen oder sich lösende Verbindungen aufweisen.

Bei der Ermittlung der Grenzen kann die Maschine im Extremfall sogar beschädigt werden: Mit hoher Wahrscheinlichkeit treten jenseits der Grenze Schrittverluste¹ auf. Das ist zwar im Testbetrieb nicht weiter problematisch. Doch stimmt die angenommene Position dann nicht mehr mit der tatsächlichen Position überein und es besteht das Risiko des “Crashes” - wenn nicht mit Bedacht vorgegangen wird. Hier noch ein ziemlich gutes Youtube-Video von gammaflow zum Thema Schrittverluste vermeiden.

Werden die Fräsbahnen im CAD oder CAM zugunsten kürzerer Fertigungszeiten verändert, so kann dies außerdem negative Auswirkungen auf Schnitt-, Kanten- und Oberflächenqualität haben.

Bei der Optimierung des Pfadinterpreters der Steuersoftware ist ebenfalls ein Kompromiss einzugehen: Höhere Fertigungsgeschwindigkeit wird hier mit geringerer Genauigkeit und/oder höherem Maschinenverschleiß eingekauft.

Welche Maßnahmen werden nicht diskutiert?

Nicht betrachten werde ich hier die Optimierung von Vorschub F und Drehzahl S des gewählten Fräsers im Eingriff. Diese Parameter hängen vom zu bearbeitendem Material, der Fräsergeometrie, den Fähigkeiten der Maschine und dem Mut des Bedienpersonals ab, sodass ich keine allgemein gültigen Tunings vorschlagen kann.

Einen anderen, großen Einflussfaktor muss ich hier ebenfalls ausklammern: Die Bearbeitungsstrategie des CAM-Programms bezogen auf Eilgänge. Mein CAM-Programm lässt mich da nicht besonders tief eingreifen, sodass ich für die Optimierung der letzten paar Prozent Fertigungszeit stets von Hand im G-Code arbeiten muss, was entsprechend fehleranfällig ist.

Tuning in drei Schritten

Bei meiner Optimierung bin ich in drei Schritten vorgegangen, die allerdings unabhängig voneinander umgesetzt werden können. Jeder Schritt hat mir hierbei deutlich spürbare Verbesserungen gebracht. Dieser Artikel konzentriert sich aus mehreren Gründen auf den Gravurbetrieb:

Gravuren erlauben meist größere Toleranzen als andere Betriebsarten. Dadurch kann stärker verrundet werden, was zu geringeren Beschleunigungen führt. Dies ermöglicht im Mittel größere Vorschübe
Die zu erwartenden Fräskräfte sind geringer: Keine Durchfräsungen, kaum Energieeinsatz bei der Spanverdrängung, kleineres Spanvolumen als bei Schaftfräsern
Dadurch kann die Maschine näher an ihren mechanischen und elektrischen Grenzen betrieben werden
Durch im Schnitt größere G-Code Dateien mehr Optimierungspotential

Schritt 1: Besserer G-Code

Dieser Abschnitt folgt dem Credo Garbage in, Garbage out. Will heißen: Wenn mein G-Code schon schlecht ist, kann die Maschine niemals optimale Fertigungszeiten erreichen. Was zeichnet also “schlechten” G-Code in Bezug auf Fertigungszeit aus?

übermäßig komplex und lang, möglicherweise Dateigröße im Megabyte-Bereich
extrem viele Stützpunkte und eine Menge kurzer Liniensegmente
Einen Haufen “Leerfahrten” im Eilgang auf XY mit hochgezogener Z-Achse
Viele Rückzüge der Z-Achse auf Sicherheitshöhe
Häufige Wartezeiten der Maschine (Spindelhochlauf, Kühlmittelpumpe, Controller-Puffer voll)
Übermäßiges Feinstschlichten auch bei B-Oberflächen

Aber wie soll ich meinen G-Code vereinfachen?

Kurze Frage, lange Antwort: Es fängt im CAD an und hört möglicherweise im CAM nicht auf.

Beispiel CAD

Nehmen wir an, wir möchten eine Schrift fräsen. Unser CAD-Programm hat auch einen Haufen toller Schriftarten dazu. Wir erzeugen nun eine DXF-Datei für’s CAM. Im CAM dann sehen wir plötzlich beim Hineinzoomen, dass alle Buchstaben aus sehr kurzen Liniensegmenten bestehen statt aus Kreissegmenten oder Splines. Die Folge: Das CAM wird G01-Bewegungen, also “Linear Moves” bzw. eine Aneinanderreihung von Strecken erzeugen.

Die verbundenen Strecken machen sehr viele Richtungswechsel der Maschine erforderlich. Folglich muss sie vor dem Verbindungspunkt ständig abbremsen und danach wieder beschleunigen. Die Maschine kann also nicht mit konstanter Geschwindigkeit fahren, denn das würde eine unendliche Beschleunigung am Knickpunkt erfordern.

Für dieses Problem gibt es Lösungen, die im Idealfall gemeinsam angewendet werden:

Im CAD-Programm einstellen, dass wann immer möglich Splines oder Kurven statt Liniensegmenten erstellt werden sollen
Vereinfachung der Zeichnung durch Reduktion der Stützstellen
Vermehrte Nutzung von Radien und Splines an Kanten, Vermeidung von Winkeln

In meinem Falle war die erste Option nicht verfügbar, sodass ich nun ein anderes Programm für die Gravur von Schriften verwende als für meine üblichen Zeichnungen. Dadurch kann ich Schrift jetzt in Linien- und Bogensegmenten ausdrücken. Die dafür erforderliche Fräszeit halbiert sich und gleichzeitig kommt der G-Code mit weniger Zeilen aus. Außerdem wird die Schrift runder und hält sich sogar noch genauer an die anfangs gewählte Schriftart.

Gute Beispiele für die Vereinfachung von Pfaden durch Reduktion von Stützpunkten liefern Gimp und Inkscape - für Inkscape habe ich das sogar bereits meinem Artikel zum Thema Bild-zu-Pfad-Konversion gezeigt. Mit ein paar wenigen Klicks erhält man auf Kosten der Genauigkeit Zeichnungsdaten, die teils deutlich schneller zu fertigen sind.

Da ein Schaftfräser sowieso keine Tasche mit r=0 in den Ecken fertigen kann, habe ich mir angewöhnt, sämtliche Ecken und Kanten im CAD abzurunden. Nicht nur liegen so hergestellte Teile besser in der Hand, sie sind außerdem schneller zu fertigen - die Zeitersparnis summiert sich, besonders auf langsamen und trägen Maschinen.

Beispiel CAM

Im CAM kann ich durch vermehrte Verwendung von Anfahrpunkten und Rampen ein wenig Zeit sparen. Ich lege sie zumeist an das kürzeste Liniensegment und spare so einen Brems/Beschleunigungsvorgang. Bei der Eintauchart ist der Vorteil von “Rampe” gegenüber “Helix”, dass sämtliche Wege des Fräsers Nutzwege sind und ich ohne zusätzliche Achsbeschleunigungen durchfahren kann. Je nach Rampensteigung allerdings verlängert sich der Fräspfad, da Überlappungen entstehen.

Einen viel größeren Effekt auf die Fertigungszeit hat die kluge Auswahl von Räumzustellungen und -strategien für Taschen passend zu Material, Fräser und gewünschter Oberflächengüte. So erzeugt Wirbelfräsen (Trochoidalfräsen²) in vielen Fällen längere Dateien und kostet auf der Maschine mehr Zeit als der klassische “Rasenmäher”, welcher die Tasche bloß abzeilt. Für die Räumzustellung wähle ich bei Materialien wie Holz und Acrylglas gern große Werte über 60% - es sei denn, der Boden der Tasche muss besonders hohen Qualitätsansprüchen genügen.

Für Gravuren ist es meiner Meinung nach oft am Schnellsten, auf einen Räumgang mit einem zweiten Fräser zu verzichten und wenn möglich einen Gravurfräser mit abgeflachter Spitze - ähnlich derer für meine Tests mit Dibond - zu verwenden. Dieser benötigt zum Räumen zwar länger; das kann ich durch gesteigerte Gravurtiefe und eine recht breite Abflachung von 1.5mm aber kompensieren. Ich verwende bei einem solchen Fräser eine Räumzustellung in XY von 1mm. Übrig bleibt schließlich der Zeitvorteil durch weniger Werkzeugwechsel.

Aber wie soll ich die Leerfahrten reduzieren?

Endlich mal ein paar knackig-kurze Antworten:

Geringere Rückzugshöhe in Z (ich verwende 5mm aber 2mm würde bei mir wahrscheinlich auch funktionieren)
Optimierung der Frässtrategie im CAM auf “minimale Wege”
Bei Nesting: Darauf achten, dass die Geometrie möglichst nicht Zeile für Zeile, sondern Teil für Teil gefertigt wird.
Im Zweifel Optimierung der Strategie im G-Code von Hand. Lohnt sich dann, wenn das CAM-Programm nicht gut genug arbeiten kann und viele Gleichteile zu fertigen sind

Und wo ist das Problem mit Rückzügen der Z-Achse?

Rückzüge finden vor allem im Gravurbetrieb sehr häufig statt
der Zeitverlust summiert sich
Beim Wiedereingriff wird meist nicht im Eilgang sondern mit für den Fräser vorgesehener Geschwindigkeit mit G01 auf das Material gefahren

Eine Verbesserung kann hier eine gute Planung der Fräsreihenfolge im CAM bringen. Möglichst viele Sektionen sollten verbunden und ohne Absetzen des Fräsers gefertigt werden. Im CAM sollte für Rückzug und Wiedereinfahrt in Z der Eilgang verwendet werden.

Wie reduziere ich Wartezeiten?

Mit Kühlschmierstoffschaltvorgängen, Wechsel der Spindeldrehzahl oder des Werkzeugs sind Wartezeiten verbunden, die meist leicht zu reduzieren sind:

Kühlschmierstoffförderung durchlaufen lassen während des Programmablaufes
die Verwendung möglichst weniger Werkzeuge bei gleichbleibender Drehzahl für ein Produkt
Anschläge verwenden, um die Maschinenbeschickung zu vereinfachen und Nullpunkte nicht immer wieder neu setzen zu müssen
Wird die Maschine mit komplett verschiedenen parametern für Gravur- und Fräsbetrieb gefahren, empfiehlt sich die doppelte Installation der Steuersoftware mit jeweils passenden Parametersätzen. Dadurch entfällt das ständige Ändern der Konfiguration.

Weiter geht es in Teil 2: Kinematische Parameter hochdrehen.

Schrittverluste treten dann auf, wenn die Achse eines Schrittmotors nicht mehr synchron mit der durch die Steuerung vorgegebenen Schrittfolge dreht, sondern weniger bzw. mehr Schritte zurücklegt als vorgegeben. Fast immer ist die Ursache eines Schrittverlustes in einer unzureichenden Auslegung des Systems (z.B. zu geringe oder instabile Versorgungsspannung, zu schwache oder nicht an den Motor angepasste Endstufen) oder einer Überlastung des Schrittmotors zu finden. Selten jedoch können Schrittverluste Symptome von Defekten sein wie Lagerfraß, Windungsschluss oder durchschlagene Pufferkondensatoren. ↩︎
Das Trochoidalfräsen ist keine schlechte Praxis. Es hat andere Stärken, ist im Gravurrbetrieb aber nur selten von Nutzen. ↩︎

'redir' im Caddyserver

Schallbert — Tue, 30 Jan 2024 00:00:00 +0000

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 00:00:00 +0000

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 00:00:00 +0000

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.

Update Aug-2024

Irgendwann fragte ich mich, ob fail2ban auch tatsächlich auf den iptables meines Servers arbeitet oder nur innerhalb des Containers korrekt funktioniert. Zum Glück war ich nicht der Erste mit dieser Frage (stackoverflow) und fand die vorgeschlagene Lösung ganz charmant:

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

Update Jul-2025

Ich habe jetzt eine Lösung für Gitea, aber auch alle anderen meiner Websites zustande gebracht:

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 00:00:00 +0000

Das Problem

Jetzt bin ich nach ewigem Probieren nun endlich in der Lage, meinem Caddyserver die gebauten Dateien per Docker-Volume zur Verfügung zu stellen. Leider sieht die Seite aber wie folgt aus:

Die Analyse

Zuerst hatte ich den Webserver in Verdacht. Wenn ich die Website aber testweise in meinem Browser aufrufe¹, zeigt sich dasselbe Verhalten. Merkwürdig.

Offensichtlich fehlen sämtliche Stylesheets. Sieht man genau hin, sind aber auch Bilder und andere Medien nicht geladen worden, sondern lediglich ihre Beschreibung. Dann klicke ich wild auf ein paar Links zu Artikeln und Unterseiten. Dabei fällt auf, dass die Pfade anders aussehen, als ich erwartet hätte:

# --- Erwartung ---
# Bilddatei
/assets/images/test.jpg
# Artikel
/this-is-a-post

Stattdessen sehe ich:

# --- Beobachtung ---
# Bilddatei
/pages/<username>/<repositoryname>/assets/images/test.jpg
# Artikel
/pages/<username>/<repositoryname>/this-is-a-post

Dies zeigen auch die mit F12 zugeschalteten Entwickleroptionen des Browsers (siehe Bild oben): sämtliche per relativen Link eingebundene Quellen können nicht geladen werden. Übrigens ist es im Allgemeinen eine klare Empfehlung, die Entwickleroptionen bei Problemen mit der Darstellung von Webseiten aktiviert zu haben.

Liegt ja irgendwie nahe, dass meine Jekyll-Konfigurationsdatei _config.yml oder meine Übersetzungsheader i10.yml Fehler enthalten. Dafür gibt es zum Glück bereits hervorragende Hilfeseiten.

Ein Test zeigt jedoch schnell, dass ich die Angabe repository, woher der Build <username>/<repositoryname> herbezieht, nicht einfach leer lassen kann:

# bundle exec jekyll serve
Generating... 
 Jekyll Feed: Generating feed for posts
 Liquid Exception: No repo name found. 
 Specify using PAGES_REPO_NWO environment variables, 'repository' in your configuration, 
 or set up an 'origin' git remote pointing to your github.com repository. in /_layouts/default.html
 ERROR: YOUR SITE COULD NOT BE BUILT

Und, verflixt, wo kommt der Unterordner /pages plötzlich her?

Die Lösung

Durch das /pages im Pfad liegt die Vermutung nahe, dass die Ursache in einer Kombination aus Jekyll-Bauoptionen und dem Github-Pages Gem zu finden ist.

Natürlich bin ich mit diesem Problem nicht allein, und nach längerer Recherche finde ich tatsächlich eine Dokumentation der Lösung.

Also ändere ich die Umgebungsvariable JEKYLL_ENV (steht für die Bauumgebung) von production auf development, so wie es normalerweise für das lokale Bauen vorgesehen ist.

# workflows/jekyll-build-action.yml
env:
 JEKYLL_ENV: development # I had "production" here before

Und, was soll ich sagen: Kaum macht man es richtig, schon funktioniert’s!

Die Website offline darstellen funktioniert wie folgt: Die gebauten Dateien (den _site-Ordner) auf den eigenen Rechner ziehen und die index.html mit dem Browser öffnen. ↩︎

🗸 Gitea Actions Teil2 - Jekyll-Dockerimage

Schallbert — Sat, 09 Dec 2023 00:00:00 +0000

Die Vorgeschichte

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

“Set up job”

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

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

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

bundle install

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

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

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

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

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

act_runner: Kein Schreibzugriff auf `Gemfile.lock`

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

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

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

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

Update Nov-2025

Nach einem Update meiner lokalen Bildumgebung per bundle update stellt sich bei mir nun erneut das oben genannte Problem, obwohl ich Gemfile.lock inzwischen versioniere. Die Lösung diskutiere ich in einem Artikel zum Thema Bundler

Abhängigkeiten: `sass-embedded`

Nach weniger als 20 Sekunden die nächste Fehlermeldung:

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

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

Nun endlich läuft bundle install erfolgreich durch:

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

jekyll build

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

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

Und jetzt direkt nochmal probieren, ob Jekyll erfolgreich baut:

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

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

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

Artefakte transferieren

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

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

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

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

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

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

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

Aber man kann doch `upload-artifact` verwenden!

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

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

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

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

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

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

Sackgasse.

Auch Docker `cp` funktioniert in diesem Falle nicht

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

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

Dies schlägt wieder fehl:

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

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

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

Transferieren per SFTP würde klappen

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

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

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

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

Dem Action-Container ein Volume zur Verfügung stellen

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

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

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

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

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

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

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

und schon schlägt die Aktion wieder fehl:

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

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

OK, also schnell der Action hinzugefügt:

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

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

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

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

# runner/config.yml

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

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

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

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

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

Und endlich:

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

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

Noch ein letzter Tipp

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

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

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

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

🗙 Gitea Actions - Jekyll Workflow

Schallbert — Thu, 30 Nov 2023 00:00:00 +0000

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

Gewünschter Ablauf

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

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

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

Ausgangspunkt: Github Actions

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

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

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

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

Probleme mit der Ruby-Installation

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

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

Na, das ist doch mal eine hilfreiche Fehlermeldung!

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

Möglichkeiten zur Fehlerbehebung

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

Den Runner mit Ubuntu22 statt Node16 betreiben

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

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

Den Runner direkt auf der Hostmaschine (Ubuntu22) laufen lassen

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

Gitea act_runner direkt auf dem Host laufen lassen

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

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

Ruby im Cache vorinstallieren

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

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

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

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

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

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

Probleme mit prebuilt-Ruby

Das Log zeigt das Problem:

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

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

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

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

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

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

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

Noch immer Fehler beim Bauen mit dem Github-Acitons script

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

💬 ::debug::isExplicit: 3.1.4

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

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

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

Update Jan-2024

Es es gibt zwei weitere Möglichkeiten dafür, dass der toolcache nicht gefunden wird:

Ich habe das Volume nicht der Action, sondern dem Runner zur Verfügung gestellt. Ich bin mir nicht sicher, dass die Daten auch in der Action verfügbar sind.
Der toolcache-Pfad ist nicht in der Konfigurationsdatei des runners unter dem Eintrag valid_volumes enthalten. Eine pull request Kommunikation lässt mich jedoch vermuten, dass dies automatisch passiert. Dennoch bin ich mir nicht 100% sicher, ob die Information noch dem Stand der Dinge entspricht.

Docker volume überprüfen

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

docker exec -it <containerID> bash

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

Misserfolg anerkennen

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

einen anderen Ansatz.

Problemursache

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

Mehrsprachige Webseiten - l10n

Schallbert — Tue, 14 Nov 2023 00:00:00 +0000

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.

Update: Alternativ kann man der Überschrift auch eine sprachunabhängige “ID” geben, sodass auch hier die Anchor-Links auf die Überschriften identisch bleiben. Beispiel: ## Umstrukturierung der Website {# website-restructuring}, Aufruf im Link per #website-restucturing.

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

Sprachauswahl

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

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

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

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

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

Veröffentlichung

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

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

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

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

Github Actions: Fehler beheben

Schallbert — Tue, 14 Feb 2023 00:00:00 +0000

Motivation

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

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

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

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

Alles klar, aber warum ein extra Blogeintrag?

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

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

Das Script

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

Die sogenannte “Workflowdatei” sieht so aus:

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

name: python_integrate

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

permissions:
 contents: read

jobs:
 build:

 runs-on: ubuntu-latest

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

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

Github Action runner Fehlermeldungen

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

Ordner nicht vorhanden?

Output:

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

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

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

YAML Syntaxfehler

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

Fehler: Pfad-nicht-gefunden

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

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

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

Aber auch hier gab es Probleme mit Pyinstaller auf Github.

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

Tkinter headless

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

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

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

Ausschnitt:

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

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

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

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

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

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

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

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

QR-codengrave V1.1 / V1.2

Schallbert — Sun, 12 Feb 2023 00:00:00 +0000

Kurze Fakten des Updates

Schnellerer Gravuralgorithmus und -Pfadoptimierung
Diverse Bugfixes
Bedienbarkeit verbessert

Demo Video

QR-codengrave Quick Demo

Version 1.1

Algoritmusoptimierung

Die Zeilen des QR-Codes werden nun horizontal eingelesen
Die Ausgabe der Pfade verläuft nun “rechts nach links”, danach “links nach rechts” und reduziert damit Maschinenbewegungen
Linien werden Punkten vorgezogen, da sie schneller gefertigt werden können
Linien werden nun vertikal und horizontal berechnet, die längere Linie bekommt den Vorzug
Eilgänge werden nun per XY-Vektor gefahren und nicht mehr nur eindimensional, was Zeit spart
Der neue Pfadalgorithmus benötigt 20% weniger Maschinenzeit

Bugfixes

Bei nicht vorliegendem Datensatz Persistence.dat wird das Startbild nicht angezeigt (qruwu.jpg)
Crash bei Klick auf Stop Draw wenn zuvor keine Zeichnung angefragt wurde
Crash bei Hinzufügen eines Werkzeuges bei leerer Werkzeugliste
Wird das Programm ohne Werkzeugauswahl gestartet, ist das dropdown-Menü gesperrt
Fehler in der QR-Code Größenschätzung
Fehler in der Blockbreitenberechnung bei Verwendung von V-Fräsern
Das gegenwärtig ausgewählte Werkzeug wird bei Start der Anwendung nicht im Dropdown-Feld angezeigt
QR-codes können größer dargestellt werden der Anzeigebereich

Bedienbarkeit

Default Werkzeugname geändert von name nach default zur besseren Verständlichkeit
Fräser mit geraden Schneiden (also kein V-cut) ist jetzt das Standardwerkzeug
Erstellen eines Offsets für den XY-Nullpunkt ist jetzt intuitiver gelöst (Y- nach unten, X+ nach Rechts)

Version 1.2

Kleine Änderungen zu 1.1, am Wichtigsten die Behebung eines Bugs, bei dem die Aufforderung zum Werkzeugwechsel verloren gehen kann. Außerdem werden die Winkel von V-Fräsern jetzt bei Berechnung von Pixelbreite und Größe der QR-Codes mit einbezogen.

Bugfixes

Werkzeugauswahl Tx und Werkzeugwechselkommando M06 befinden sich nun in derselben Zeile G-Code wie üblich und können so wie gewünscht Makros auslösen.
Das beim letzten Speichern verwendete Werkzeug wird nicht angezeigt, stattdessen das erste Werkzeug der Liste
Programmabsturz wenn versucht wird, den Jobstatus zu aktualisieren obwohl keine Gravurparameter vorliegen

Bedienbarkeit

Versionsnummer als Kommentar in G-code hinzugefügt
Prefix qr_ der Zieldatei im Datei-Speichern-Dialog hinzugefügt
Genauigkeit der Maschinenzeitabschätzung verbessert

Download

Der aktuelle Release ist hier zum Download verfügbar. Das Programm ist für die private Anwendung sowie Schulungszwecke kostenlos. Für weitere Informationen und Projektdokumentation stehen die readme sowie eine Projektseite zur freien Verfügung.

Upgrade von einer früheren Version

Es wird empfohlen, die Persistenzdatei von der alten Version in die neue Version zu übernehmen. Auf diese Weise werden gespeicherte Werkzeuglisten, Gravurparameter und XY-Offsets portiert. Und so geht’s:

Wechseln Sie in den Ordner, wo sich das QR-codengrave Programm befindet. Anschließend navigieren Sie zu src/assets.
Kopieren Sie die Datei Persistence.dat in einen temporären Ordner oder z.B. auf Ihren Desktop.
Entfernen Sie die alte Version durch Löschen des QR-codengrave Ordners.
Laden Sie die letzte Version herunter und verschieben Sie sie zur gewünschten Position auf Ihrem Rechner.
Verschieben Sie nun die vorab zwischengespeicherte Persistence.dat in den src/assets Ordner des aktualisierten Programms.

Estlcam: Inverse Gravuren

Schallbert — Tue, 27 Sep 2022 00:00:00 +0000

Der Plan war, ein Holzschild mit meiner CNC zu fertigen. Es sollte jedoch invertiert sein. Das heißt, die Lettern sollten sich vom flachen Hintergrund abheben. Da es verschiedene Wege gibt, so etwas in Estlcam umzusetzen (ein sogenanntes Computer Aided Machining Programm, was aus Zeichnungsdaten Fräspfade und später Maschineninstruktionen erzeugen kann), aber nicht alle Wege leicht zu finden oder gut anwendbar sind, biete ich hier eine Schritt-für-Schritt Anleitung an.

1. Den Rahmen des Schildes importieren

Zuerst sollten Zeichnungsdaten des Rahmens von dem zu fertigenden Schild vorliegen, beispielsweise im DXF-Format. Ich habe ein rechteckiges Schild mit abgerundeten Ecken und definierter Rahmenstärke in meinem CAD-Programm gezeichnet. Es gilt sicherzustellen, dass die Frästiefe später nicht die Breite des Rahmens überschreitet, ansonsten könnte die Fräsarbeit zu instabil werden.

2. Den Text hinzufügen

Jetzt kann der Inhalt des Schildes in Form von Text durch Tastendruck auf das “Carve”-Symbol hinzugefügt werden. Dabei ist es sinnvoll, die Breite der Textbox an die inneren Rahmengrenze anzupassen, sodass der Text stets hineinpasst. Man hat verschiedene Carve-Stile zur Auswahl. Für die hier dargestellte Fräsarbeit ist Carve aussen zu wählen. Nun den Text eintippen, Schriftart selektieren und die Schrifthöhe so anpassen, dass es im Schild ein harmonisches Bild ergibt.

Abhängig vom zu verwendenden Fräser sollte dann die Frästiefe gewählt werden. Bei kleineren Winkeln der V-Nutfräsers ist die Frästiefe meist größer zu wählen als bei breiten 90°-Fräsern wie ich ihn verwende. Für mein 12mm starkes Plattenmaterial setze ich eine Frästiefe von 4.5mm an. Anschließend wird die maximale Fräsbreite festgelegt. Gemeint ist hier, wie breit die “Täler” zwischen den Buchstaben sein sollen. Da ich für den invertierten Carve eine “Talsohle” benötige, habe ich hier einen sehr großen Wert eingestellt. Zum Schluss dann sollte die Taste Umrahmung auswählen geklickt werden. Hiermit ist die Fräsarbeit dann nach außen begrenzt.

Bitte dieses Bearbeitungsfenster vorerst geöffnet lassen.

3. Werkzeugauswahl

Wählen Sie nun das V-Nutwerkzeug durch Klicken in der entsprechenden Zeile Ihrer Werkzeugliste für die Textfräsung aus. Stellen Sie sicher, dass das Häkchen bei Textobjekt zerlegen im Fenster “Text Fräsen” nicht erscheint, denn nur dann können Sie weitere Anpassungen vornehmen. Schließen Sie nun dieses Fenster per Klick auf OK. Nun wählen Sie Vorschau aus, um sich einen Eindruck von der Fräsarbeit zu verschaffen. Sehen Sie die eng beisammenstehenden parallelen Linien rechts im Bild? Dies wird durch den Parameter Räumzustellung aus der Werkzeugtabelle verursacht. Für saubere Arbeiten mit einem Gravurfräser sollte dieser Wert bei kleiner gleich 5% bleiben.

Hmm, so werden Sie noch keine befriedigenden Arbeitsergebnisse erhalten, und die Fräsarbeit wird lange dauern. Wir benötigen also zusätzlich ein paar Räumpfade mit einem normalen Schaftfräser.

4. Räumen

Speichern Sie Ihr Projekt spätestens jetzt ab. Nach dem aktuellen Schritt kann der Text nicht mehr bearbeitet werden!

Um den Fräser für die Räumung der “Talsohle” hinzuzufügen, wählen Sie den Carve-Pfad aus und wählen Textobjekt zerlegen an. Bestätigen Sie mit OK und wählen den Fräspfad erneut aus. Nun erscheint die Werkzeugkonfiguration. Fügen Sie das Räumwerkzeug hinzu. Vorzugsweise ist sein Durchmesser geringer als der Abstand zwischen Schrift und Rahmen, sodass eine möglichst große Fläche später glatt geräumt werden kann (Anmerkung: Ich habe das nicht gemacht, weswegen auf meinem Beispiel ein paar raue Stellen übrig geblieben sind). Die Räumzustellung dieses Fräsers wähle ich bei Holz zwischen 20% und 40%.

Wenn Sie für die Gravur einen Fräser ohne Abflachung am Boden gewählt haben (ich empfehle hier gern 0.5mm als guten Kompromiss zwischen hoher Auflösung und guter Fertigungsqualität), können Sie die Räumzustellung des Fräsers in der Werkzeugtabelle zur Verbesserung der Oberflächenqualität noch einmal nach unten korrigieren.

5. Zweite Vorschau

Ok, jetzt sollten wir durch sein. Nochmal kurz die Vorschau ausgewählt und sich über die reduzierte Verarbeitungszeit gefreut, und ran an die Maschine?

Ah, eine weitere Optimierung kann für das Gravurfräsen angebracht sein: Unter Einstellungen die Sicherheitshöhe auf ein Minimum reduzieren (aber ohne in Klemmen oder andere Hindernisse zu rauschen). Das ständige Aus- und Eintauchen ins Material kostet bei Gravuren in Estlcam immer recht viel Zeit, wenn sich die Sicherheitshöhe in großem Abstand zur Werkstückoberfläche befindet.

Keine Sorge, wenn die Schrift in der Vorschau nun nicht mehr lesbar ist. Das ist total normal, weil ja nur die (jetzt wegen Verwendung des Räumfräsers gröber dargestellten) Fräspfade angezeigt werden.

Nach einer letzten Prüfung von Vorschüben und Werkzeugen kann’s jetzt endlich losgehen :)

6. Auf die CNC damit!

Viel Spaß beim Fräsen. Ich für meinen Teil fand es sehr entspannend, der Maschine dabei zuzusehen, wie sie langsam ein immer deutlicher werdendes Bild ins Holz schneidet, was aber erst bei Verwendung des V-Fräsers lesbar wird.

Favicon und Sammlungsgenerator

Schallbert — Sun, 13 Jun 2021 00:00:00 +0000

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 00:00:00 +0000

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 00:00:00 +0000

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 00:00:00 +0000

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 00:00:00 +0000

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.

🎄 Steckbrett-Lagerfeuer

Schallbert — Mon, 01 Jan 0001 00:00:00 +0000

Projekt-Steckbrief

Schwierigkeit: Anfänger 1/5
Kosten: 8…25€
Zeit ~1h

Überblick

Dies ist ein schnelles und einfaches Projekt, das zeigt, wie man mit einem Microcontrollerboard und einigen LEDs eine warme und gemütliche Wohnzimmeratmosphäre schaffen kann. An eine Powerbank angeschlossen, wird diese kleine Bastelei den ganzen Abend leuchten und eine warme und gemütliche Atmosphäre schaffen. Ich habe Teile der Idee für dieses Projekt dem Buch “Tiny AVR for the evil Genius” entliehen, in dem ich viel gelesen habe, als ich vor Jahren mit dem Entwurf eingebetteter Software in C begann.

Die Projektkosten hängen von den gewählten Komponenten ab. Wenn ein original Arduino verwendet wird, liegen sie am oberen Ende des Bereichs. So kann man den hart arbeitenden Entwicklern und Ingenieuren von Arduino Anerkennung zollen, die Open-Source-Lösungen für uns alle schaffen 🥳.

Die Hardware

Natürlich kann man jedes Mikrocontroller-Board verwenden, das mindestens 8 digitale Ausgänge und 1 analogen Eingang unterstützt. In meinem Beispiel verwende ich ein Arduino Nano (Nachbau), das ich irgendwo herumfliegen hatte. Zeit für ein Upgrade auf das “Original”… Des Weiteren benötigt man ein Steckbrett, ein paar Drähte und acht LEDs. Ich empfehle, 5 warmweiße LEDs, 2 gelbe LEDs und 1 rote LED mit ähnlicher Helligkeit (Lumenzahl) zu verwenden, um Farben zu erhalten, die einem echten Feuer ähnlich sind.

Die Software

Die Software erzeugt einen flackernden Lichteffekt mit unterschiedlicher Geschwindigkeit.

Einrichtung

Beim Start definiere ich in setup() die Pins, an die die LEDs angeschlossen sind, als Ausgänge. Ich lasse einen offenen Analog-Pin einmal auslesen und nehme dessen (undefinierten) Wert als Seed für den später besprochenen Pseudo-Zufallszahlengenerator.

Schleife

In der Endlosschleife berechnet das Programm eine neue Zufallszahl und übergibt diese dann an die nachgeschalteten Funktionen. Hier erzeugt ein Zufallszahlengenerator einen Wert, der dann verwendet wird, um

zu bestimmen, welche der acht LEDs leuchten soll
die Zeit festzulegen, für die dieser LED-Status beibehalten werden soll.

Schließlich werden die LEDs entsprechend gesetzt und die Schleife wiederholt sich am Anfang.

Linear rückgekoppeltes Schieberegister

Der Zufallszahlengenerator ist als sogenanntes linear feedback shift register (LSFR) mit einer Länge von 32bit implementiert (wiederholt sein Muster nach max. 2^32 Schritten). Diese Implementierung verwendet den “Galois-Typ” von LFSRs.

Galois LFSR Implementierung

void loop() 
{
 iRandNum = (iRandNum >> 1) ^ (-(iRandNum & 1u) & 0xd0000001u);
 [...]
}

In dieser Codezeile passiert eine Menge, also schauen wir sie uns mal genauer an.

Wesentlich für diese Art von Zufallszahlengeneratoren ist die XOR-Operation, die durch ein ^ in der Mitte der Codezeile angezeigt wird. XOR" bedeutet “eXclusive OR”, das nur dann eine logische 1 ausgibt, wenn die logischen Eingänge A und B unterschiedlich sind. Wenn “A” und “B” beide “0” oder beide “1” sind, wird dieses Gatter “0” ausgeben.

Beispiel für binäres XOR:

 A B Ergebnis
0b00001111 ^ 0b00110011 = 00111100

Links vom XOR-Operator wird die aktuelle Zufallszahl um 1 nach rechts verschoben (>>). Dabei wird ihr gesamter Inhalt wird um ein Bit geschoben. In numerischer Hinsicht bedeutet dies, dass der Wert ganzzahlig durch zwei dividiert wird.

Beispiel für binäres SHIFT:

 A B Ergebnis Als Zahl:
0b00001111 >> 1 = 0b00000111 15 >> 1 = 7

OK, analysieren wir die obige Zeile Code weiter. Direkt neben dem XOR-Operator findet eine weitere Operation statt: Ein logisches AND (&) zwischen unserer aktuellen Zufallszahl und 1u, was “unsigned 1” bedeutet. Dabei werden alle höheren Bits des Zufallszahlengenerators maskiert. Das Ergebnis dieser Aktion ist eine einfache “0”, wenn die Zahl eine “0” als niedrigstwertiges Bit hat usw.

Beispiel für binäres UND:

 A B Ergebnis 
0b00001111 & 1 = 0b00000001

Die Negation am Anfang dieses Terms bedeutet, dass, wenn das Ergebnis des vorherigen & 0 war, der gesamte Term wieder 0b00000000... sein wird. Wenn das Ergebnis -1 lautet, sieht der 2er-Komplement-Binärcode stattdessen wie folgt aus: 0b1111111....

Dies ist eine einfache Möglichkeit, einen einzelnen booleschen Wert auf einen beliebigen längeren Datentyp anzuwenden, ohne eine Verzweigungslogik wie bei einer if()-Klausel zu verwenden.

Und schließlich gibt es ein weiteres logisches AND zwischen diesem Begriff und einer festen Bitmaske 0xd0000001u. Letztere sind die “Anzapfungen” des LFSR, d.h. welche Bits des aktuellen Wertes in das System zurückgeführt werden. Die Aufschlüsselung dieses Hex-Wertes in Boolesche Werte zeigt: 0xd = 0b1101", d.h. die Bits 32, 31, 29 und 1 werden mit der aktuellen Zufallszahl maskiert, so dass nur ihre Werte unberührt bleiben, während alle anderen auf “0” gesetzt werden.

Galois LFSR Zusammenfassung

Puh, das war eine Menge. Es ist Zeit für ein paar Minuten Pause.

Gut, fassen wir die Codezeile oben nochmal zusammen:

iRandNum = (iRandNum >> 1) ^ (-(iRandNum & 1u) & 0xd0000001u);

Bedeutung: “Wenn das niedrigstwertige Bit der aktuellen Zufallszahl Null ist, dann verschiebe die Zufallszahl einfach nach rechts. Andernfalls XOR anwenden mit den abgegriffenen Bits der aktuellen Zufallszahl.”

LFSRs sind weit verbreitet in der drahtlosen Kommunikationstechnik, sie sind interessant für Prüfsummenberechnungen, [Kryptographen](https://medium. com/@czapfel/an-introduction-to-lfsrs-for-cryptography-bf2602640e91) und können sogar bei Programmierspielen nützlich sein, z.B. bei der Erstellung prozeduraler Karten. LFSRs sind einfach zu implementieren (wie man oben sieht, benötigen sie im Extremfall sogar nur eine einzige Codezeile!) und verbrauchen nicht viele Ressourcen. Hier ist ein hervorragender Blogpost, der sich eingehend mit LFSRs beschäftigt, wenn Sie eher der visuelle Typ sind (und weniger der logische). Nachteilig ist, dass ihre “Zufallsqualität” schlecht ist, weil sie deterministisch sind.

Alles in allem fand ich das Thema so interessant, dass ich mich entschlossen habe, hier einen LFSR manuell zu implementieren, anstatt die Arduino-Funktion random() zu verwenden.

Pitfall! Spielszene: prozedurales Leveldesign mittels LFSR ^[1]

Ein Problem bleibt

Nun, wenn Sie die Codezeile vollständig verstanden haben, sehen Sie, was passiert, wenn die Zufallszahl nur Nullen enthält.

Er wird nie wieder aus diesem Zustand herauskommen 💀.

Deshalb sollte man diese Art von LFSR niemals mit “0” initialisieren.

Ansteuerung der LEDs

Der Rest der Software hat viel mehr Zeilen, macht aber auch viel mehr langweilige Sachen. Sie nimmt den generierten 32-Bit-Zufallswert und lässt ihn an den 8 LED-Ausgängen vorbeilaufen, d.h. jede LED “sieht” jedes Bit des Wertes. Zwischen jeder dieser Iterationen wird eine zufällige Verzögerung verwendet, so dass die Flackergeschwindigkeit auf eine Änderungsrate begrenzt ist, die wir Menschen noch wahrnehmen können.

Die Hardware

Zum Glück ist die Hardware einfacher zu erklären als die Software:

Ein Arduino Nano-Board ist mit einem Prototyping-Board verbunden.
Anoden der acht LEDs (+) sind mit den digitalen Ausgängen D2...D9 verbunden.
Ihre Kathoden werden mit Jumpern gebrückt und mit dem “GND” des Arduino verbunden.

Dies ist die einfachste Konstruktion, die mir für diese Aufgabe einfiel.

Verbesserungen

Jede LED sollte einen Vorwiderstand bekommen.
- In meinem Design ist der Strom nur durch den maximalen Strom begrenzt, den der Arduino Pin treiben kann.
- Entweder kann die LED deutlich mehr als 40mA Spitzenstrom verkraften oder sie wird unweigerlich irgendwann durchbrennen.
- Bei der Berechnung des Widerstands sollte man sich an das Datenblatt der LED halten, da verschiedene LED-Farben unterschiedliche Spannungen haben.
- Beispiel für eine Widerstandsberechnung bei einer Versorgungsspannung von 5V für eine Warmweiße LED: 20mA @ 3.1V --> R = U/I = (Usup-Uled) / I = 1.9 / 0.02 = 95Ohm. Nächster Widerstand aus der E6-Reihe 100Ohm.
Jede LED könnte einen Parallelkondensator erhalten.
- Dies würde den Flackereffekt glätten.
- Man könnte Videos aufnehmen, in denen die Kamera nicht durch das Flackern der LEDs gestört wird. Das wäre doch schön.
- Beispiel Kondensatorberechnung: Durchschnittlicher Strom im ausgeschalteten Zustand 20mA, erlaubter Spannungsabfall 0.6V innerhalb von 1ms. Vorgeschlagene Kapazität ist dann 20mA * 1ms / 0.6V = 33uF

Zeit für eine DIY-Replik?

Bitteschön!

Steckbrett-Lagerfeuer DIY Anleitung

ClickEncoder

Schallbert — Mon, 01 Jan 0001 00:00:00 +0000

Projekt-Steckbrief

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

Überblick

Bibliothek für das Arduino Framework, geschrieben in C++.

Der Quellcode selbst besteht nur aus ein paar hundert Zeilen. Er ist leichtgewichtig und leistungsfähig, da der verbesserte Algorithmus weniger Berechnungen benötigt und gleichzeitig eine bessere Zustandsinterpretation bietet als das ursprüngliche Projekt, von dem sie abgezweigt ist. Die Bibliothek ist offiziell auf PlatformIO IDE veröffentlicht und wird auf Github gehostet und gepflegt. Sie enthält Beispiele sowohl für Arduino- als auch für PlatformIO-IDEs und bietet Unittests, die nach der Anpassung an die spezifische Anwendung ausgeführt werden können.

Motivation

Ich habe zunächst die von 0xPIT veröffentlichte Originalbibliothek verwendet, aber diese verursachte bei mir einige Compiler-Warnungen, außerdem waren die Messwerte des Encoders nicht einwandfrei und manchmal gab es Jitter oder zurückspringende Werte, was ich nicht akzeptieren wollte.

Lösung

Da das Archiv ungepflegt aussah und meine Anfrage für Verbesserungen nicht beantwortet wurde, beschloss ich, diese Probleme selbst zu beheben. Ich habe also behutsam einen Teil des Codes umgeschrieben. Für mein damaliges Projekt benötigte ich auch ein “Wiederholungssignal”, wenn eine Taste kontinuierlich gedrückt wird, also fügte ich auch dies hinzu. Schließlich trennte ich den Encoder-Algorithmus von der Tastenbehandlung und stellte separate Klassen bereit, so dass nun bei Bedarf jede beliebige Kombination aus Taste und Encoder verwendet werden kann, jeweils mit konfigurierbarem Verhalten.

Encoder Algorithmus erklärt

API

Die API von ClickEncoder ist einfach und leicht zu verstehen: service() führt die Geschäftslogik aus und die Zustandsinterpretation durch. Diese Methode muss regelmäßig ausgeführt werden, um zu überprüfen, ob der Encoder seit seinem letzten Aufruf bewegt wurde, in welche Richtung, wie viele Schritte, und diese Werte dann in einer Akkumulatorvariablen speichern. getIncrement() gibt die Schrittänderungen des Encoders seit dem letzten Aufruf zurück. getAccumulate() gibt die Summe der Inkremente seit dem Start zurück. getButton() gibt den aktuellen Button-Status zurück.

void service();
int16_t getIncrement();
int16_t getAccumulate();
Button::eButtonStates getButton();

Encoder-Status

Der Encoder verwendet einen Gray Code zur Kodierung der Schritte. getBitCode() wandelt diesen Code, der über die Hardware-Pins A und B des Encoders übertragen wird, in eine “0…3”-Rasten-Interpretation um, wobei die Zahlen bei einer Rechtsdrehung ansteigen und bei einer Linksdrehung abfallen. Dies geschieht effizient ohne Verwendung von if() oder anderer Verzweigungslogik.

uint8_t Encoder::getBitCode()
{
 // GrayCode convert
 // !A && !B --> 0
 // !A && B --> 1
 // A && B --> 2
 // A && !B --> 3
 uint8_t currentEncoderRead = digitalRead(pinA);
 currentEncoderRead |= (currentEncoderRead << 1);
 
 // bit0 of result to be inverted if set
 currentEncoderRead ^= digitalRead(pinB);
 return currentEncoderRead;
}

Ich habe hier mit einem Trick gearbeitet, sodass man sich den Code-Schnipsel oben möglicherweise mehrfach ansehen muss. Der Zustand von PinA wird auf Bit1 von currentEncoderRead geschrieben, indem ich es mit der <<-Operation nach links schiebe. Gleichzeitig bleibt der Status des 0. Bits durch |= aber erhalten. Würde ich jetzt PinB einfach logisch &= anbinden, dann würde ich den Gray-Code verletzen, nachdem A&&B=2 sein sollte und nicht 3.

Sind A und B also beide nicht gesetzt, bleibt das Ergebnis 0, denn 00^00=00=0. Ist nur A gesetzt, B aber nicht, so lautet das Ergebnis 11^00=11=3. Wenn B gesetzt ist, A aber nicht, ergibt sich 00^01=01=1. Sind beide gesetzt, schließlich 11^01=10=2.

Für weitere Informationen zum Thema logische Binäroperationen siehe mein Steckbrett-Lagerfeuer Projekt

Zustandsinterpretation

Nachdem der Bitcode gelesen wurde, wird die Variable rawMovement gesetzt, die uns sagt, wie weit der Encoder zwischen zwei Durchläufen der service() Routine gedreht wurde. Hier sieht man, dass dieser Schritt zeitkritisch ist: Es kommt zu Aliasing-Fehlern, wenn der Geber schneller einmal alle Positionen wechselt, als dass service() erneut aufgerufen wird. In diesem Falle würden Schritte verloren gehen.

void Encoder::handleEncoder()
{
 uint8_t encoderRead = getBitCode();
 // bit0 set = status changed, bit1 set = "overflow 3" where it goes 0->3 or 3->0
 uint8_t rawMovement = encoderRead - lastEncoderRead;
 lastEncoderRead = encoderRead;
 // This is the uint->int magic, converts raw to: -1 counterclockwise, 0 no turn, 1 clockwise
 int8_t signedMovement = ((rawMovement & 1) - (rawMovement & 2));

 encoderAccumulate += signedMovement;
 encoderAccumulate += handleAcceleration(signedMovement);
}

Hier ein weiterer Trick: signedMovement wird berechnet, indem die Bewegung in eine vorzeichenbehaftete Ganzzahl umgewandelt wird, die 0 als “nicht gedreht”, -1 als “links gedreht” und 1 als “rechts gedreht” darstellt. Dabei wird das Verhalten bei Integer-Überlauf ausgenutzt, in Kombination mit der Interpretation von “signedness”.

Abschließend wird die Akkumulation durchgeführt und die Beschleunigung, sofern konfiguriert, dem Akkumulator hinzugefügt, je nachdem, wie schnell der Geber gedreht wird.

Um diese beiden Methoden ohne Verzweigungen zu programmieren, habe ich mehrere Abende Grübelei und praktisch einen halben Block kariertes Papier benötigt. Offen gesagt haben mich diese paar Zeilen Code an den Rande der Leistungsfähigkeit meines Hirns gebracht. Ich habe das Programmieren eben nicht von der Pike auf gelernt 😅

Die Methode getAccumulate()

Sie ist wirklich einfach. Sie gibt nur den internen akkumulierten Wert zurück, der der Konfiguration des Encoders entspricht, wie viele Ticks einen Schritt ausmachen.

int16_t Encoder::getAccumulate()
{
 return (encoderAccumulate / stepsPerNotch);
}

Die Methode getIncrement()

Gibt zurück um wie viele Ticks sich der Encoder seit dem letzten Aufruf dieser Methode bewegt hat.

int16_t Encoder::getIncrement()
{
 int16_t accu = getAccumulate();
 int16_t encoderIncrements = accu - lastEncoderAccumulate;
 lastEncoderAccumulate = accu;
 return (encoderIncrements);
}

Ermittlung des Tasterzustands

Die Methode handleButton()

Alle Tasterzustände leiten sich von zwei Basiszuständen ab: gedrückt oder nicht gedrückt. Dies spiegelt sich in der Logik wider:

void Button::handleButton()
{
 if (lastGetButtonCount < ENC_BUTTONINTERVAL)
 {
 return;
 }
 lastGetButtonCount = 0;

 if (digitalRead(pinBTN) == pinActiveState)
 {
 handleButtonPressed();
 }
 else
 {
 handleButtonReleased();
 }

 if (doubleClickTicks > 0)
 {
 --doubleClickTicks;
 }
}

Der Taster kann so konfiguriert werden, dass er seltener ausgelesen wird als der Encoder. Wenn dies der Fall ist, bleibt diese Methode zwischenzeitlich ohne Aktion.

Taste gedrückt:

handleButtonPressed() kann entweder Closed, Held oder LongPressRepeat zurückgeben, je nachdem wie der Taster konfiguriert ist und wie lange er bereits gedrückt wurde.

Taste nicht gedrückt:

handleButtonReleased() kann entweder Clicked, Released oder Doubleclicked zurückgeben, abhängig von der Konfiguration des Tasters und der Anzahl der Klicks innerhalb einer bestimmten Zeit.

Konfiguration der Bibliothek

Das Verhalten der Encoder/Tastenerkennung kann in der Datei encoder.h mit Hilfe der unten aufgeführten Konstanten geändert werden. Die Werte wurden bereits optimiert und fühlen sich, zumindest für mich, natürlich an. Sie sollten geändert werden, wenn Sie ein anderes Serviceintervall als 1ms verwenden möchten, da diese Werte alle dieses Intervall als Referenz nehmen.

// ----------------------------------------------------------------------------
// Acceleration configuration (for 1ms calls to ::service())
//
constexpr uint8_t ENC_ACCEL_START = 150; // The smaller this value, the quicker you must turn to activate acceleration.
constexpr uint8_t ENC_ACCEL_SLOPE = 75; // the smaller this value, the stronger the acceleration will manipulate values.

// Button configuration (values for 1ms timer service calls)
//
constexpr uint8_t ENC_BUTTONINTERVAL = 20; // check button every x ms, also debouce time
constexpr uint16_t ENC_DOUBLECLICKTIME = 400; // second click within x ms
constexpr uint16_t ENC_LONGPRESSREPEATINTERVAL = 200; // reports repeating-held every x ms
constexpr uint16_t ENC_HOLDTIME = 1200; // report held button after x ms
// ----------------------------------------------------------------------------

Verwenden Sie sie in Ihrem Projekt!

Die Bibliothek ist eine Open-Source-Software, die unter der MIT-Lizenz steht.
PlatformIO-Benutzer? Ganz einfach, suchen Sie sie in der Ansicht ‘Bibliotheken’, die Tags sind Arduino, Encoder, Schallbert. Dann ist es nur noch ein Klick, um sie zu Ihrer Lösung hinzuzufügen.
Alternativ können Sie auch das repository klonen oder forken und die Header/Cpp-Datei nach eigenem Ermessen verwenden.
Sie möchten etwas beitragen? Vielleicht haben Sie eine effizientere Zustandsberechnung für die Taster? Ich würde mich freuen, Ihren Pull Request in meinem Posteingang zu finden.

Diese Website programmieren

Schallbert — Mon, 01 Jan 0001 00:00:00 +0000

Projekt-Steckbrief

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

Die Idee

Die Idee entstand durch mein MobFobAmp-Projekt, für das ich kein Github-Repository hatte, da es keinen Code oder ähnliche Dokumentation gab. Also beschloss ich eine Website einzurichten, auf der ich Anleitungen für dieses Open-Hardware-Projekt bereitstellen kann, damit andere das Projekt nachbauen können. Ich wollte eine einfach zu hostende Lösung, die nicht zu viel Arbeit beim Einrichten erfordert. Da ich keinen eigenen Server habe, habe ich um Hilfe gebeten. moritzmar empfahl mir, für den Anfang “Github-Pages” als Site-Host zu verwenden, um eine einfache automatische Bereitstellung und globale Reichweite zu gewährleisten. Also habe ich das mal ausprobiert.

Erste Schritte

Eine statische Site kam mir genau Recht. Ohne die Notwendigkeit einer Datenbank oder eines großen Content-Management-Frameworks bleibt mein Site-Layout einfach und minimalistisch; ich wollte am Anfang nur dieses eine Projekt hosten. Github empfiehlt die Verwendung von Jekyll

Jekyll Logo ^[1]

als Website-Generator. Ich hatte einige Probleme mit dem Windows Subsystem für Linux (WSL), da es meine Terminaleingaben nicht akzeptierte, also folgte ich der Anleitung und verwendete den RubyInstaller, der bei mir sofort funktionierte.

Einrichtung der Site

Mir wurde klar, dass ich vielleicht mehrere meiner Projekte dokumentieren möchte. Deshalb kam ich auf die Idee, Projekte in Gruppen zusammenzufassen, jede mit einer Überschrift, einem kleinen Text und einem Miniaturbild. Wenn man darauf klickt, kommt man auf die jeweilige Projektseite. Das würde eine Menge Programmierarbeit für die Seiteneinrichtung und das Layout bedeuten, mit der ich nicht allzu viel Zeit verbringen wollte - meine anderen Projekte warten…

Erster Versuch mit Themes

Also folgte ich einer weiteren Anregung von Github-Pages: Die Verwendung von vordefinierten “Themes”. Zuerst habe ich das Agency Theme verwendet. Es hat eine tolle Landing Page mit einem großen Bild und unterstützt Sammlungen, die das von mir gewünschte Gruppieren von Projekten ermöglichen. Leider ist das Thema ein “Remote-Thema”, so dass die Anpassungsmöglichkeiten begrenzt waren, z. B. konnte ich eine Sammlung nicht auf eine andere Seite verweisen lassen, sondern es öffnete sich immer ein “Popup”, und das wollte ich einfach nicht. (Später habe ich herausgefunden, dass Remote-Layouts überschrieben werden können, aber da war es zu spät, denn ich hatte bereits zu einem anderen Theme-Anbieter gewechselt…) Das Theme, das ich derzeit verwende, ist das “Minimal Mistakes Theme” (siehe Fußzeile der Website), das sehr gut dokumentiert ist. Nach dem Herunterladen und ein paar ersten Schritten kämpfte ich mit benutzerdefinierten Farben (_sass) und den Kollektionen - wieder einmal - da ich zunächst nicht verstand, wie Jekyll die Bindungen hinter den Kulissen durchführt. Einige meiner Schwierigkeiten sind in den Blog-Beiträgen vom Juni 2021 zu finden.

Seitenlayouts: Hero Screens

Um die Navigation einfach und intuitiv zu gestalten, sollte man sich ein paar Gedanken darüber machen, wie das Layout der Seite aussehen soll. Die Herangehensweise wird sich bei jedem Seitentyp aufgrund der unterschiedlichen Komplexität und Dokumentstruktur unterscheiden.

Auf der Landing-/Homepage zum Beispiel soll die Navigation mitlaufen, so dass die Kategorien der Website immer sichtbar sind. Sie soll ein großes, breites Overlay-Bild mit der Seitenbeschreibung erhalten. Darunter sollen die neuesten Beiträge aufgelistet werden. Dies ist das Beispiel für die “Hero Pages” der Kollektion:

Die Projekte und ihre Inhalte enthalten eine Seitennavigation in der linken Seitenleiste, können ein scrollbares Panoramabild enthalten und haben eine breite Einstellung, um eine große Menge an Text im Inhaltsbereich anzuzeigen.

Die “hero screen”-Skizzen für die Layouts dieser Website finden Sie hier.

Sammlungen / Kollektionen

Sammlungen (englisch “Collections”) sind eine gute Möglichkeit, Inhalte zu gruppieren. Sehen Sie sich meine Open Hardware Projekte Seite an. Sie können alle Projekte in dieser Kategorie mit einem kleinen Teaser-Bild und einer Beschreibung finden, um einen Überblick zu bekommen.

So kann die Konfiguration der Sammlung aussehen:

Überlegen Sie sich einen passenden Namen für Ihre Sammlung, z.B. electronics.
Der Name der Sammlung wird in _config.yml als collections: electronics definiert.
Der Sammlungsname muss in #defaults als type: electronics gesetzt werden, damit Jekyll weiß, wie der tatsächliche Inhalt zu interpretieren ist.
Eine Sammlungsseite muss erstellt werden (z.B. im Ordner _pages) mit dem Attribut collection: electronics. Dies ist die Seite, die die Übersicht der Artikel in der Sammlung anzeigt.
Es muss ein Ordner mit demselben Namen wie der Name der Sammlung mit führendem Unterstrich erstellt werden: _electronics.
Alle Dokumente in diesem Ordner werden nach einem vollständigen Bauvorgang automatisch auf der Sammlungsseite angezeigt.
Diese Dokumente sollten ein “front matter” (Abschnitt vor dem eigentlichen Inhalt in der Datei, gekennzeichnet mit ---) erhalten, damit sie wie in der entsprechenden _layouts-Datei beschrieben angezeigt werden können, z.B. collection. Vergisst man dies, wirft einem Jekyll in der Konsole seitenlange, unverständliche Fehlermeldungen um die Ohren.

Mehr als das Standard-Theme

Ich habe zwar einige Theme-Standardeinstellungen überschrieben, verwende aber zumeist die bestehendenTheme-Infrastruktur. Dennoch hat meine Seite ein paar spezielle Anforderungen, so dass ich das Theme anpassen und neue Funktionen hinzufügen musste. Diese werden in den folgenden Abschnitten beschrieben.

Da der Navigationsbaum meiner Website ziemlich flach ist und ich nicht viele Seiten habe, zu denen ich navigieren muss, wollte ich, dass die linke Seitenleiste die Seitennavigation und nicht die Website-Navigation enthält. Daher bräuchte ich keine rechte Seitenleiste, so dass mehr Platz für den Seiteninhalt zur Verfügung stünde.

Inhaltsverzeichnis auf der linken Seite

Wie hier und dort geschrieben, war ich nie 100%ig zufrieden damit, wie meine Projektseiten aussahen:

Die ursprüngliche Idee des Themes ist, dass der Inhalt von zwei Seitenleisten eingerahmt wird. Die linke kann entweder Autoreninformationen, benutzerdefinierte Inhalte oder die Seitennavigation anzeigen. Der Inhaltsbereich ist zwischen breit und normal konfigurierbar, wobei in letzterem Fall Platz für eine zweite Seitenleiste auf der rechten Seite bleibt. Die rechte Seitenleiste ist so konfigurierbar, dass sie entweder gar nicht vorhanden ist oder das Inhaltsverzeichnis der Seite anzeigt.

Das Ziel war also die rechte Seitenleiste für mein Design zu eliminieren und statt der Seitennavigation in der linken Seitenleiste die Seitennavigation dorthin zu verschieben.

Es geht um den Ordner /_layouts, in dem Informationen darüber gespeichert werden, wie ein Seitenlayout aussehen soll. Das fragliche Seitendesign heißt single.html und ruft an einer bestimmten Stelle include sidebar.html auf, das sich in /_includes/sidebar.html befindet. Also habe ich mir einen neuen Parameter ausgedacht, mit dem ich die Anzeige des Inhaltsverzeichnisses in der linken Seitenleiste steuern kann, habe toc_left gewählt und eine Bedingung hinzugefügt:

<div class="sidebar sticky">
<!-- ...
{.% if page.toc_left %}
 {.% include toc_left nav=page.toc_left %}
{.% endif %}
... -->
</div>

(Trick: Ich musste jinja code auskommentieren und mit ... anführen, denn Liquid würde sie sonst selbst als Kommandos erkennen)

Implementierung des Inhaltsverzeichnisses

Es sollte in der linken Seitenleiste erscheinen. Also muste ich nur eine Datei namens toc_left erzeugen, die den Generator für das Inhaltsverzeichnis wie folgt aufruft:

<aside class="toc_left">
<nav class="toc" markdown="1">
<header><h4 class="nav__title"><i class="fas fa-{{ include.icon | default: 'file-alt' }}"></i>
<!-- ...
{.{ include.title | .default: site.data.ui-text[site.locale].toc_label }}</h4></header>
{.% include toc.html sanitize=true html=content h_min=1 h_max=6 class="toc__menu" skip_no_ids=true %} 
... -->
</nav>
</aside>

Audio-Einbettungen

Audio-Embeds sind diese kleinen Player-ähnlichen Dinger auf einer Website, die oft zu einer Streaming-Plattform oder ähnlichem weiterleiten. Ich brauche sie für einige meiner Audio-Projekte wie dieses mobfobamp: nur eine Überschrift und der Player darunter.

Dieser Beitrag hat mir sehr geholfen, so dass ich es einfach in das _include einfügen konnte, es ein wenig modifizieren konnte, und es funktionierte auf Anhieb.

Platzierung des Favicons

Ich folgte dieser Anleitung, um ein Favicon für die Website zu platzieren.

Der Pfad des Favicons muss unabhängig von dem Ordner, in dem sich die gerenderte Seite befindet, gültig sein. Ich musste ../ entsprechend der Tiefe der Seiten in der Ordnerstruktur der Website hinzufügen, um sicherzustellen, dass das Favicon nicht nur auf der Startseite, sondern auch auf Unterseiten angezeigt werden kann.

Optimierung für Suchmaschinen

Da meine Website einige Wochen lang nicht von Suchmaschinen gefunden wurde, beschloss ich, eine so genannte “SEO” (Suchmaschinenoptimierung) durchzuführen. Deshalb fügte ich jekyll-seo-tag hinzu und überarbeitete z.B. alle meine Links nach Juliette Sinibardy’s SEO 101. Danach habe ich meine Webseite dem Web-Analyse-Audit von Lighthouse unterzogen.

Für einen ersten Versuch sieht es meiner Meinung nach ziemlich gut aus. Das größte Problem auf der Leistungsseite scheint der CSS-Overhead zu sein.

Sicherheitsrichtlinie für Inhalte

Der Lighthouse-Audit hat gezeigt, dass es eine gute Idee wäre, externe Skripte - wie sie die Basisversion meines Themes enthält - einzuschränken. Also habe ich eine Content Security Policy (CSP) wie folgt eingeführt:

webrick:
 headers:
 Content-Security-Policy: 
 default-src 'self'; 
 script-src 'self'; 
 connect-src 'self'; 
 img-src 'self'; 
 style-src 'self' 
 font-src 'self;

Mit dieser strikten Auslegung werden Inhalte Dritter gar nicht mehr geladen (aber leider meine eigenen teils auch nicht).

Anfänglich wurde das Hintergrundbild meiner Homepage nicht angezeigt, meine eingebetteten Audiodateien konnten nicht abgespielt werden und alle Icons, die von extern geladen wurden, waren ebenfalls weg. Das Hinzufügen von media-src: 'self'; und etwas mehr Lektüre in Jakob Wilforss’ Blog und vor allem Lighthouses eigene Vorschläge halfen bei der Lösung dieses Problems. Mit Hilfe der Web developer Tools des Browsers habe ich die fehlenden Ressourcen ermittelt, die das Theme im Hintergrund zu laden versucht, so dass mein aktualisiertes CSP wie folgt aussieht:

webrick:
 headers:
 Content-Security-Policy:
 default-src 'self' 'unsafe-inline' https://cdn.jsdelivr.net/; 
 script-src 'self';
 connect-src 'self';
 img-src 'self' 'unsafe-inline' https://upload.wikimedia.org/wikipedia/commons/ https://raw.githubusercontent.com;
 style-src 'self' 'unsafe-inline' https://cdn.jsdelivr.net/;
 font-src 'self' 'unsafe-inline' https://cdn.jsdelivr.net/; 
 media-src 'self'; 
 object-src 'none';
 base-uri 'none';

Update

Ende 2021 bin ich vom Nachladen von Inhalten über Drittanbieter (oben namentlich Font Awesome und Wikimedia) auf die eigene, statische Bereitstellung übergegangen. Somit gibt es keine Dritten mehr, die beim Aufruf meiner Seite etwas von Ihnen mitbekommen - und die Seite lädt etwas schneller. Meine Content Security Policy habe ich wieder auf die Obere der beiden Darstellungen zurückgedreht, media-src 'self'; aber beibehalten.

Fehler

Hier sammele ich Fehler, deren Lösung trivial erscheint, die mich aber dennoch ganze Abende gekostet haben.

Jekyll serve: `UTF-8` incompatible character encoding

Man gibt bundle exec jekyll serve ein und erhält einen seltsamen UTF-8 “incompatible character encoding” Fehler? Die Ursache ist einfach: Eine der zu konvertierenden Dateien hat höchstwahrscheinlich keinen Header, der in das “Front matter” der Seite übersetzt werden kann, die aus dieser Datei generiert wird. Einfach die übliche Kopfzeile zur fraglichen Datei hinzufügen und schon funktioniert es wieder:

---
title: "Feeds and Speeds database"
description: "for (light) CNC milling machines"
header:
 image: "blah/testimage.jpg"
[...]
---

Webseite wird nicht dargestellt: `404`

Dieser Fehler war besonders fies versteckt, denn auf meinem Rechner als localhost wird die Seite einwandfrei dargestellt - nur “in Produktion” erscheint, wenn ich die Seite aufrufe, gar nichts.

Ursache: neuerdings verwende ich das permalink: Attribut in der Frontmatter von Seiten, die übersetzt werden sollen und auf einer tieferen Ebene liegen - für diese möchte ich die Links kurz halten, daher bekommen sie manuell erstellte Permalinks. Nur wenn ich ihnen ein “trailing slash” gebe, lassen sie sich auch online aufrufen. Beispiel:

# Falsch:
---
title: "This Page won't be displayed"
permalink: /projects/pageerror
# [...]
---

# Richtig:
---
title: "This Page will be displayed!"
permalink: /projects/nopageerror/
# [...]
# Wird auf dem deutschen Blog zu:
---

Website-Hosting

Diese Seite ist selbst ein normales Gitea-Repository. Es wird automatisch mit einer von Github Actions entlehnten Aktion gebaut, sobald Änderungen zum Main des Repositorys hinzugefügt werden.

Update Jan-2024

Inzwischen bin ich von Github-Pages nach Gitea umgezogen und hoste meine Webpräsenz nun selber. Dennoch sind alle Inhalte dieser Seite weiterhin als Repository verfügbar und können leicht von mir gewartet und auf Stand gebracht werden. Außerdem schütze ich die Site nun vor unautorisiertem Zugriff

Zusammenfassung

Sich damit vertraut zu machen wie Jekyll die Seite erstellt, wie das Theme mit meinen Befehlen interagiert und wie man das Verhalten des Themes überschreibt, hat einige Stunden gekostet. Aber ich denke, dass diese Seite eine klare Struktur und ein mehr oder weniger “professionelles” Aussehen besitzt - und ich musste nicht eine einzige Zeile JavaScript oder HTML schreiben, um das zu erreichen. Toll!

Inhalt in Markdown *.md geschrieben
Grundlegende Konfiguration der Seite in YAML _config.yml
Seitenlayouts in html und jinja *.html, abgelegt in _layouts und _includes
Seitenvariablen und Aussehen in SASS *.scss, automatische Generierung von css-Dateien

Lust mitzumachen oder Beiträge beizusteuern?

Sie haben Ideen, Kritik oder interessante Dinge, die Sie mir mitteilen möchten? Nehmen Sie gern über meine Diskussions-Seite Kontakt auf.

GoogleTest Demo

Schallbert — Mon, 01 Jan 0001 00:00:00 +0000

Projekt-Steckbrief

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

Motivation

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

Die Welt der “embedded controller”

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

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

GoogleTest direkt in PlatformIO verwenden

Hier gestaltet sich die Installation besonders einfach:

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

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

GoogleTest per GCC einsetzen

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

MinGW herunterladen und installieren

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

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

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

MinGW konfigurieren

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

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

PlatformIO konfigurieren

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

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

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

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

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

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

Tests ausführen

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

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

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

Tipps und Tricks

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

Ab diesem Punkt

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

Repository-Inhalte erklärt

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

Schnittstelle der Hardware-Abstraktionsschicht

Schauen wir uns das Interface und seine Struktur genauer an.

// hal_if.h
namespace hardwareAbstraction {

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

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

} // hardwareAbstraction

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

LoopInOut

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

// loopInToOut.h

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

 bool loopThrough(uint8_t inPin, uint8_t outPin);

private:
 hardwareAbstraction::Hal_IF& m_hal;
};

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

// loopInToOut.cpp

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

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

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

Modellierte Hardwareabstraktion (mock hal)

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

// hal_mock.h

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

Die Testvorrichtung (test fixture)

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

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

 virtual void TearDown()
 {
 delete m_loopInToOut;
 }

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

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

Der eigentliche Test

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

// unittest_loopInToOut.cpp

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

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

 m_loopInToOut->loopThrough(1, 2);
}

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

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

Implementierung des Hardwareverhaltens

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

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

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

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

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

#include "hal.h"

namespace hardwareAbstraction{

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

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

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

Gtest Schlüsselkonzepte

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

Dependency Injection

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

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

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

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

Hardware-Abstraktionsschicht

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

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

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

Der zweite Ansatz hat eine Reihe von Vorteilen:

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

Nachteile

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

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

Einige weitere Tipps

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

Schwieriges Thema!

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

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

PC-Upgrade

Schallbert — Mon, 01 Jan 0001 00:00:00 +0000

Projekt-Steckbrief

Schwierigkeit: Amateur 3/5
Kosten: ~500€
Zeitaufwand: ~20h

Ziel und Motivation

Im Jahr 2006 hatte ich mir einen Spiele-PC gegönnt. Als Gehäuse kaufte ich ein HTPC-Gehäuse. Es ist relativ flach und passt in das Rack einer Stereoanlage. 2015 tauschte ich ein erstes mal das Innenleben, als mir die Hardware zu langsam wurde. Ende 2025 war es wieder so weit: Das Netzteil zeigte sich mit der Leistungsaufnahme der neuen Grafikkarte überfordert, die Festplatten liefen voll und Spiele nicht mehr stabil.

Umbauten

Kurz: Es muss neue Hardware her. Doch diese erzeugt viel mehr Abwärme als die Vorherige. Zur Optimierung des Luftstroms sind daher einige Umbauten vorzunehmen. Klingt doch nach einem tollen Projekt mit vielen Facetten, die dieses Blog ausmachen: Mechanik, Elektronik, Software, CNC-fräsen.

Neue Komponenten

Einzubauen sind

650W Enermax Netzteil ersetzt 400W
Neues Motherboard MSI B550
AMD Ryzen5600x ersetzt Intel i5-6500
32GB DDR4 RAM statt 16GB
1TB PCIE SSD statt SATA SSDs
140mm Lüfter in 5.25" Schacht
2x60mm Lüfter in hintere Auslässe
96mm Lüfter für CPU, neuer Heatpipe-Kühler

Die meisten Komponenten besorge ich mir gebraucht. Nur Netzteil, Platte und Lüfter sind Neuware. Doch schnell zeigt sich, dass ich das Gehäuse modifizieren muss: Die Grafikkarte kollidiert mit dem 3.5"-Schacht, wo bis dato Festplatten und Kartenlesegerät untergebracht waren. Der große 140mm-Lüfter passt nur an die Stelle, wo sich der 5.25"-Schacht befindet.

Also müssen beide Schächte entfernt oder mit dem Trennschleifer bearbeitet werden, um Platz zu schaffen. Außerdem benötige ich eine Montagevorrichtung für den Lüfter vor der 5.25"-Öffnung. Hingucker für das Gehäuse wäre es jetzt noch, die Laufwerkklappe automatisch steuern zu können. Dann würde sie nur bei laufendem Lüfter unter hoher Rechenlast geöffnet und im Normalbetrieb geschlossen bleiben.

Anpassung des Gehäusedeckels

In meinem Artikel zum Thema Fräsen von SECC-Stahlblech zeige ich, wie man den Gehäusedeckel zwecks besserer Belüftung der Grafikkarte mit zusätzlichen Schlitzen ausstattet.

3.5"-Schacht

{< image src="/assets/images/htpc/floppy-bay-modified.avif" alt=“Image: Cutout in 3.5” bay" position=“right” >} Die Grafikkarte ist so lang, dass sie 1cm Überlappung mit dem 3.5"-Schacht besitzt. Zum Glück lässt sich der Schacht im Handumdrehen ausbauen. Also nehme ich den Trennschleifer zur Hand und bringe einen Ausschnitt in die Halterung ein. Anschließend bohre ich ein paar zusätzliche Löcher in die Seiten des Schachtes, sodass meine 2.5"-SSDs auf der von der Grafikkarte abgewandten Seite des Schachtes befestigt werden können. Auch der Schachtdeckel erhält ein weiteres Loch zur Befestigung am Gehäuse, da zwei Rastnasen durch den Ausschnitt für die Grafikkarte entfallen.

Der Kartenleser nutzt die volle Tiefe des Schachtes aus. Ich fürchte also schon, ihn gar nicht wieder montiert zu bekommen. Probehalber öffne ich sein Gehäuse und siehe da: Nur das vorderste Drittel wird tatsächlich von Leiterplatten belegt. Der hintere Teil ist anscheinend nur dafür da, Befestigungsmöglichkeiten zu bieten. Also trenne ich den hinteren Teil des Kartenlesergehäuses kurzerhand ab und baue alles wieder zusammen, sodass er sich nun passend im Schacht anbringen lässt.

5.25"-Schacht

Der Schacht ist hoch genug, um zwei Laufwerke aufzunehmen. Ich benutze aber kaum noch CDs bzw. DVDs - und wenn, dann tut es auch ein externes Laufwerk. Den leeren Laufwerkkäfig kann ich also ausbauen und stattdessen an seiner Stelle einen Lüfter montieren. Dafür entwerfe ich im CAD eine Adapterplatte, die Befestigungsmöglichkeiten und Ausschnitte für den Lüfter enthält.

Lüfterplatzierung

Ich setze Gehäuselüfter gezielt ein, um zwei voneinander getrennte Luftströmungen im PC-Gehäuse zu erzeugen: Die CPU-Netzeil-Strömung verläuft an der Gehäusefront über einen 140mm-Lüfter an den CPU-Kühler, von wo aus die Warme Luft durch Netzteil und zwei weitere 60mm-Gehäuselüfter hinaus geleitet werden.

Der Luftstrom zur Grafikkarte wird über einen außerhalb des Gehäuses verbauten 140mm-Lüfter gestützt. Die Grafikkarte selbst fördert die erwärmte Luft direkt über den Gehäusedeckel nach draußen. Um den externen Lüfter anzuschließen, schneide ich ein Loch in eine Slotblende für PCI-Einbauschächte. Dort hinein passt genau die Buchse eines Lüftersteckers. Mittels Heißkleber sichere ich die Buchse in der Blende und schließe sie sonst den Lüfter auch an einen AUX-FAN Anschluss an.

Klappensteuerung

Nun soll die Frontklappe noch automatisch öffnen, sobald der Lüfter dreht. Ist zwar komplizierter als wenn ich das von Hand mache, aber dieses Gimmick macht das Gehäuse doch erst richtig interessant. Ich entferne also das Klappenschloss und füge der Adapterplatte eine Halterung für ein Modellbauservo hinzu, welches die Klappe öffenn und schließen können soll.

Elektronik

Das Servo benötigt eine Ansteuerung. Außerdem möchte ich die Klappenzustand wie den Lüfter auch temperaturabhängig regeln, sodass ich die an dem Lüfter angelegte Spannung einlesen muss. Hierfür setze ich den Microcontroller ATTINY44 ein. Die Schaltung habe ich nur mit den allernötigsten Komponenten bestückt:

Der Microcontroller gibt ein pulsweitengesteuertes Signal an den Servo aus. Dessen Spannungsversorgung wird über einen Elko gepuffert. Die Energieversorgung für den Gehäuselüfter leite ich über zwei Steckerleisten weiter. Dort greife ich das Signal mittels Spannungsteiler ab und führe es einem Analogeingang zu. Ansonsten ist nur ein weiterer Widerstand verbaut, der den RESET-Eingang des Microcontrollers auf VCC zieht und ihn so in Betrieb hält.

Software-Anforderungen

Die Anforderungen an die Software sind einfach und klar:

Wenn der Lüfter steht, soll die Klappe schließen
Ist der Lüfter in Betrieb, soll die Klappe öffnen
Damit die Klappe nicht zu oft hin- und her fährt, soll der Klappenzustand mit etwas Verzögerung geändert werden und auch nur dann, wenn der Lüfter in der Zwischenzeit seinen Zustand beibehalten hat.

Die daraus entstandene Software ist auf meinem Github-Account frei verfügbar.

Software: Hauptschleife

Bei der Ansteuerung des Modellbauservos mache ich es mir einfach: Ich verwende die Servo-Bibliothek von Arduino.

Das Programm macht nicht viel. Ich initialisiere das Servo servoHatch, welches später im Programm angesteuert wird, definiere ein paar wenige Variablen und lege fest, auf welchem Pin der Spannungsteiler vom Lüfter liegt. Die Hauptschleife begnügt sich damit, die Spannung am Lüfter einzulesen und basierend darauf zu entscheiden, ob sich die Klappe bewegen sollte.

Die Auswertung übergebe ich dann der Klappensteuerung. Anschließend wartet das Programm 15ms und läuft dann erneut los.

Servo servoHatch; // create Servo object to control a servo
uint16_t fanVoltage{0}; // variable to read the value from the analog pin
bool open{false};

void setup() {
 pinMode(pinFanVoltage, INPUT);
}

void loop() {
 fanVoltage = analogRead(pinFanVoltage); // reads the value of the fan voltage (value between 0 and 1023)
 open = mapHatchState(fanVoltage);

 
 setHatch(open);
 delay(15); // waits for the servo to get there
}

Software: Hysterese

Mit der Funktion mapHatchState lege ich den Sollzustand der Klappe in Abhängigkeit der Spannung am Lüfter fest.

Liegt die Spannung lange genug unter etwa 4.8V, so schließt die Klappe oder behält ihren geschlossenen Zustand bei. Liegt sie darüber, soll die Klappe geöffnet werden. Der Dauer des Zustandswechsels hängt von der Spannung selbst ab; bei Werten weit ab vom Schwellwert läuft der Aggregator schneller voll und der Klappenzustand wird ebenfalls zügiger verändert.

bool mapHatchState(uint16_t voltage){
 #define maxint 32767 - 1024
 #define minint -32768 + 1024
 static int16_t vAggregate{0};
 static bool hatchOpen{false};

 // Divider VCC 33k T 22k GND, 12V fan will yield 4.8V at divider --> 983 digit
 // So a value of 410 is roughly 5V which allows Fan start + hatch open
 vAggregate = vAggregate + voltage - 410;
 if (vAggregate > maxint) {
 vAggregate = maxint;
 hatchOpen = true;
 }
 else if (vAggregate < minint) {
 vAggregate = minint;
 hatchOpen = false;
 }

 return hatchOpen;
}

Software : Klappe bewegen

Die Funktion setHatch() prüft den gewünschten Zustand der Klappe und bewegt sie, falls sie vom aktuellen Zustand abweicht, dort hin. Dabei wird dem Servo mittels write() ein Zielwinkel vorgegeben, der eingestellt und gehalten werden soll. Die Bewegung geschieht graduell und über die Iteration von hatchState, da die Klappe sich mir sonst viel zu ruckartig und schnell bewegt.

Your browser does not support the video tag.

Test der Klappensteuerung durch Verstellen der Lüfterspannung

void setHatch(bool open){
 static uint8_t hatchState{180}; // variable to capture current position, default closed
 static bool wasMoving{false};
 bool isMoving{false};

 if (open && (hatchState > 0)){
 hatchState--;
 isMoving = true;
 } else if (!open && (hatchState < 180)) {
 hatchState++;
 isMoving = true;
 }


 if (!wasMoving && isMoving) {
 servoHatch.attach(portServo); // connect servo on start
 }
 else if (wasMoving && !isMoving) {
 servoHatch.detach(); // disconnect servo on finish
 }

 servoHatch.write(hatchState);
 wasMoving = isMoving;
}

Die Funktionen attach() und detach() definieren den Signalausgang zum Servo, ordnen also den Pin des Microcontrollers intern dem Servo so zu, wie er tatsächlich verdrahtet ist. Bei meinen Experimenten fand ich heraus, dass das Servo im Stillstand bei detached nur wenig Energie benötigt - viel weniger, als wenn ich es attached lasse und nur kein weiteres Bewegungssignal sende. Daher melde ich es für jede Bewegung an und danach wieder ab.

Ergebnis

Ich erhalte einen schön aufgeräumten, modernen PC. Mittels diverser Bloatware-Lösungen (die ich nach getaner Arbeit direkt wieder deinstalliere) schaffe ich es nach einigem Fluchen, alle LED-Farben aufeinander abzustimmen. Besonderes Highlight ist die automatische Klappe, welche bei höherer CPU-Last samt Lüfter aktiviert wird.

QR-Codengrave

Schallbert — Mon, 01 Jan 0001 00:00:00 +0000

Projekt-Steckbrief

Schwierigkeitsgrad: Schwer 4/5
Kosten: 0€
Zeitaufwand: ~50h

Die Idee

Ein Freund bat mich, einen Bierdeckel für ihn anzufertigen. Ein eigenes Logo, ein paar Buchstaben. Nichts allzu Schweres. Auf der Rückseite wollte er einen QR-Code eingravieren lassen, der einen Link zu seiner Website enthält.

Ich habe also einen QR-Code mit einem Standard-Webtool erstellt und als .svg exportiert. Leider müsste ich in meinem CAM jedes einzelne Pixel anklicken und eine Carve-Action für dieses Pixel erstellen, was einige Minuten meiner Zeit für Auswahl-Klick-und-Parameter-Wähl-Prozeduren in Anspruch nehmen würde. Außerdem müsste ich einen Gravurstichel mit tiefenvariabler Gravur verwenden, um ein quadratisches Pixel zu erhalten, was viel mehr Bearbeitungszeit erfordert als eine runde Darstellung.

An diesem Punkt beschloss ich, viele, viele weitere Stunden meiner Zeit auf dieses Problem zu werfen und eine allgemeine Lösung für QR-Code-Gravuren zu entwickeln - eine Software namens QR-codengrave.

Erste Schritte

Spezifikation

Das, was ich mit dem Tool erreichen wollte:

Muss es können:

Texteingabe verarbeiten und in einen QR-Code konvertieren. Der Benutzer muss keine zusätzliche Konfiguration vornehmen.
Bietet die Option zur Verwaltung verschiedener CNC-Werkzeuge.
Ermöglicht Eingabe von Gravurparametern: Gravurtiefe, Eilgangbewegung im Job, Überflughöhe
Ermöglicht Eingaben für benutzerdefinierte XY0-Offsets für Werkstücke
Vektorisiert die Pixelausgabe des QR-Codes
Kann Pfade aus den Vektoren erstellen lassen, beginnt der Einfachheit halber mit einer Spirale nach innen
Übergabe der Pixellinien an ein Modul, das die Parameter des ausgewählten Werkzeugs verwendet, um Maschinenbahnen zu erstellen
Maschinenbahnen in G-Code konvertieren, der später von meiner Maschine interpretiert werden kann.
Gründliche Überprüfung der Algorithmen mit automatisierten Unit-Tests (bitte keine Abstürze in der realen Welt)
Bietet eine grafische Benutzeroberfläche, um die Parametereingabe so einfach wie möglich zu machen.

Optional

Eine Continuous-Integration-Pipeline sowohl für meine IDE als auch für Github-Aktionen erstellen
Eine Continuous-Deploy-Pipeline für meine IDE (PyInstaller) und Github-Aktionen (Artefakte, Releases) erstellen
Integrationstests für die GUI hinzufügen
Optimieren des Algorithmus zur Pfaderzeugung, da die “nach innen gerichtete Spirale” eine hohe Fertigungsqualität hat und schön anzusehen ist, aber nicht sehr effizient mit der Zeit umgeht.

Unbekannte

Zu Beginn dieses Projekts hatte ich einige offene Fragen und Risiken, die die Nutzbarkeit des Programms hätten einschränken oder sogar das gesamte Projekt undurchführbar machen können. Sie haben sich alle als falsch herausgestellt (zum Glück), aber dennoch sind hier die Risiken, die meine ganze Arbeit unbrauchbar hätten machen können:

Kameras lesen keine runden Punkt-als-Pixel-QR-Codes.
Der Kontrast, den meine Graviermaterialien bieten, ist zu gering, so dass das Lesen der Codes schlecht oder gar nicht funktioniert.
Die Bearbeitungszeit könnte sehr hoch sein, was das Projekt unwirtschaftlich machen würde.
Beschränkungen der Programmierwerkzeuge oder meiner Programmierfähigkeiten könnten die Entwicklungszeit so verlängern, dass es sich nicht lohnt, weitere Anstrengungen zu unternehmen.

Daher beschloss ich, Unit-Tests zusammen mit dem Code zu schreiben, um ein schnelles Feedback darüber zu erhalten, ob mein Code das leisten kann, was er soll. Außerdem habe ich die Funktionalität des Programms auf eine Gravurstrategie beschränkt und die GUI so gestaltet, dass sie nur eine Vorschau des QR-Codes anzeigt, nicht aber XY-Offsets oder anderen Schnickschnack.

Programmiersprache

Ich nahm einige Blätter Papier und notierte mir das Wesentliche.

Ein Modul soll sich um die Erstellung eines QR-Codes aus einer Texteingabe kümmern, ein anderes soll Vektoren und Pfade erzeugen, um diesen QR-Code zu gravieren, und eine GUI in der Mitte soll die Texteingabe, eine Bearbeitungsvorschau und Eingabemöglichkeiten für Fräswerkzeuge, Gravurparameter und Werkstückversätze enthalten.

Ich hatte ein paar Programmiersprachen zur Auswahl, die ich gut genug “spreche”:

C++ mit QT-Framework
Java
Python mit dem Tkinter-Framework

Ich entschied mich für die - meiner Meinung nach - einfachste Lösung, um so schnell wie möglich einen lauffähigen Prototyp zu haben: Python mit Tkinter. Ich kenne Tkinter von einem meiner früheren Projekte und obwohl es seine Einschränkungen hat, ist es immer noch leistungsstark genug und schnell zu verwenden.

Konzeptphase

Nach etwas Recherche fand ich eine ziemlich gute Open-Source-QR-Code-Bibliothek im Internet, die auch in Python verfügbar ist. Auf der Grundlage ihrer Ausgaben habe ich einen Vektorisierungsalgorithmus erstellt, der die QR-Code-Bibliothek abfragen kann, um die Werte der Pixel des QR-Codes in einer Scanzeile zurückzugeben:

 def _qr_bitstream_from_line(self, line):
 """Creates a bitstream from an input line of a QR-code data representation
 :param line: a QR-code data representation (line of bits within the QR-code)
 :returns bitstream: returns an array of bits reflecting the QR code's state at the respective
 point of the line."""
 bitstream = []
 if line.get_direction() == Direction.RIGHT:
 for x in range(line.get_p_start().x, line.get_p_end().x + 1):
 bitstream.append(self._qr.get_module(x, abs(line.get_p_start().y)))
 if line.get_direction() == Direction.LEFT:
 for x in range(line.get_p_start().x, line.get_p_end().x - 1, -1):
 bitstream.append(self._qr.get_module(x, abs(line.get_p_start().y)))
 if line.get_direction() == Direction.UP:
 for y in range(line.get_p_start().y, line.get_p_end().y + 1):
 bitstream.append(self._qr.get_module(line.get_p_start().x, abs(y)))
 if line.get_direction() == Direction.DOWN:
 for y in range(line.get_p_start().y, line.get_p_end().y - 1, -1):
 bitstream.append(self._qr.get_module(line.get_p_start().x, abs(y)))
 return bitstream

Dann musste ich aus diesen Linien Vektoren erstellen, so dass aufeinanderfolgende Pixel derselben Farbe zu einer Linie zusammengefügt werden konnten, die viel schneller herzustellen ist als einzelne Punkte:

 def _vectorize_bitstream(self, bitstream):
 """Creates a QrLineData object from an input bitstream
 :param bitstream: an array of bits = a line of the QR-code
 :returns line_vector: A list of QrLineData objects"""
 line_vector = []
 data = QrLineData(bitstream[0], True)
 for bit in range(1, len(bitstream)):
 if bitstream[bit] == data.get_state():
 data.add_length()
 else:
 line_vector.append(data)
 data = QrLineData(bitstream[bit])
 if not data.get_state():
 data.finalize()
 line_vector.append(data)

 return line_vector

Diese beiden Methoden würden nun von einer übergeordneten Methode aufgerufen werden, die einen spiralförmigen Pfad durch den QR-Code kennt. Meine erste GUI hatte nur drei Elemente: Ein Eingabefeld für den Text, der in einen QR-Code umgewandelt werden sollte, eine Schaltfläche, um den Algorithmus auszuführen, und eine Zeichenfläche, auf der der Gravurpfad des Algorithmus ausgegeben werden sollte.

Ich das Modul Turtle verwendet, um den vektorisierten QR-Code-Pfad zu zeichnen, ein Tool, das für Schülerinnen und Schüler geschrieben wurde, die sich in Programmiersprachen wie Python einarbeiten. Es ist zwar langsam, aber einfach einzurichten, so dass mir das für den Anfang genügte. Ich habe für’s Erste hart kodiert, um Zeit zu sparen, und meine Schleifen sind eher C-esk als pythonisch, aber egal.

 for vect in self._spiral_path[i].get_z_vector():
 if self._stop_draw:
 break
 length = vect.get_length()
 if vect.get_state():
 self.turtle.down()
 self.turtle.forward(self.pen_size * length)
 self.turtle.up()
 else:
 self.turtle.forward(self.pen_size * length)
 self.turtle.right(90)

Dieses sehr einfache Konzept sah für mich vielversprechend aus, aber ich musste ein paar Stunden daran feilen, weil meine anfängliche Ausgabe wie folgt aussah:

Your browser does not support the video tag.

QR-codengrave GUI test

Nach einer Weile konnte ich jedoch zuverlässig einen (21x21 Pixel) QR-Code auf den Bildschirm zeichnen und die Kamera meines Smartphones verwenden, um den Link zur Webseite zu erhalten. 🥳 Yeah!

Your browser does not support the video tag.

QR-codengrave Vektorerzeugung funktioniert

Unit-Tests

Die “Plattform”-Teile - Klassen vectorize_qr und machinify_vector - enthalten beide eine Menge überprüfbarer Berechnungen und Geschäftslogik. Deshalb sind meine Tests mit Pythons Standardmodul unittest schnell und einfach zu schreiben. In diesem Beispiel überprüfe ich, ob die von mir erstellte Linienklasse eine Länge (n+1 Stil) korrekt berechnet:

class TestLine(unittest.TestCase):

 def test_line_x_calculates_valid_length(self):
 line = Line(Point(0, 0), Point(5, 0))
 self.assertEqual(6, line.get_abs_length())

Aber es wurde schnell komplexer, als ich testen wollte, ob die Ausgabe der QR-Code-Generatorbibliothek in meinem Programm korrekt verarbeitet wird. Dazu musste ich die Bibliothek in meine zu testende Klasse einbinden, damit ich eine Mock-Implementierung einschleusen konnte, die dann im Test abgefragt wird.

Dieses Muster der Abhängigkeitsinjektion ist der Vorgehensweise in C++ sehr ähnlich, wo ich viel mehr Erfahrung habe (siehe ein Projekt hier oder ein anderes hier, zum Beispiel), nur dass in Python viel weniger Boilerplate-Code nötig ist, um dorthin zu gelangen. Ein paar Suchvorgänge im Internet und schon war der folgende Testfall geschrieben:

 def test_bitstream_qr_input_loop_xpos_correct(self):
 mock_qr = QrCode.encode_text("schallbert.de", QrCode.Ecc.MEDIUM)
 mock_qr.get_module = MagicMock()
 cam = VectorizeQr(mock_qr, 1)
 cam._qr_bitstream_from_line(self.test_line_x)
 mock_qr.get_module.assert_called_with(20, 0)

Ich injiziere die “echte” QrCode-Bibliothek, aber mit einer Mock-Methode, die für mich von Interesse ist, get_module(). In dem Test stelle ich sicher, dass die Methode mit den erwarteten Parametern aus meiner zu testenden Klasse aufgerufen wird.

Mit solchen Tests kann ich sichergehen, dass die Bausteine meines Algorithmus wie vorgesehen funktionieren und dass Regressionen schnell gefunden werden können.

Der lange Weg zum Produkt mit Minimalanforderungen

Beflügelt von diesem schnellen Erfolg, ging ich aufs Ganze. Vor der Implementierung des G-Code-Generators musste ich einen Werkzeugselektor entwerfen, da ich die Werkzeugeigenschaften zur Verfügung haben musste, bevor ich die Abmessungen und die Werkzeuggeschwindigkeit / den Vorschub für die QR-Code-Gravur einstellen konnte.

Nach einigen erfolglosen Versuchen im Hauptfenster entschied ich, dass das Werkzeugkonfigurationsfenster stattdessen ein Dialog sein sollte (den Tkinter Toplevel nennt), so dass die Werkzeugparameter eingegeben und nach Abschluss an die Haupt-GUI zurückgeschickt werden können. Ich habe den Dialog modal gemacht mit

 self._dialog.grab_set()

So hat er immer den Fokus, damit nicht mehrere Instanzen dieses Fensters gleichzeitig vorhanden sein können. Ich habe die konfigurierten Werkzeuge in einer nummerierten Liste gespeichert, so dass die Anwendung, sobald sie gefüttert wurde, die Liste zur Verfügung stellt, damit der Benutzer das gewünschte Werkzeug für den Job aus einem Dropdown-Menü auswählen kann.

In diesem Schritt musste ich zwei Dinge implementieren:

Überprüfungen für Wertetyp und -bereich
Ein Persistenzmodul, so dass die eingegebenen Tools einen Neustart der Anwendung überleben würden.

Überprüfungen von Wertetyp und -bereich

Dies könnte mit einem Ereignis-Auslöser innerhalb des Eingabefeld-Widgets wie folgt erreicht werden:

 reg = config_tool_frame.register(validate_number)
 tool_nr_entry.config(validate="key", validatecommand=(reg, '%P'))

Anschließend wird der eingegebene Wert an einen einfachen Validator übergeben, der lediglich versucht, den Eingabewert in einen Float-Wert umzuwandeln und False zurückgibt, wenn dies einen Fehler erzeugt,

def validate_number(entry):
 """Helper function that is used in validators to check
 that the entered keystroke is a number"""
 if entry == '':
 return True
 try:
 float(entry)
 return True
 except ValueError:
 return False

Eine Prüfung ob der Wert plausibel ist erfolgt erst, wenn die Schaltfläche “OK” gedrückt wird, um die eingegebenen Daten an die Anwendung weiterzuleiten. Bei Überschreitung des Bereichs würde ein Warn-Popup (Modul tkinter.messagebox) erscheinen, das auf das mögliche Problem hinweist.

Persistenz

Das Persistenzmodul war etwas schwieriger zu implementieren. Ich entschied mich dafür, ein Element zu erstellen, das C++-Kenner eine statische Klasse nennen würden, d.h. eine Klasse, die nicht instanziiert werden muss, um eine ihrer Methoden aufzurufen. Diese Klasse hat nur zwei Methoden namens load und save, die das tun, was ihr Name andeutet, indem sie Pythons pickle Modul zur Serialisierung von Objekten verwenden, die ich speichern wollte. In Python habe ich den Dekorator @classmethod verwendet, um die statische Natur dieser Klasse zu kennzeichnen.

So einfach kann die Serialisierung von Daten mit den richtigen Werkzeugen werden:

 with open(app_persistence_path, 'wb') as file:
 pickle.dump([cls._tool_list,
 cls._z_params,
 cls._xy0],
 file, protocol=2)

Als dies zuverlässig funktionierte, fügte ich ein Widget zur Konfiguration der Gravurparameter hinzu. Von Nachteil bei statischen Methoden ist, dass sie nur schlecht unit-testbar sind, weil Dependency Injection hier nicht funktioniert; sie sind ja instanzlos. Es bliebe mir nichts anderes üblich als “Fakes” zu schreiben, die im Testfalle die echte Speicher- bzw. Ladefunktion ersetzt.

Gravur-Parameter

Um den G-Code aus meinen QR-Code-Daten zu generieren, benötigte ich nicht nur Werkzeug- und Geschwindigkeits-/Vorschubdaten, sondern ich musste auch wissen, wie tief ich gravieren wollte, wie weit das Werkzeug bei Eilgängen über der Werkstückoberfläche schweben sollte und welche Sicherheitshöhe die CNC für die Rückkehr zum Ursprung oder zur Ausgangsposition verwenden sollte.

Es wird auf ähnliche Weise wie das Dialogfeld “Werkzeugkonfiguration” erstellt und verwendet dieselben Mechanismen zur Überprüfung von Typ und Bereich. Der einzige Unterschied besteht darin, dass er nicht über einen Klick auf eine Schaltfläche, sondern direkt über das zugehörige Textfeld gestartet wird, das den aktuellen Wert der Gravurparameter im Hauptfenster anzeigt.

Werkstück XY Nullpunktverschiebung

Der Konfigurationsdialog für den Werkstückversatz enthält einige Radiobuttons zur Auswahl der gängigsten Werkstückursprünge und eine benutzerdefinierte Option, mit der der Benutzer Werte für den X- und Y-Achsennullpunkt des Werkstücks eingeben kann. Eine Funktion im Hintergrund berechnet den erforderlichen Versatz relativ zum Startpunkt der Gravierspirale.

Normalerweise würde ich nicht wollen, dass die grafische Benutzeroberfläche Berechnungen durchführt oder viel Verzweigungslogik verwendet, da dies schwieriger zu verifizieren ist, weil die Test Fixtures damit größer und schwieriger zu warten werden. In diesem Fall habe ich mich jedoch entschieden, die Offset-Berechnung mit Hilfe einer Wertetabelle innerhalb des GUI-Moduls durchzuführen, um zu vermeiden, dass alle GUI-Module zur Plattform und zurück kommunizieren müssen (und das durch 4 Klassen hindurch).

 def _get_xy_offset(self, offset):
 """calculates an XY coordinate offset from a preset point, taking the selected tool diameter into account.
 :param offset the selected offset from the above enum class
 :returns a XY Point where XY0 is assumed for the engraving."""
 qr = self._qr_dimension
 d = self._tool_diameter
 offsets = {Offset.CENTER: Point((d - qr) / 2, (qr - d) / 2),
 Offset.TOPLEFT: Point(d / 2, -d / 2),
 Offset.TOPRIGHT: Point(d / 2 - qr, -d / 2),
 Offset.BOTTOMLEFT: Point(d / 2, qr - d / 2),
 Offset.BOTTOMRIGHT: Point(d / 2 - qr, qr - d / 2)
 }

 if offset in offsets:
 return offsets[offset]

Erstes Release V1.0

Die erste Version ist minimalistisch. Sie erfüllt ihren Zweck, hat aber noch einige Fehler (z.B. eine Fehlermeldung, wenn kein Werkzeug in der Auswahlliste ausgewählt ist) und Unzulänglichkeiten (z.B. ist das Zeichnen eines QR-Codes sehr langsam, beim erneuten Zeichnen kippt der QR-Code ein wenig usw.), aber sie sollte einfach funktionieren und dem Benutzer helfen, die schlimmsten Fehler auf seinem Weg zu vermeiden.

Ich habe die Ausführung auf meiner CNC-Maschine getestet und zumindest mein Handy ist in der Lage, zu einer Website zu navigieren, indem es einfach die Kamera auf das Werkstück hält 📱.

Automatisierte Integrationstests für die GUI: Frustrierende Arbeit

Als meine erste Version herauskam, wollte ich einige Tests für die grafische Benutzeroberfläche hinzufügen. Da ich es nicht geschafft habe, dort absolut keine Geschäftslogik zu haben, wollte ich zumindest Bereichsprüfungen sowie die Kommunikation mit der Plattform überprüfen, um sicherzustellen, dass alles wie vorgesehen funktioniert.

Aufgehängt in der Messagebox

Zu diesem Zweck schrieb ich einige Tests, die auf meinem lokalen Rechner liefen, mit dem Nachteil, dass, wenn der Test auf einen Warn- oder Fehlerdialog messagebox.showinfo / messagebox.showerror stieß, eine manuelle Benutzerinteraktion unbedingt erforderlich war, damit das Fenster geschlossen und der Test fortgesetzt werden konnte.

Ich habe keine einfache Möglichkeit gefunden, dieses Problem zu umgehen, da die Messagebox als unabhängiges Widget agiert, das nicht einfach manipuliert werden kann. Auch meine Versuche, einen Tastendruck als Seiteneffekt aus dem Test heraus auszulösen, waren nicht von Erfolg gekrönt (und wären am Ende wohl auch keine saubere Lösung gewesen).

Meine Lösung nach ein paar Stunden gemurmelten Fluchens ist, dass die Messagebox-Widgets in die GUI-Klassen injiziert werden, die sie verwenden:

@patch('src.gui.gui_tool_manage.GuiToolManager')
 def setUp(self, mock_guitoolmanager):
 tk.Tk() # required to have tk variables properly instantiated
 self.mock_guitoolmanager = mock_guitoolmanager
 self.mock_msg = MsgBox()
 self.mock_msg.showinfo = MagicMock()
 Persistence.set_mock_msgbox(self.mock_msg)
 self.config_tool = GuiConfigureTool(self.mock_guitoolmanager, self.mock_msg, {'padx': 5, 'pady': 5})

Auf diese Weise kann ich mock_msg in die Gui-Klasse werfen, so dass nicht die echte showinfo genommen wird, sondern das Mock weiß, ob er wie vorgesehen aufgerufen wurde. Ich könnte ihr zur Testvorrichtung hinzufügen, so dass mein Testcode selbst DRY bleiben könnte.

Es fügt dem Konstruktor mehr Argumente hinzu und delegiert die Instanziierung an eine Klasse höherer Ebene, aber die Verwendung innerhalb der zu testenden Klasse bleibt trivial. Im Einsatz unter Realbedingungen agiert die Schnittstelle wie ein Proxy, der dann die echte showinfo-Methode des Messagebox Objektes aufruft.

Probleme mit statischen Klassen

Da die Persistenzklasse, die ich oben erwähnt habe, statisch ist, d.h. keine Instanziierung erfordert, hatte ich das nächste Problem von Anfang an in meinen Code eingebaut: Ein Integrationstest würde nun versuchen, in eine tatsächliche “persistence.dat”-Datei zu schreiben, eine Abhängigkeit, die ich nicht haben wollte, insbesondere nicht in der kontinuierlichen Integration (CI) - denn dort würde das Programm die Rechte für das Schreiben auf Festplatte nicht besitzen.

Also habe ich Persistence in die Haupt-GUI-Datei verschoben, die nicht getestet werden würde, und folgte damit Steven Andersons großartigem Blogbeitrag. Die Haupt-GUI sollte ohnehin nur deklarativen Code enthalten, und die geladenen Daten werden dann in die Klassen kaskadiert, die sie verwenden, anstatt in die Persistenzklasse, die die eigentliche Lade-/Speicheroperation durchführt.

Zukünftige Versionen

Folgendes ist für spätere Releases geplant:

Die Zeichnungsgeschwindigkeit des QR-Codes muss erhöht werden
Grafikfehler (Skalierung, Kippen) und unscharfe Ränder des Zeichenbildschirms sollen behoben werden
CNC-Bahnen sollen optimiert werden, um die Fertigungszeit zu verringern
Fehlerbehebungen

Zumindest wenn es welche gibt; mal sehen, wie oft ich dieses Tool benutzen werde. Die Dinge, die mich am meisten stören, werden wahrscheinlich zuerst behoben werden.

Ach ja, noch etwas: Danke für’s Lesen des gesamten Artikels. Zur Belohnung gibt es eine Kopie QR-codengrave kostenlos zum Herunterladen. Es kann für den privaten Gebrauch gern verwendet werden. Falls Sie eine kommerzielle Nutzung planen, lassen Sie es mich bitte im Voraus wissen.

Tonuino - alternative Firmware

Schallbert — Mon, 01 Jan 0001 00:00:00 +0000

Projekt-Steckbrief

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

Galerie

Die alternative Tonuino-Firmware im Einsatz.

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

Anwendungsbeispiel mit Microcontroller unter Verwendung meiner ClickEncoder-Bibliothek

Anwendungsbeispiel mit Arduino in einem Gitarrenverstärker

Gesteuert wird der Player in diesem Fall mit drei Tasten.

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

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

Motivation

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

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

Schwierigkeiten

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

Übersicht

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

Funktionen

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

Nicht enthaltene Funktionen

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

Dokumentation

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

Projekt Modulübersicht

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

Verwendete externe Bibliotheken

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

Klassendiagramme

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

Software-Modulübersicht

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

Los geht’s!

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

Testen

Unit-Tests

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

Akzeptanztests

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

Switching ON

System Pre: System is OFF

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

Switching OFF

System Pre: System is ON

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

Play Help Prompt

System Pre: System is ON

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

Behavior without Tag

System Pre: System is ON, no Tag present

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

Behavior with Tag

System Pre: System is ON, linked Tag available

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

Behavior with unlinked Tag

System Pre: System is ON

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

Hardware

Materialliste

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

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

Zusätzliche Bauteile und Tipps

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

Schaltplan

Umzug von Github Pages

Schallbert — Mon, 01 Jan 0001 00:00:00 +0000

Projekt-Steckbrief

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

Motivation

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

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

Überblick

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

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

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

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

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

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

Konfiguration meines Servers

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

SSH auf dem Server einrichten

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

Sodann erstelle ich mir ein neues Schlüsselpaar per Befehl

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

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

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

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

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

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

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

Docker installieren 🐳

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

caddy installieren 🛒

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

#caddy2/docker-compose.yml

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

networks:
 caddy-proxy:
 external: true

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

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

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

Sieht gut aus!

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

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

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

Test-Website erstellen 🧪

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

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

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

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

Und dort dann ein unverkennbares Hello World eintragen:

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

Speichern, fertig.

Das Stammverzeichnis von caddy sieht nun so aus:

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

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

docker compose up -d

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

[+] Running 1/1
 ✔ Container caddy Started

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

Gitea installieren 🍵

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

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

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

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

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

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

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

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

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

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

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

docker compose up

So sieht die Konsolenausgabe bei mir aus:

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

Webzugriff einrichten

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

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

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

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

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

Gitea per Web-Oberfläche konfigurieren

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

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

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

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

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

Jetzt schnell prüfen, ob auch alles funktioniert:

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

Perfekt.

Gitea-Konfiguration per `app.ini` fertigstellen

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

docker compose down

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

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

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

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

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

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

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

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

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

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

[attachment]
PATH = /data/gitea/attachments

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

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

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

[lfs]
PATH = /data/git/lfs

[mailer]
ENABLED = false

[openid]
ENABLE_OPENID_SIGNIN = true
ENABLE_OPENID_SIGNUP = true

[cron.update_checker]
ENABLED = false

[repository.pull-request]
DEFAULT_MERGE_STYLE = merge

[repository.signing]
DEFAULT_TRUST_MODEL = committer

[oauth2]
JWT_SECRET = <redacted>

[actions]
ENABLED = true

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

Nun kann der Container neu gestartet werden:

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

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

Action Runner einrichten 🏃

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

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

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

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

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

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

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

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

Funktionsprüfung Runner

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

Commit, push, und - nichts.

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

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

Wahnsinn! 🥳

Zwischenfazit

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

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

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

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

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

Update: Server-Architektur im Januar 2024

Ich habe den Server inzwischen mehrfach um Peripheriefunktionen erweitert. So habe ich mich um Sicherheit und Backups ebenso gekümmert wie um automatische Updates, wobei mir die Kapselung durch Docker nicht nur einmal auf die Füße gefallen ist und einiges an Zeit gekostet hat. Auch wenn noch immer nicht alle Aspekte vollständig abgedeckt sind (Benachrichtigungen sind z.B noch ein offenes Thema), komme ich meinem Ziel, einen weitgehend selbstständig laufendes System zu schaffen, spürbar näher.

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

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

Software on Schallberts Blog

Umzug von Jekyll zu Hugo

Projekt-Steckbrief

Warum überhaupt wechseln?

Weitere Schwierigkeiten mit Jekyll

Die Chancen

Das Migrationswerkzeug

Anpassen der Front Matter

Konfiguration des Theme

Organisation der Ordnerstruktur

Vorher

Nachher

Manuelle Anpassungen: Shortcodes

Hugo

Jekyll

image

audio

video

links

Manuelle Anpassungen: Partials

index

math

cover image

Manuelle Anpassungen: Layouts

baseof.html

list.html

single.html

Direkter Vergleich

Größe

Komplexität

Auslieferung/Continuous Deployment

htmltest-Konfiguration für Hugo

htmltest

Ausgabe in Datei umleiten

Fehlerkategorien

Das Log bereinigen

“Missing trailing slash”: Fehlerbehebung per Markup

Manuelles Suchen und Beheben

Das Ergebnis

Hugo Multi-Lang: Interne Permalinks

Konfiguration

Das Problem mit der Standardsprache

Lösung: Sprachabhängige Link-Prefixes

Standardsprache auslesen

Code für render-link.html

Zusatzfunktionen

Richtig auflösende Permalinks auf Überschriften

Funktioniert so noch nicht.

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

Scheitern von SSH-Verbindungen

Problem: “No Route To Host”

Problem: Connection Refused

Problem: Too Many Authentication Failures

Server-Anmeldelimit prüfen

Git-Config überprüfen

Problem: Permission Denied (publickey,password)

Problem: Agent Refused Operation

Hardware Security Key: SSH einrichten

Motivation

SSH-Zugriff für Hardware Security Keys einrichten

Was so nicht funktioniert

Bedeutung des Kommandos und der wichtigsten Optionen

Woran hat es gelegen?

Was hingegen funktioniert

Was verify-required benötigt

Installation von ssh-askpass

Nervig: Gnome-Popup “Allow inhibiting shortcuts”

Übertragung auf Windows-Systeme

VPS: Vorsicht bei Schlüssel-Ersatz

Neue Schlüssel manuell auf VPS ablegen

Schlüssel erfolgreich übertragen?

Auf direktem Wege ohne ssh-copy-id

Überlegungen zu Komfort und Bedienbarkeit

Hardware Security Keys

Begriffsabgrenzung: TPM und HSK

Was bisher geschah

Zielvorstellung

Yubikey

Yubico Authenticator

Konzept des HSK

Was `verify-required` benötigt

`Gemfile.lock` für verschiedene Umgebungen optimieren

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

Giteas act_runner rootless ausführen

Gefahr durch `docker.sock`

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

Ordner `filter.d`

Datei `jail.local`