kollegen-hugo

Die Kolleenrunden-Website besteht aus statischen Webseiten, die mittels dem Hugo-Framwork generiert werden. Es gibt zwei Repositories: kollegen-posts für die Inhalte der Blog-Beiträge und kollegen-hugo, was die Generierungsgrundlage beinhaltet. Um redaktionell mitzubloggen, benötigt man nur das Posts- Repository. Die Anleitung dazu findet man dort.

Dieses Repository wird für Website-Bearbeitung benötigt, was im Folgenden beschrieben ist.

Lokales Setup

Klappt auf Linux, Windows und Mac. Beschrieben ist es hier für Linux.

Voraussetzungen:

• Installierter git-Client: https://git-scm.com/downloads
• Gitea-User aus dem Owners-Team

Verzeichnis anlegen

Die Installation kann in einem beliebigen Verzeichnis erfolgen, wir nehmen ~/kred und installieren dort das aktuelle Hugo-Release und das kollegen-hugo/Repository, jeweils in ein Unterverzeichnis:

$ mkdir ~/kred
$ cd ~/kred
$ mkdir hugo

Hugo-Release installieren

Das aktuelles hugo-Release für seine Zielplattform findet man auf gitHub: [https://github.com/gohugoio/hugo/releases/latest] (die extended Version wird nicht benötigt).

Wenn das aktuelle Hugo-Relase 0.78.1 ist, gilt für Linux:

$ wget https://github.com/gohugoio/hugo/releases/download/v0.78.1/hugo_0.78.1_Linux-64bit.tar.gz
...
hugo_0.78.1_Linux-64bit.tar. 100%[============================================>] 13,31M 1,54MB/s in 25s
2020-10-13 21:09:43 (547 KB/s) - »hugo_0.78.1_Linux-64bit.tar.gz« gespeichert [13953675/13953675]

$ tar -xvf hugo_0.78.1_Linux-64bit.tar.gz --directory hugo
$ rm hugo_0.78.1_Linux-64bit.tar.gz

Nach erfolgreicher Installation sollte Hugo seine Version ausgeben können:

$ hugo/hugo version
Hugo Static Site Generator v0.78.1-347F2DE6 linux/amd64 BuildDate: 2020-11-05T09:39:06Z

Web-Repository holen

Das Repository wird geklont und installiert sich im Unterverzeichnis:

$ git clone --recurse-submodules https://kollegen.uber.space/gitea/kollegenrunde/kollegen-hugo.git
$ ls kollegen-hugo
archetypes config.toml data layouts LICENSE README.md resources static themes

Als Theme wird Ananke verwendet (wurde einmalig als Submodul eingebunden mit 'git submodule add https://github.com/budparr/gohugo-theme-ananke.git themes/ananke').

Content/Repository holen (Posts)

Für die Post-Bearbeitung und ggf. auch zur Web-Entwicklung benötigt man noch den Content. Dieses Repository wird neben das Web-Repository installiert:

$ git clone https://kollegen.uber.space/gitea/kollegenrunde/kollegen-posts.git

Damit ist das Setup abgeschlossen.

Setup des Servers auf uberspace

Die Pflege des Servers erfolgt über ssh:

$ ssh kollegen@despina.uberspace.de
Password:
...
[kollegen@despina ~]$

Gitea wird im im Lab beschrieben installiert: (https://lab.uberspace.de/guide_gitea.html). Einzige Abweichung ist die Root-Url in der app.ini:

[kollegen@despina ~]$ cat gitea/custom/conf/app.ini | grep ROOT_URL
ROOT_URL = https://%(DOMAIN)s/gitea/

Im Gitea ist die Organisation 'kollegenrunde' mit die beiden Repositories kollegen-hugo und kollegen-posts anzulegen.

Hugo wird ebenfalls wie im Lab beschrieben installiert: (https://lab.uberspace.de/guide_hugo.html). Es wird lediglich ~/bin/hugo benötigt.

[kollegen@despina ~]$ ~/bin/hugo version
Hugo Static Site Generator v0.74.3-DA0437B4 linux/amd64 BuildDate: 2020-07-23T16:22:34Z

Das Skript generate.sh zum automatischen Generieren beim git-update muss im Verzeichnis 'kollegengen' liegen. Das Skript ist aus dem Verzeichnis 'admin' des Repositories kollegen-hugo zu kopieren.

[kollegen@despina ~]$ mkdir ~/kollegengen
[kollegen@despina ~]$ git clone https://kollegen.uber.space/gitea/kollegenrunde/kollegen-hugo.git ~/kollegengen/kollegen-hugo
[kollegen@despina ~]$ cp ~/kollegengen/kollegen-hugo/admin/generate.sh ~/kollegengen/

Zur Erfolgskontrolle kann die Website nun generiert und gepublished werden:

[kollegen@despina ~]$ ~/kollegengen/generate.sh

Es sollte die Ausgabe "Ready, Blog created in /var/www/virtual/kollegen/html/kollegenrunde!" erfolgen.

Git-Hook einrichten

Per Gitea-Hook wird das Skript generate.sh nun in das git-update-Event der beiden Repositories eingebunden. Damit wird die Website mit jeden Push neu erzeugt.

Das Hook Skript ist für beide Repositories das gleiche und wird ebenfalls im admin-Verzeichnis von kollegen-hugo gepfelgt. Die Aktivierung kann entweder mit der Gitea-Webkonsole oder auf dem Server erfolgen.

Serverseitig installiert man das Script durch kopieren in die Hooks (darauf achten, dass die Skripte ausführbar sind - 0775):

[kollegen@despina ~]$ cp ~/kollegengen/kollegen-hugo/admin/post-receive ~/gitea-repositories/kollegenrunde/kollegen-hugo.git/hooks/post-receive.d/
[kollegen@despina ~]$ cp ~/kollegengen/kollegen-hugo/admin/post-receive ~/gitea-repositories/kollegenrunde/kollegen-posts.git/hooks/post-receive.d/

Hinweis: Das Hook-Skript starten das generate.sh mit 'env -i' in einer neuen Umgebung, damit nicht GIT_DIR gesetzt ist (vom ausführenden git). Ansonsten scheitert der pull innerhalb der Skripts.

In der Web-Konsole von Gitea kann man nun sehen, dass die post-receive-Hooks aktiv sind (grüner Punkt), s. (https://kollegen.uber.space/gitea/kollegenrunde/kollegen-hugo/settings/hooks/git) bzw. (https://kollegen.uber.space/gitea/kollegenrunde/kollegen-posts/settings/hooks/git).

Backup and Restore

Das Backup ist ein manueller Vorgang. Es wird beschrieben, wie alle Daten auf dem lokalen Server gespeichert werden. Da alles in gitea abgelegt ist, wird nur dieses gesichert.

Gitea-Backup

Auf Uberspace wird ein dump erzeugt und dann auf den lokalen Server kopiert.

Auf den Server per ssh:

$ ssh kollegen@despina.uberspace.de
Password:
[kollegen@despina ~]$ gitea/gitea dump
...
[kollegen@despina ~]$ ls gitea-dump-*
gitea-dump-1603992523.zip

Lokal:

$ scp kollegen@kollegen.uber.space:gitea-dump-1603992523.zip /media/diskstation/externalAccess/backups/uberspace-kollegen/gitea-dump.zip
Password:
...
gitea-dump-1603992523.zip 100% 365MB 1.6MB/s 03:55

Server:

[kollegen@despina ~]$ rm gitea-dump-1603992523.zip

Restore

tbc