Autor: internetfreak

Lesezeit: 9 Min

Hallo Leute,
willkommen zum ersten Tutorial der Serie “CMS mit Hugo”. In diesem Teil lernt ihr, wie man Hugo installiert und einrichtet. Am Ende des Tutorials haben wir dann eine vollständig eingerichtete Seite, die mit Hugo erstellt wurde. Soweit zur Einleitung, fangen wir an.

Was ist Hugo

Bei Hugo handelt es sich um einen Static Site Generator, d.h. es werden statische Webseiten damit generiert. Hugo ist in Go geschrieben und pfeilschnell, die Generierung einer Seite dauert in der Regel weniger als 100ms. Weitere Informationen zu Hugo findet ihr auf der offiziellen Homepage .

Voraussetzungen

Im Rahmen des Tutorials benötigt ihr folgendes:

  • Einen Webhost
    Meine Empfehlung: Uberspace , ein Hoster mit SSH-Zugang, vielen Funktionen und einem monatlich wählbaren Paketpreis.
  • Eine Domain
  • (optional) Ein SSL-Zertifikat, beispielsweise von Let’s Encrypt

Annahmen

Für dieses Tutorial gelten folgende Annahmen:

  • Gehostet wird bei Uberspace, der Account wurde dabei neu angelegt
  • Unsere Seite soll unter www.mein-hugo-blog.de liegen und erreichbar sein.
  • Zur Verbesserung der Sicherheit wird ein SSL-Zertifikat eingesetzt. Wir werden dieses im Verlauf des Tutorials erwerben und installieren.

Das Tutorial lässt sich auch ohne Uberspace-Account befolgen, die meisten Befehle sind universiell auf jeder Linux-Maschine einsetzbar. Lediglich ein paar Uberspace-spezifische Dinge müsst ihr dann auslassen.

Das Tutorial

Uberspace einrichten

Beginnen wir damit, unseren Uberspace etwas vorzubereiten, damit wir die nachfolgenden Schritte besser durchführen können.

Verzeichnis für Hugo sowie die Seite erstellen

Loggt euch auf eurem Uberspace per SSH ein. Ihr befindet euch nun in eurem persönlichen Homeverzeichnis. Führt dort folgende Befehle aus:

mkdir apps
mkdir apps/hugo
mkdir hugo-sites

Damit sind die erforderlichen Verzeichnisse soweit eingerichtet, weiter mit dem nächsten Schritt.

PATH anpassen

Damit Hugo in jedem Verzeichnis verwendet werden kann, fügen wir den Pfad dazu in die Umgebungsvariable PATH ein. Öffnet mit Hilfe von nano ~/.bashrc eure bashrc und fügt dort folgendes am Ende der Datei ein:

export PATH=$HOME/apps/hugo:$PATH

Damit eure Änderung wirksam wird, lest nun die bashrc mit source ~/.bashrc neu ein.

Domain aufschalten

Wir möchten nun unsere Domain auf den Uberspace aufschalten, gebt dazu folgendes ein:

uberspace-add-domain -d www.mein-hugo-blog.de -w

Der Domainname muss natürlich eurer Domain entsprechen, beachtet dies bitte. Euch werden nun zwei IP-Adresse für den A und den AAAA Record eurer Domain angezeigt. Tragt nun mindestens die IPv4-Adresse als A-Record bei eurem Domainhoster ein.

SSL-Zertifikat erwerben

Zur Absicherung der Kommunikation mit der Seite werden wir nun ein SSL-Zertifikat bei Let’s Encrypt beantragen und auf unserem Uberspace installieren. Zunächst benötigen wir ein neues Verzeichnis:

mkdir /var/www/virtual/$EUER_USER/www.mein-hugo-blog.de

Ersetzt $EUER_USER durch euren Uberspace-Benutzernamen und www.mein-hugo-blog.de natürlich durch den Namen eurer Domain, wie ihr ihn auch eben beim Aufschalten eingetragen habt. Führt nun folgenden Befehl aus:

