Klonen und Bauen

Inhaltlicher Überblick

Wenn ich, DJ3EI, der Autor dieser Zeilen, aus irgend einem Grund ausfallen sollte: Hier ist beschrieben, wie es mit der Webpräsenz afubarcamp.de auch ohne mich weiter gehen kann.

Das Material dieser Seite kann auch genutzt werden, um schlicht zu spielen, oder auch, wenn jemand sich engagieren will. Etwaige Änderungsexperimente können wie hier beschrieben mit dem eigenen Rechner ausprobiert werden und, wenn ein Vorschlag für die offizielle Seite daraus werden soll, kann mir das Ergebnis dann per Email geschickt werden. (Git-Wissende können Texte für solche Emails mit git format-patch erzeugen.)

Technischer Überblick

Seit März 2022 wird diese Webseite mit einem “static site generator” erzeugt. (Die Vorläuferimplementierung basierte auf Wordpress.)

Die “Sourcen”

Die Texte (“Sourcen”) werden dazu zunächst als Markdown-Dateien verfasst. Das sind Textdateien, die sich mit einem einfachen Texteditor bearbeiten lassen. Diese Dateien liegen dann zunächst auf der Festplatte des PCs des AfuBarcamp-Autors.

Das Generieren der Website

Mit Hilfe von Pelican, einer Python-basierten Software, wird aus diesen Textdateien die eigentliche Website erzeugt. Das passiert ebenfalls zunächst nur auf dem PC des AfuBarcamp-Autors. Was dazu getan werden muss, wird im Folgenden beschrieben. Das sollte mit etwas Computer-Mutterwitz durchaus zu Hause am eigenen PC nachvollziehbar sein.

Versionierung

Seit Anfang 2022 wird das alles mit git versioniert. “Alles” bedeutet:

• Die Markdown-Texte.
• Andere Dateien wie z.B. Folien, PDF-Dateien und ein Video.
• Die erzeugte Webseite.
• Pelican-spezifische Dateien, die für den Erzeugungsprozess hilfreich sind.
• Das (recht schnörkellose), von mir (DJ3EI) handgeklöppelte CSS für die Formatierung der Seite.

Das Wort “versioniert” bedeutet, dass sich in Nachhinein nachvollziehen lässt, was zu welchem Zeitpunkt online war.

Bauen

Mit Pelican (unter der Regie von invoke) wird dann die Webseite gebaut. Das alles findet nur auf der eigenen Festplatte des eigenen PCs statt. Üblicherweise läuft ein kleiner Webserver auf dem eigenen Rechner los, der den üblichen Browser mit den Inhalten der Webseite bedient. Im Ergebnis sind die Inhalte von afubarcamp.de zu sehen, die kommen aber nicht aus den Tiefen des Internet vom DARC-Server, sondern von der eigenen Festplatte. Insofern kriegt auch niemand sonst das zu sehen, wenn zum Beispiel für ein Experiment ein Text geändert worden ist.

Klonen

Der Webserver liefert das Git-Archiv seines eigenen Inhalts. Wer möchte, kann sich git auf dem eigenen Rechner installieren und dann den gesamten versionierten Inhalt besorgen, indem in ein Terminal (Windows: “git shell”) getippt wird:

git clone https://afubarcamp.de/afubarcamp.git

Das erzeugt ein neues Verzeichnis afubarcamp. Alle folgenden Aktionen sollten in diesem Verzeichnis ausgeführt werden.

Installation

Um die Webseite auf dem eigenen Rechner erzeugen zu können, wird zunächst eine Installation von Python benötigt. Das Original wird derzeit gepflegt mit der Python-Version 3.11.2, aber jede spätere Version sollte auch funktionieren.

Als nächstes empfiehlt es sich, eine “virtuelle Umgebung” zu erstellen und zu aktivieren. Wie das geht, unterscheidet sich geringfügig je nach Betriebssystem, siehe die Python-Dokumentation dazu.

Mit aktivierter virtueller Umgebung und im afubarcamp - Verzeichnis werden Pelican und andere Tools, von denen Pelican abhängt, installiert mit Hilfe von

pip install -r requirements.frozen

Das dauert einen Moment und läd einiges an Software aus dem Internet nach und installiert sie in der virtuellen Umgebung. Dieser Schritt ist nur einmal nötig.

