MyCoRe Dokumentation: Umgebung einrichten

An dieser Stelle wird beschrieben, wie die Entwicklungsumgebung und Tools für die Dokumentation eingerichtet werden.

Installation von Hugo

Der Static Site Generator Hugo (https://gohugo.io/) bildet seit April 2019 die technische Basis für die MyCoRe-Dokumentation. Die Software ist in Go programmiert und steht für die gängigen Betriebssysteme als Download bereit.

Wir verwenden Hugo (Version: 0.55.6 ) in der Extended Edition, vor allem da diese das CSS-Framework Sass unterstützt.

Der Download erfolgt direkt von der Hugo-GitHub-Seite. Windows-Nutzer verwenden hugo_extended_0.55.6_Windows-64bit.zip.

Die Zip-Datei enthält das komplette Hugo-Programm, welches aus nur einer Datei besteht. Diese kann an einem beliebigen Ort auf dem PC abgelegt werden (z.B. C:\Programme). Anschließend muss der Ordner noch in der Umgebungsvariable Path bekannt gemacht werden. Eine detailierte Installationsanleitung findet man in der Hugo Dokumentation Install Hugo.

Git Checkout

Die Dokumentation wird in dem MyCoRe-Git-Repository MyCoRe-Org/mycore-website gepflegt. Commits dürfen ohne Pull-Requests direkt in den master-Branch erfolgen.

cd \workspaces\mycore-website\git
git clone https://github.com/MyCoRe-Org/mycore-website

Initialisierung (Maven)

Wir haben uns dafür entschieden, externe CSS- und Javascript-Frameworks (wie Bootstrap) nicht über das Git-Repository auszuliefern. Diese werden via Maven als Webjars heruntergeladen und in den Dokumentations-Source-Code integriert. Deshalb muss zuvor Maven gemäß der Anleitung "Installing Apache Maven" eingerichtet werden.

Werden die Hugo-Dokumentations-Umgebung neu eingerichtet oder die betreffenden Bibliotheken aktualisiert, muss einmalig in dem Ordner, in den das MyCoRe-Dokumentations-Projekt ausgecheckt wurde, das folgende Maven-Kommando aufgerufen werden:

cd \workspaces\mycore-website\git\mycore-website
$ mvn clean compile

Hugo starten und öffnen

Hugo unterstützt die Webseiten-Entwicklung mit einem lokalen Server mit Live-Reload. Das bedeutet, das Änderungen am Quellcode direkt im Browser betrachtet werden können

cd \workspaces\mycore-website\git\mycore-website\mycore.org
$ hugo server

Die MyCoRe-Dokumentation kann nun lokal unter folgender Adresse betrachtet werden: http://localhost:1313/

MyCoRe-Webseite deployen

Die folgenden Informationen sind nur für die Installation auf einem Server relevant.

Bei der Installation auf dem MyCoRe-Server wurde festgestellt, dass die in CentOS 7 verwendeten C-Bibliotheken zu alt sind ("libstdc++.so.6: version `GLIBCXX_3.4.21' not found"), um Hugo extended (mit Sass-Support) zu starten. Deshalb wird die normale Hugo-Version verwendet und SASS vorab per Maven-Plugin zu CSS kompiliert.

Installation

Die Installation muss einmalig durchgeführt werden, um die notwendigen Ordner und Tools zu konfigurieren. Danach reicht es, das Autodeploy-Skript aufzurufen.

Die Installation der Webseite auf dem Server umfasst die folgenden Schritte:

  • Anlegen der Ordner
  • Download und die Installation von Hugo
  • Checkout des Sourcecodes aus Git
  • Kompilieren der Webseite mit Maven und Hugo
  • Kopieren der generierten Seite in den WWW-Ordner
$ sudo mkdir -p /opt/mycore-hugo/bin
$ cd /opt/mycore-hugo/bin

$ sudo  wget https://github.com/gohugoio/hugo/releases/download/v0.55.6/hugo_extended_0.55.6_Linux-64bit.tar.gz
$ sudo tar -xzf hugo_extended_0.55.6_Linux-64bit.tar.gz

$ sudo mkdir -p /opt/mycore-hugo/git
$ sudo chown www-data /opt/mycore-hugo/git
$ cd /opt/mycore-hugo/git
$ sudo -u www-data git clone https://github.com/MyCoRe-Org/mycore-website

$ cd /opt/mycore-hugo/git/mycore-website
$ sudo -u www-data mvn clean compile

$ cd mycore.org
$ sudo -u www-data /opt/mycore-hugo/bin/hugo -b /mycore-hugo

$ sudo mkdir -p /opt/mycore-hugo/www
$ sudo chown www-data:www-data /opt/mycore-hugo/www
$ sudo rm -Rf /opt/mycore-hugo/www/mycore.org
$ sudo mv /opt/digibib_docs/working/checkout/digibib_docs/public/ /opt/digibib_docs/www/digibib_docs

Apache Konfiguration

Da Hugo valide HTML-Dateien erzeugt, muss in der Apache-Konfiguration lediglich ein Alias angelegt werden.
<Location /mycore-hugo>
  Require ip 123.45.67.0/24
</Location>
Alias "/mycore-hugo" "/opt/mycore-hugo/www/mycore.org"

Apache Konfiguration: /etc/apache2/sites-available/my-ssl.conf

Autodeploy Skript

Das Autodeploy Skript prüft zunächst, ob Update auf dem Git-Server commited wurden und lädt diese herunter. Wenn das letzte Commmit weniger als 4 min. zurückliegt, stoppt es, um auf weitere Commits zu warten. Ist die Wartezeit abgelaufen, wird die Webseite mit Maven und Hugo gebaut und das Ergebnis in den Webordner kopiert.

Direkt auf dem Server kann das Script mit dem Paramter now aufgerufen werden, dann wird die Webseite sofort ohne Update-Check und Wartezeit neugebaut und deployed.

#!/bin/bash

# This script will download the MyCoRe website from Git, 
# rebuild is with Maven and Hugo an deploy it.
# If the last commit was less than 4 min ago, nothing will be done 
# (waiting for other commits).
# A rebuild can be forced by calling the script with the parameter "now".

NOW=$1
cd /opt/mycore-hugo/git/mycore-website

LOCAL_HASH=$(git rev-parse HEAD)
REMOTE_HASH=$(git ls-remote)
echo "Local: $LOCAL_HASH"
echo "Remote: $REMOTE_HASH"

if [[$NOW != "now"]]; then
  if [[ $REMOTE_HASH == *$LOCAL_HASH* ]]; then
    echo "Up to date"
    exit 0
  fi
fi

echo "Do fetch"
git fetch

if [[$NOW != "now"]]; then
  REMOTE_TS=$(git log -1 --format="%ct" --abbrev-commit remotes/origin/master)
  NOW_TS=$(date +%s)

  if (($NOW_TS - $REMOTE_TS < 4 * 60)); then
    echo "Time is not ready for action yet - waiting for other commmits"
    exit 0;
  fi
fi

echo "Time is ready - starting website rebuild now"
git merge -X theirs origin/master

cd /opt/mycore-hugo/git/mycore-website
mvn clean compile

cd /opt/mycore-hugo/git/mycore-website/mycore.org/
export HUGO_DISABLELANGUAGES="io"
/opt/mycore-hugo/bin/hugo --baseURL https://lab.ub.uni-rostock.de/mycore-hugo --cleanDestinationDir

STATUS=$?
if (($STATUS == 0)); then
  echo "Hugo build finished successfully - deploying to www dir"
  rm -Rf /opt/mycore-hugo/www/mycore.org
  mv /opt/mycore-hugo/git/mycore-website/mycore.org/public /opt/mycore-hugo/www/mycore.org
fi

exit $STATUS

Bash: /opt/mycore-hugo/update-website.sh

Das Skript muss ausführbar sein:
$ sudo chmod +x update-mycore-hugo.sh

Crontab

Das Skript wir in der Crontab für root eingetragen und als User www-data ausgeführt. Es soll alle 5 Minuten gestartet werden.
$ sudo crontab -e
# m h  dom mon dow   command
01,06,11,16,21,26,31,36,41,46,51,56 * * * * sudo -u www-data /opt/mycore-hugo/bin/update-mycore-hugo.sh