Statisches Hosting mit GitHub Pages

22 September, 2022 von Jörn Bernhardt

Wie in dem vorherigen Blogpost beschrieben, haben statische Seiten einige Vorteile. In diesem Artikel wird beschrieben, wie eine statische Seite mit GitHub ausgeliefert wird und wie Inhalte aus "dynamischen" Quellen genutzt werden.

Generell gibt es auf GitHub zwei Möglichkeiten, eine Webseite zu hosten:

In einem Unterordner /docs eines Branches (Standardmäßig vom main Branch)
In einem dedizierten Branch, der konfiguriert werden kann (gh-pages)

In beiden Fällen muss die statische Webseite im Git-Repository abgelegt sein. Die Konfigurationsmöglichkeit befindet sich in den Einstellungen des jeweiligen Repositories unter dem Punkt "Pages".

Wird eine reine HTML / CSS / JS Seite gebaut, ohne die Notwendigkeit, sie vorher bauen zu müssen, so ist ein Ordner dafür ausreichend. Sollte aber ein Build-Prozess notwendig sein, ist es empfehlenswert, das Ergebnis des Build-Prozesses in einem separaten Branch zu speichern und diesen zu verwenden. Das hat den Vorteil, dass die Änderungen an dem Quellcode schnell ersichtlich sind und die daraus resultierenden Build-Artefakte das jeweilige Update nicht unübersichtlich gestalten.

Das Vorgehen wäre also:

Einmal die Seite "bauen" lassen (npm run build, oder was im eigenen Projekt dafür verwendet wird)
Das Ergebnis im konfigurierten Git-Branch ablegen (gh-pages)
Den konfigurierten Branch auf GitHub hochladen (git push)

Es gibt Skripte, die diesen Weg vereinfachen, zum Beispiel das NPM Paket gh-pages, welches auch ein Kommandozeilentool mitliefert. Damit kann Schritt 2 und 3 zu einem gh-pages -d build Kommando (oder ähnlichem) zusammengefasst werden.

Fallstricke durch Jekyll, auch wenn es nicht genutzt wird

GitHub hat noch eine weitere Besonderheit: Die Webseite wird einmal mit dem statischen Webseiten-Generator Jekyll gebaut. Die Seite kann entsprechend so aufgebaut werden, dass Jekyll beispielsweise Markdown-Dateien und ähnliches automatisch konvertiert. Das bedeutet aber auch, dass bestimmte Datei- und Ordnernamen eine spezielle Bedeutung bekommen. Fangen beispielsweise Ordner oder Dateinamen in der fertig gebauten Version mit einem Unterstrich an (_assets), so werden diese später nicht direkt an den Browser ausgeliefert, sondern sind für Jekyll in dessen Build-Prozess geplant.

Im Regelfall ist das kein Problem, aber es kann zu unerwarteten Nebenwirkungen führen. Wird eine Seite mit dem statischen Adapter von SvelteKit gebaut, kann das zu dem beschriebenen Problem führen. Dieser erstellt einen Ordner mit dem Namen _app, der die generierten CSS- und JavaScript-Dateien enthält, die zur Anzeige der Webseite benötigt werden. Abhilfe schafft eine Datei namens .nojekyll, die dafür sorgt, dass Jekyll nicht ausgeführt wird. Diese müssen sich in dem Ordner und dem Branch befinden, welche in der GitHub Pages Konfiguration gesetzt wurden. Im angesprochenen Fall von SvelteKit muss diese Datei also im static Ordner liegen. Die Datei selbst benötigt keinen Inhalt - eine leere Textdatei reicht dafür.

Sobald GitHub Pages aktiviert ist, kann man in dem Tab "Actions" im Repository den Status der Auslieferung sehen. GitHub führt dazu die Action "pages build and deployment" aus. Sobald diese fertig ist, ist die Seite unter <username>.github.io/<repo-name> erreichbar.

Unterschiede bei lokaler Entwicklung und GitHub Pages