uberspace-letsencrypt

Es wird nun eine Konfiguration für euch erstellt. Mit in der Ausgabe des Kommandos sollte nun jene Domain erscheinen, für die wir gerade einen Ordner angelegt haben. Sollte dies nicht der Fall sein, ist dies nicht so schlimm, das könnt ihr beheben. Öffnet dazu mit nano ~/.config/letsencrypt/cli.ini die eben angelegte Konfigurationsdatei und passt die Variable domains an, wenn die dort angegebene Domain nicht korrekt sein sollte. Speichert mit STRG + O + Enter und verlasst nano mit STRG + X.

Nun können wir das Zertifikat erwerben, dazu führt folgenden Befehl aus:

letsencrypt certonly

Der Vorgang sollte normalerweise ohne Probleme durchlaufen. Sollte es zu einem Fehler kommen, prüft, ob eure DNS-Records stimmen und ob die Domain auch korrekt auf den Uberspace aufgeschaltet ist.

Um das Zertifikat nun installieren zu können, müssen wir es eigentlich per uberspace-add-certificate importieren, wir bedienen uns aber einem kleinen Trick, damit wir die benötigten Pfade nicht manuell eintragen müssen. Eigentlich zur Erneuerung von Zertifikaten gedacht, können wir uberspace-letsencrypt-renew mit dem Schalter -f verwenden. Das Script holt sich ein neues Zertifikat von LE ab und installiert es vollautomatisch für euch. Im Idealfall solltet ihr am Ende des Vorgangs dann die Meldung All good! Your new certificate will be live within the next five minutes. erhalten, falls nicht, probiert es einfach nochmal. Weitere Informationen zu den eben durchgeführten Schritten findet ihr im Wiki von Uberspace .

Installation von Hugo

Wir sind nun soweit, Hugo installieren zu können. Zuerst wechseln wir mit cd ~/apps/hugo in das künftige Installationsverzeichnis von Hugo. Sucht euch nun von der Release-Seite von Hugo den neuesten Release sowie das passende Binary raus und kopiert den Link dazu. Zum Zeitpunkt des Tutorials war Version 0.31.1 aktuell, für Uberspace benötigen wir die Linux-ARM64.tar.gz Version.
Zum Download und zur Installation führt nun folgende Befehle aus:

wget https://github.com/gohugoio/hugo/releases/download/v0.31.1/hugo_0.31.1_Linux-64bit.tar.gz
tar -xzf hugo_0.31.1_Linux-64bit.tar.gz
rm hugo_0.31.1_Linux-64bit.tar.gz

Hugo ist nun heruntergeladen und installiert. Zum Testen, dass alles funktioniert hat, gebt hugo version ein, was die Versionsnummer von Hugo ausgibt. Wechseln wir nun per cd ~/hugo-sites zum Verzeichnis, wo wir unsere Seite ablegen wollen. Wir erstellen nun unsere Seite mit hugo new site mein-hugo-blog. Kurze Zeit später ist unsere Seite erstellt. Glückwunsch, wir können nun damit beginnen, die Seite einzurichten und aus dem Internet erreichbar zu machen.

Seite einrichten

Theme installieren

Als erstes sollten wir ein Theme installieren. Es gibt ein Theme-Repository unter https://themes.gohugo.io/ , sucht euch dort euer Wunsch-Theme aus. Für das Tutorial verwende ich den Hugo-Port des Themes Future Imperfect , es handelt sich um dasselbe Theme, welches ich hier auf der Seite verwende.

Um das Theme zu installieren, wechselt zuerst in das themes-Verzeichnis eurer Seite:

cd mein-hugo-blog/themes

Klont nun das Repository des Themes:

git clone https://github.com/jpescador/hugo-future-imperfect.git

Als nächstes kopieren wir den Inhalt des Ordners hugo-future-imperfect/exampleSite in unsere Seite:

