An dieser Stelle wird beschrieben, wie die Entwicklungsumgebung und Tools für die Dokumentation eingerichtet werden.
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.89.0 ) 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.89.0_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.
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.
Deutsch
English
cd \workspaces\mycore-website\git
git clone https://github.com/MyCoRe-Org/mycore-websiteWir 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 compileHugo 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 serverDie MyCoRe-Dokumentation kann nun lokal unter folgender Adresse betrachtet werden: http://localhost:1313/
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.
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:
$ sudo adduser mycore
$ sudo mkdir -p /mcr/mycore.de/hugo/bin
$ cd /mcr/mycore.de/hugo/bin
$ sudo wget https://github.com/gohugoio/hugo/releases/download/v0.89.0/hugo_0.89.0_Linux-64bit.tar.gz
$ sudo tar -xzf hugo_0.89.0_Linux-64bit.tar.gz
$ sudo mkdir -p /mcr/mycore.de/hugo/mycore-website
$ sudo chown mycore /mcr/mycore.de/hugo/mycore-website
$ cd /mcr/mycore.de/hugo
$ sudo -u mycore git clone https://github.com/MyCoRe-Org/mycore-website
$ cd /mcr/mycore.de/hugo/mycore-website
$ sudo -u mycore mvn clean compile
$ cd mycore.org
$ sudo ../../bin/hugo -b https://www.mycore.de/ --cleanDestinationDir
$ sudo mv /mcr/mycore.de/hugo/mycore-website/mycore.org/public/* /var/www/mycore-website<Location /mycore-hugo>
Require ip 123.45.67.0/24
</Location>
Alias "/mycore-hugo" "/var/www/mycore-hugo"
Apache Konfiguration: /etc/apache2/sites-available/my-ssl.conf
Das Autodeploy Skript update-website.sh prüft zunächst, ob Updates auf dem Git-Server commited wurden und lädt diese herunter.
Wenn das letzte Commmit weniger als 4 min alt ist, 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.
Das Script kann direkt auf dem Server mit dem Parameter force aufgerufen werden,
dann wird die Webseite sofort ohne Update-Check und Wartezeit neu gebaut und deployed.
#!/bin/bash
# This script will download the MyCoRe website from Git,
# rebuild it with Maven and Hugo and 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 "force".
cd /mcr/mycore.de/hugo/mycore-website
LOCAL_HASH=$(git rev-parse HEAD)
REMOTE_HASH=$(git ls-remote | grep -C0 'HEAD' ) # filter lines containing 'HEAD'
echo "Local: $LOCAL_HASH"
echo "Remote: $REMOTE_HASH"
if [[ $REMOTE_HASH == *$LOCAL_HASH* ]]; then
if [[ "$1" != "force" ]]; then
echo "Up to date"
exit 0
fi
fi
echo "Do fetch"
git fetch
REMOTE_TS=$(git log -1 --format="%ct" --abbrev-commit remotes/origin/master)
NOW_TS=$(date +%s)
if (($NOW_TS - $REMOTE_TS < 4 * 60)); then
if [[ "$1" != "force" ]]; 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 /mcr/mycore.de/hugo/mycore-website
/opt/apache-maven/bin/mvn clean compile
cd /mcr/mycore.de/hugo/mycore-website/mycore.org/
export HUGO_DISABLELANGUAGES="io"
../../bin/hugo -b https://www.mycore.de/ --cleanDestinationDir
STATUS=$?
if (($STATUS == 0)); then
echo "Hugo build finished successfully"
# deploy to www dir (optional)
rm -Rf /var/www/mycore-hugo
mv /mcr/mycore.de/hugo/mycore-website/mycore.org/public /var/www/mycore-hugo
fi
exit $STATUS
Bash: /mcr/mycore.de/hugo/bin/update-mycore-website.sh
$ sudo chmod +x /mcr/mycore.de/hugo/bin/update-mycore-website.sh$ sudo crontab -e# m h dom mon dow command
01,06,11,16,21,26,31,36,41,46,51,56 * * * * sudo -u mycore /mcr/mycore.de/hugo/bin/update-mycore-website.sh