Wenn bei der lokalen Entwicklung eine <domain>:<port>/ Adresse verwendet wurde, ohne den <repo-name> Teil, dann muss geprüft werden, ob alle Links noch funktionieren. Das ist häufig bei der Entwicklung mit Create-React-App oder ähnlichen Tools der Fall, die einen eigenen Development-Server bereitstellen, um Änderungen sofort auf der Seite widerspiegeln zu können. Wird die Seite auf GitHub Pages nur "halb" angezeigt, das Layout stimmt nicht und die Funktionalität ist stark eingeschränkt, dann sind meist die Links zu Styling- und Skript-Ressourcen nicht mit dem passenden base-Pfad gesetzt.

Viele Tools erlauben das Setzen diese Pfads mithilfe einer Umgebungsvariable wie PUBLIC_URL oder als Konfigurationseinstellung. Darin lässt sich das von / zu /<repo-name>/ umstellen und sollte nach dem Bau auch dort erreichbar sein.

Oft soll eine Webseite allerdings unter einen eigenen Domain oder Sub-Domain verfügbar gemacht werden. Da die Links dann normalerweise ohne /<repo-name>/ angegeben werden müssten, kann sich dieses Problem durch entsprechenden Umzug ebenfalls lösen lassen.

Einrichtung einer eigenen Domain

Soll die Seite unter einer eigenen Domain verfügbar sein, so müssen in den Domaineinstellungen die DNS Einträge angepasst werden und für GitHub Pages eine Datei namens CNAME angelegt werden, in der der Domainname angegeben ist. Am besten werden zunächst die eigenen DNS-Einstellungen vorgenommen, so dass GitHub die (noch fehlenden) DNS-Einstellungen nicht vorher prüft und nach den Änderungen längere Zeit gewartet werden muss. In den DNS-Einstellungen für entsprechende Domain muss, im Falle einer Sub-Domain, also <name>.example.com, die CNAME Einstellung auf <username>.github.io gesetzt werden. Das gilt auch für www.example.com.

Soll example.com direkt ohne Subdomain verwendet werden, so ist der A-Record auf eine bestimmte IP-Adresse zu setzen. Die genauen Einstellungen sind in der GitHub Pages Dokumentation zu "apex domains" zu finden. In jedem Fall sollte auch der Teil "Verify your Domain" umgesetzt werden, um mögliche Sicherheitsrisiken zu vermeiden.

Sobald die CNAME-Datei mit dem Inhalt www.example.com (oder wie die Domain heißen sollte) in entsprechendem gh-pages Branch im obersten Verzeichnis liegt (oder wie die GitHub Pages sonst vorher eingestellt wurden), sollte die Seite nach wenigen Minuten online ansprechbar sein.

Ein kleines Wort der Warnung bezüglich der Einstellung zur Custom Domain in GitHub Pages: GitHub macht hier nichts anderes, als selbst eine Datei namens CNAME mit entsprechendem Inhalt in den Branch und den Ordner via Git zu schreiben. Spätere Updates der Webseite können diese also wieder überschreiben. Daher sollte die Einstellung über eine CNAME-Datei durchgeführt werden, die auch mit dem eigenen Build-Prozess zusammen funktioniert.

Sind all diese Schritte getan, sollte die Seite manuell aktualisiert werden können. In einem späteren Blog-Beitrag werden wir GitHub Actions etwas genauer ansehen und zeigen, wie sich die Aktualisierung nach Code-Änderungen automatisieren lässt.

Video "Cheap hosting" YouTube Video zum Thema: https://www.youtube.com/watch?v=zjtda-WHH8c

Wer sich bis dahin nicht gedulden kann, kann hier ein Beispiel finden, wie eine statische Seite gebaut und deployed werden kann. Dazu wird statt des gh-pages NPM Pakets eine GitHub Action verwendet, die das Gleiche über eine GitHub Action Konfiguration erledigt.