cp -R hugo-future-imperfect/exampleSite/* ../.

Das Theme ist nun installiert und wir haben nun die Inhalte Beispielseite, die unsere Seite füllen. Zur Konfiguration des Themes verweise ich euch an die Github-Page, dort sind alle Optionen erklärt. Wir können nun damit fortfahren, unsere Seite erreichbar zu machen.

Seite über das Internet erreichbar machen

Zum Abschluss müssen wir nun daran arbeiten, die Seite zu veröffentlichen sowie aus dem Internet erreichbar zu machen. Hierfür gibt es zwei Möglichkeiten, abhängig davon, wie ihr die Seite hosten wollt/könnt. Der Vollständigkeit halber führe ich alle Möglichkeiten auf:

Statisches Hosting

Für den Fall, dass euer gewünschter Webhoster kein SSH anbietet, könnt ihr die Schritte des Tutorials trotzdem auf einer Linux-Maschine bzw. -VM durchführen. Um die Inhalte nun veröffentlichen zu können, wechselt in das Hauptverzeichnis eurer Seite, wo auch die config.toml liegt. Führt nun einfach den Befehl hugo aus. Hugo generiert euch nun innerhalb kürzester Zeit die Seite. Wenn Hugo fertig ist, könnt ihr den Inhalt des public-Ordners auf einen beliebigen Webhost hochladen und eure Seite sollte erreichbar sein.
Wenn ihr Änderungen an eurer Seite durchgeführt habt, löscht ihr einfach den public-Ordner und führt hugo erneut aus, um die neuen Inhalte hochladen zu können.

Für das Tutorial relevant ist allerdings der nächste Weg.

Dynamisches Hosting über Hugo

Hugo verfügt über einen eingebauten Webserver, mit dem ihr eure Website nach dem Generieren schnell und einfach hosten könnt. Um diesen nutzen zu können, müssen wir allerdings noch ein paar Dinge vorbereiten.

Port für Hugo ermitteln

Zum Hosten benötigt Hugo einen freien Port. Da Uberspace strenge Richtlinien hat, was die verwendung von Ports angeht, können wir natürlich nicht jeden beliebigen Port verwenden. Glücklicherweise ist ein freier Port dennoch schnell gefunden, führt dazu einfach folgendes auf der Shell aus:

HUGOPORT=$(( $RANDOM % 4535 + 61000)); netstat -tulpen | grep $HUGOPORT && echo "versuch's nochmal"

Wenn alles geklappt hat, sollte keine Ausgabe erfolgen, ansonsten probiert es einfach erneut. Um den ermittelten Port einsehen zu können, gebt einfach echo $HUGOPORT ein. Notiert euch den ausgegebenen Port, wir benötigen ihn gleich wieder

htaccess erstellen

Erstellen wir als nächstes die .htaccess-Datei für den Webserver, damit die Seite später auch erreichbar ist. Wir wechseln dazu mit cd /var/www/virtual/$EUER_USER/www.mein-hugo-blog in das Verzeichnis für unsere Domain und öffnen mit nano .htaccess eine leere .htaccess-Datei. Fügt dort folgendes ein:

# URL-Rewriting aktivieren
RewriteEngine On

# Zugriff auf die Seite per SSL erzwingen
RewriteCond %{HTTPS} !=on
RewriteCond %{ENV:HTTPS} !=on
RewriteRule .* https://%{SERVER_NAME}%{REQUEST_URI} [R=301,L]

# Zugriff auf Hugo umleiten
RewriteBase /
RewriteRule (.*) http://localhost:$HUGOPORT/$1 [P]

Ersetzt $HUGOPORT durch den eben ermittelten Port, das $1lasst ihr bitte so wie es ist, das gehört zur Datei selbst und ist für den Webserver wichtig. Solltet ihr - aus welchem Grund auch immer - kein SSL einsetzen wollen bzw. den Zugriff auf die Seite nicht rein per SSL zulassen wollen, so nehmt die beiden ersten RewriteCond und die darauf folgende RewriteRule aus der Datei raus. Der Webserver ist damit vorbereitet, wir können nun Hugo starten bzw. starten lassen. Der Inhalt der Datei ist über Kommentare erläutert, die Befehle genau zu erläutern, würde den Rahmen des Tutorials sprengen, hierzu verweise ich euch dann auf die Dokumentation von Apache

Hugo Webserver starten und Service einrichten

Bevor wir zum Abschluss des Tutorials kommen, müssen wir nun noch Hugo starten und anweisen, unsere Seite auszuliefern. Am einfachsten und besten geht dies per Service. Uberspace macht es uns dabei einfach, diesen einzurichten. Zuerst müssen wir sicherstellen, dass wir ein Verzeichnis für unseren Service haben, das geht mit folgendem Befehl:

test -d ~/service || uberspace-setup-svscan

Sollte noch kein Verzeichnis existieren, erstellt das Script eines für uns, ansonsten wird keine Aktion vorgenommen. Wir können nun unseren Service erstellen, das geht wie folgt:

uberspace-setup-service mein-hugo-blog hugo server -p${HUGOPORT} --baseUrl=$EURE_DOMAIN --bind="0.0.0.0" --appendPort=false

Vergesst nicht, wieder eure Domain einzutragen. Den Port zu Hugo holen wir uns per Shell ab, lasst die Variable so, wie sie ist. Uberspace richtet euch nun euren Server ein, allerdings müssen wir diesen für kurze Zeit wieder stoppen, da Hugo derzeit nicht in der Lage ist, unsere Seite zu finden und zu generieren. Stoppen könnt ihr den Service hiermit:

svc -d ~/service/mein-hugo-blog

Wir müssen nun die Konfiguration des Service anpassen, dazu führen wir folgenden Befehl aus:

nano ~/service/mein-hugo-blog/run

Die Datei müssen wir nun so bearbeiten, dass die letzten beiden Zeilen in etwa so aussehen:

cd /home/$EUER_USER/hugo-sites/mein-hugo-blog
exec /home/$EUER_USER/apps/hugo server -p$PORT --baseUrl=$DOMAIN --bind=0.0.0.0 --appendPort=false --disableLiveReload 2>&1

Wie üblich die Platzhalter natürlich anpassen. Sobald die Datei angepasst ist, könnt ihr den Service mit

svc -u ~/service/mein-hugo-blog

wieder starten. Wenn ihr jetzt eure URL in den Browser eingebt, sollte euch eure Seite begrüßen. Falls nicht, kontrolliert, ob ihr alle Schritte korrekt durchgeführt habt, ansonsten schreibt mir eine Mail oder hinterlasst einen Kommentar, damit ich euch helfen kann.

Wer mehr wissen will, wie Services unter Uberspace funktionieren, kann dies auf der dazugehörigen Seite im Wiki nachlesen.

Der Vorteil dieser Methode ist, dass Uberspace über Hugo wacht und bei Bedarf neu startet, sollte es bspw. mal crashen oder das System neu gestartet werden. Außerdem hat die Ausführung von hugo serverden Vorteil, dass Hugo das Verzeichnis der Seite überwacht. Ändert ihr nun etwas am Inhalt oder Theme der Seite, so baut Hugo die Seite automatisch neu. Die Dokumentation von Hugo hält dazu weitere Informationen für euch bereit.

Abschluss

Damit sind wir am Ende des ersten Teils angelangt. Wir haben Hugo installiert und angewiesen, unsere Seite zu generieren und auszuliefern. Ich hoffe, es hat euch gefallen. Hinterlasst mir doch gerne einen Kommentar, was ihr zu dem Beitrag meint und teilt ihn mit euren Freunden.

Bis zum nächsten Beitrag!

~internetfreak

comments powered by Disqus