Hugo auf GitHub-Pages hosten

Was ist Hugo

Hugo ist ein so genannter “static site generator”. Also mit Hilfe einfacher Dateien (In diesem Fall Markdown) generiert Hugo eine statische Internetseite, die man dann ohne PHP, Java oder .NET auf einem ganz einfachen Webserver betreiben kann. Wie man damit umgeht und eine ganz neue Seite erstellt, werde ich ggf. mal in einem weiteren Blogeintrag beschreiben. Heute soll es zunächst erst mal einen Schritt weiter um das gehen, was nach der ersten lokalen Version passiert. Das bereitstellen im Internet. Und das mit ganz einfachen Mitteln und zwar GitHub-Pages.

Warum GitHub-Pages?

Eigentlich ist es eine sehr einfache Antwort. Es ist kostenlos, der Code unserer meisten öffentlich zugänglichen Projekte liegt hier eh (Also meiner bisher auf jeden Fall) und durch die Funktionen die Github bietet, kann man sogar seine eigene Domain direkt mit einbinden. Also alles was man für den Anfang braucht. Was allerdings zu beachten ist, dass wir für jeden Benutzer/Organisation nur eine GitHubPage anlegen können. Sprich wir können Github nicht für mehrere Projekte benutzen sondern “nur” für unsere persönliche oder organisations Webseite.

Was brauchen wir?

Als erstes benötigen wir einen GitHubAccount. Das ist ja schon mal recht einfach. Nun geht es weiter indem wir ein privates repo anlegen. Warum privat? Naja hier liegen alle Dateien, die wir für unsere Webseite brauchen, inklusive Skripte die wir ggf. nicht komplett öffentlich der Gemeinschaft präsentieren möchten. Und hier werden wir auch später unsere GithubActions anlegen, die es uns ermöglichen nach einem commit in unserem Repo direkt die Webseite zu aktualisieren. Danach brauchen wir aber noch ein zweites, diesmal öffentliches Repo, in dem später unsere wirkliche Webseite ablegen. Hier müssen wir aber anders als bei unserem privaten Repo auf den Namen achten. Da wir nur eine GitHubPage haben können, ist das Muster “GITHUBUSERNAME.github.io” hier sehr wichtig. Gleichzeitig ist unsere Webseite auch direkt unter dieser URL erreichbar (Beispiel http://DevTown.github.io). Und für später ggf. noch eine Domain bei einem Anbieter unserer Wahl. Das ist es dann auch schon für den Anfang.

Nun füllen wir die Repos mit Leben

In das private Repo comitten wir nun unsere (hoffentlich bereits vorhandene) Hugo-Webseite. Nachdem wir also in unserem privaten Repo unseren Hugo-Ordner mit allen Artikeln und co abgelegt haben, ist es an der Zeit eine Action anzulegen. Dafür müssen wir im privaten Repo eine neue YML-Datei in dem Ordner “.github/workflows” anlegen. Als Beispiel nennen wir diese mal “GitHub-Pages.yml”. In dieser Datei erstellen wir nun unsere Aktion, die unser Repo abruft (incl. Subrepo), Hugo installiert, Hugo ( ggf. mit vorhandenen Parametern) unsere statische Webseite generieren lässt und am Ende dann noch den “public” Ordner nimmt, und diesen dann in unser öffentliches Repo schiebt. Das klingt alles viel schwerer als es eigentlich ist. Als Anfang, hier mal meine Action, die alle wichtigen Schritte inne hält:

name: GitHub-Pages

on:
  push:
    branches:
      - master  # Set a branch name to trigger deployment
  pull_request:

jobs:
  deploy:
    runs-on: ubuntu-20.04
    concurrency:
      group: ${{ github.workflow }}-${{ github.ref }}
    steps:
      - uses: actions/checkout@v2
        with:
          submodules: true  # Fetch Hugo themes (true OR recursive)
          fetch-depth: 0    # Fetch all history for .GitInfo and .Lastmod

      - name: Setup Hugo
        uses: peaceiris/actions-hugo@v2
        with:
          hugo-version: 'latest' 
          extended: true #Wichtig für viele Themes

      - name: Build
        run: HUGO_ENV=production hugo --minify

      - name: Deploy
        uses: peaceiris/actions-gh-pages@v3
        with:
          personal_token: ${{ secrets.TOKEN }}
          external_repository: GithubUser/GithubRepo.io #REPO where to push to / CHANGE ME
          publish_dir: ./public #what to publish
          #   keep_files: true
          user_name: Username  #git username / CHANGE ME
          user_email: user@domain.de # git email / CHANGE ME
          publish_branch: master # branch 
          cname: Domain.de # Externe Domain die wir noch einrichten müssen / CHANGE ME

Nachdem wir die Datei angelegt haben, müssen wir nur noch für unser öffentliches Repo einen ZugriffsToken erstellen und diesen dann für unser privates Repo als secret einstellen. Sind nun alle Einstellungen richtig vorgenommen, sollte ein weiterer commit in unserem privaten Repo dafür sorgen, dass wir unsere “compilierte” statische Homepage direkt ins öffentliche Repo geschoben bekommen. Somit wird unsere Webseite (das öffentliche Repo) immer aktualisiert sobald wir an unserem privaten etwas ändern.

Eigene Domain benutzen

Bisher können wir unsere Webseite “nur” über die Subdomain von GitHub erreichen. Aber das ist ja nur halb so schön als wenn wir das ganze auch über unsere eigene Domain erreichen könnten. Da GitHub das auch weiß, bietet es uns die Möglichkeit auch hier unsere eigene Domain zu hinterlegen. Dazu gehen wir nun in unserem öffentlichen Repo auf die Einstellungen und unter Pages finden wir die passenden Einstellungen.

Hier wird dann noch erklärt was wir bei unserem Anbieter der Domain einstellen müssen und ganz wichtige den “enforce HTTPS” Hacken setzen. Denn wir möchten gerne die Webseite über HTTPS erreichen und nicht nur über HTTP (Als als gesicherte verschlüsselte Verbindung).

Fazit

Dank Hugo und Github ist es möglich, sich seine eigene statische Webseite innerhalb weniger Stunden zusammen zu bauen und ins Internet zu stellen. Selbst wenn man keine eigene Domain hat ist sofort die recht sprechende Subdomain von GitHub.io vorhanden und kann genutzt werden. Natürlich wird es schöner und professioneller eine eigene Domain zu verwenden, aber auch dies ist mit nur wenigen Einstellungen schnell realisiert. Also für den Einstig ist hier alles vorhanden was man braucht und das ganze auch noch sehr Kostengünstig. Ja die Webseite liegt bei GitHub einem US-Unternehmen, aber da wir hier “nur” eine statische Webseite ohne Anmeldung und weiterer Kundendaten betreiben kann man hier für den Anfang ein Auge zu drücken. Wenn man später weiter gehen möchte, kann man sich natürlich entweder die Actions so umschreiben, dass diese die Webseite auf einen eigenen Webspace oder auch als Docker-Image bereitstellt. Aber das ist dann auch schon wieder ein ganz eigener Blogbeitrag für die Zukunft.

Wenn ihr noch weitere Anregungen oder Fragen habt könnt ihr mich gerne auf Twitter oder Mastodon anschreiben. Würde mich hier über Feedback freuen. Links sind oben in der Menuleiste zu finden. :-)