Bauen

Die Website wird nun erzeugt mit Hilfe von

invoke reserve

Es wird dann auch gleich ein Browser gestartet, der die Übersichtsseite anzeigt - die kommt jetzt nicht mehr aus dem Internet, sondern von der eigenen Festplatte.

Wird der Prozess invoke reserve nicht mehr gebraucht, kann er beendet werden durch die Tastenkombination Strg+C, ins Terminal getippt.

Änderungen am den Markdown-Dateien werden erst nach erneutem invoke reserve im Browser sichtbar.

Veröffentlichen

Das funktioniert nur auf meinem PC:

invoke publish

Damit das für eine eventuelle Nachfolgerin oder einen eventuellen Nachfolger von mir auch funktioniert:

• Auf dem PC rsync und ssh installieren.
• Der ssh-Zugang für www.afubarcamp.de muss durch die DARC-IT freigeschaltet werden. Der wiederum ist durch eine Firewall geschützt, die eine bekannte IP-Nummer sehen will (“jump host”). Ich nutze einen privaten Server mit konstanter IP-Anschrift dazu, samt passender ProxyJump-Konfiguration in meiner $HOME/.ssh/config.

Bekannte Probleme

CSS

Die CSS-Datei bestimmt viele Details des Aussehens, der Formatierung der Seite. Die Sourcen dazu finden sich unter theme/sass/main.scss.

Ich benutze die Software dart-sass, um daraus die eigentliche CSS-Datei theme/static/css/main.css zu erstellen. Das ist nur nötig nach Änderungen an theme/sass/main.scss.

Nun ist dart-sass keine Python-Software. Sie wird mit pip nicht mit installiert. Ich habe sie einfach manuell installiert unter theme/util, siehe die README.md-Datei dort. Unter Linux funktioniert das.

Der Film

Zu Anfang jeden AfuBarcamps erkläre ich traditionell, wie ein AfuBarcamp überhaupt funktioniert und, dass unsere Regeln gegenseitigen Respekt und Toleranz erfordern. Das kostet wertvolle Zeit.

Beim Online-AfuBarcamp 25.03.2021 haben wir ausprobiert, die damalige Version der Erklärung (alles noch richtig, aber inzwischen ist noch was dazu gekommen) vorher als Video zur Verfügung zu stellen. Das hat aber nicht gut funktioniert: Bei diesem AfuBarcamp herrschte ein schlechteres Betriebsklima als gewohnt.

Seither hat dieses Repo eine Video-Datei mit an Bord von 195 MByte Größe. Eigentlich gehört so etwas in git mit Hilfe von git-lfs versioniert. Die Mühe haben wir uns nie gemacht, hauptsächlich, da wir dann eine “Large File Storage” irgendwo einrichten müssten.

Webserver als Repo-Server

Es ist möglich, einen stinknormalen Webserver als Git-Server zu gebrauchen. Genau das passiert hier. Das geht, hat aber den Nachteil, dass der Zugriff ineffizient ist.

Eine Änderung im offiziellen Repo kann mit git fetch oder git pull auf die eigene Festplatte gezogen werden. Falls es tatsächlich eine Änderung gab, saugen diese Befehle etwa 200 MByte durchs Netz, auch wenn sich nur wenige Byte geändert haben.

Teamwork

Ich mag Systeme wie Wordpress oder Typo3 nicht,

• die ohne Versionierung auskommen,
• mit denen es nicht einfach ist, fernab der Produktionsplattform und sogar ohne Internetzugang auf dem eigenen PC Texte und anderes zu entwerfen und
• die es benötigen, dass im Rahmen des Webservers ein Haufen angreifbarer Software läuft.

Das kann gerne anders sehen, wer es anders mag. Ich referiere hier nicht “gut und schlecht”, sondern nur meine persönlichen Präferenzen.

Gemäß dieser Präferenzen zu arbeiten hat einen Preis:

• Sollen Texte beigetragen werden, ist git-KnowHow nötig.
• Es bedarf einer Installation auf dem eigenen Rechner.

Die Texte dieser Webseite haben derzeit nur einen Autor (mich, DJ3EI). Wenn hier mal jemand zweites an Bord kommen wollte, wären etwas git-Kenntnisse nötig.