Allgemeine Informationen
| Anleitung | |
|---|---|
| Informationen | |
| Betriebssystem | Alle |
| Service | GitLab |
| Interessant für | Angestellte, Studierende und Gäste |
| HilfeWiki des ZIM der Uni Paderborn | |
In dieser Anleitung erfahren Sie, wie Sie mithilfe des HUGO-Frameworks statische Webseiten über GitLab CI/CD automatisch erstellen und auf einer Instanz des Cloudcomputing Dienstes bereitstellen.
Bei HUGO handelt es sich um einen freien, statischen Websidegenerator. Dieser erstellt aus HTML- und Markdown-Dateien statische Webseiten. Der Vorteil liegt hier darin, dass die Seite nicht bei jeden Aufruf neu erstellt werden muss, sondern nur wenn etwas geändert wurde. Dies ist Ressourcen schonend, effizient und einfach in der Handhabung. Weitere Informationen zu Hugo und einige Beispiel-Webseiten finden Sie auf der HUGO-Webseite.
Was ist zu tun?[Bearbeiten | Quelltext bearbeiten]
- Ein GitLab Projekt erstellen
- Entwicklungsumgebung einrichten und HUGO installieren
- Git installieren
- Testprojekt erstellen
- Eine Instanz im Cloudcomputing Dienst erstellen und einrichten
- Den GitLab Runner einrichten
- GitLab CI/CD Workflow erstellen und testen
Gitlab Projekt erstellen[Bearbeiten | Quelltext bearbeiten]
Als ersten Schritt erstellen Sie zunächst ein neuen GitLab Projekt, vergeben Sie einen aussagekräftigen Namen. Wie Sie ein neues GitLab Projekt anlegen wird im HilfeWiki zu GitLab erklärt.
Für diese Anleitung muss noch eine Einstellungen des Projektes geändert werden. Klicken Sie dazu in der linken Menüleiste auf Settings/General und klicken dort bei Visibility, project features, permissions den Expand Button. Aktivieren Sie den Punkt CI/CD, dieses Feature werden wir im Laufe der Anleitung benutzten. Klicken Sie zum Speichern der Einstellung auf Save changes.
Entwicklungsumgebung einrichten und HUGO installieren[Bearbeiten | Quelltext bearbeiten]
Ist das GitLab Projekt angelegt, ist der nächste Schritt sich eine Entwicklungsumgebung einzurichten. Dazu benötigen Sie auf ihrem Computer:
- einen Texteditor (Visual Studio Code, NodePad++, o.ä.)
- Git
- HUGO
Wir empfehlen im Zuge dieser Anleitung den quelloffenen Texteditor Visual Studio Code zu verwenden, da er für alle Plattformen verfügbar ist, ein integriertes Terminal bietet, durch Plug-ins erweiterbar ist und eine Vielzahl an Programmiersprachen und Framework unterstützt. Eine Anleitung zu Installation finden Sie unter https://code.visualstudio.com/.
Nachdem der Texteditor erfolgreich installiert ist, benötigen Sie noch eine Installation des HUGO Framework auf ihrem Computer. Dadurch können Sie lokal eine Webseite erstellen und diese über einen integrierten Testserver testen. Der Getting-Started-Guide auf der HUGO Website bietet eine Anleitung zur installation des Frameworks auf ihrem jeweiligen Betriebssystem.
Sie können die Installation überprüfen, indem Sie in ihr Terminal hugo version eingeben. Wenn die Installation erfolgreich war, sollten Sie folgende Ausgabe erhalten:
$ hugo version
Hugo Static Site Generator v0.68.3/extended linux/amd64 BuildDate: 2020-03-25T06:15:45ZGit installieren[Bearbeiten | Quelltext bearbeiten]
Neben dem Texteditor und dem HUGO-Framework wird auch die Versionsverwaltung Git benötigt. Diese können Sie hier herunterladen - dort finden Sie auch eine Installationsanleitung für ihr Betriebssystem. Durch die Versionverwaltung können Sie das zuvor angelegte Projekt von GitLab auf ihren Computer "klonen", darin weiterarbeiten und alle Änderungen später wieder auf den GitLab Server "pushen" (hochladen).
Darüberhinaus können Sie auch Module zu ihrem Projekt hinzufügen, im Falle von HUGO sind dieses z.B. Themes für ihre Website. Mehr dazu erfahren Sie im weiteren Verlauf dieser Anleitung.
TIPP: Visual Studio Code bietet eine grafisch gestützte Versionkontrolle mit Git, diese erleichtert den Einstieg im Arbeiten mit Git. Weitere Informationen zu diesem Thema finden Sie im VSCode Wiki.
Nachdem Git installiert ist, können Sie das zuvor angelegte Projekt von GitLab klonen. Dazu klicken Sie auf der Übersichtsseite des Projekt auf GitLab rechts auf den Button Clone und kopieren sich die Zeile unter Clone with HTTPS.
Offnen Sie ein Terminalfenster auf ihrem Computer - unter Windows liefert Git das Git Bash Terminal mit, dies können Sie im Zuge dieser Anleitung benutzten.
Mit dem Befehl git clone können Sie ein Git Projekt klonen, fügen Sie die zuvor kopierte HTTPS-Adresse des Projektes an den Befehl an.
git clone $HTTPS-zu-meinem-GitLab-ProjektDas Projekt wird jetzt auf ihren Computer geklont.
HUGO Projekt erstellen[Bearbeiten | Quelltext bearbeiten]
Navigieren Sie in ihrem Terminal in den Ordner des Projektes, den Sie im vorherigen Schritt geklont haben - z.B. cd MeinHugoProjekt.
Eine kleine Einführung in die Bash-Shell bekommen Sie im Ubuntu Wiki.
Dort können wir mit HUGO eine neue Webseite erstellen, dazu geben Sie folgenden Befehl ein:
hugo new site tutorialDen Namen der Webseite (tutorial) können Sie frei wählen.
Das HUGO-Framework erstellt jetzt automatisch alle nötigen Elemente und Ordner für das Projektes und Sie sollten folgende Ausgabe bekommen:
➜ hugo new site tutorial
Congratulations! Your new Hugo site is created in /Users/till/hugo_test/tutorial.
Just a few more steps and you're ready to go:
1. Download a theme into the same-named folder.
Choose a theme from https://themes.gohugo.io/ or
create your own with the "hugo new theme <THEMENAME>" command.
2. Perhaps you want to add some content. You can add single files
with "hugo new <SECTIONNAME>/<FILENAME>.<FORMAT>".
3. Start the built-in live server via "hugo server".
Visit https://gohugo.io/ for quickstart guide and full documentation.Öffnen Sie in ihrem Terminal den Ordner des Hugo Projektes, dieser hat den automatisch den Namen des Projektes erhalten:
cd tutorialEin HUGO Projekt kann um Module erweitert werden, dies ist üblicherweise ein Theme, der das Aussehen der Webseite bestimmt. Diese Module werden über Git als Submodule hinzugefügt. Für dieses Tutorial fügen wir unserem Projekt das Terrassa Theme hinzu.
Dazu geben Sie im Ordner des Hugo Projektes diesen Befehl ein:
git submodule add https://github.com/danielkvist/hugo-terrassa-theme themes/terrassaSie sollten folgende Ausgabe erhalten:
➜ git submodule add https://github.com/danielkvist/hugo-terrassa-theme themes/terrassa
Cloning into '/tutorial/themes/terrassa'...
remote: Enumerating objects: 1383, done.
remote: Total 1383 (delta 0), reused 0 (delta 0), pack-reused 1383
Receiving objects: 100% (1383/1383), 5.20 MiB | 9.96 MiB/s, done.
Resolving deltas: 100% (759/759), done.Nachdem Sie das Theme zum Projekt hinzugefügt haben, müssen Sie dies in der config.toml-Datei hinterlegen und können dort auch einige andere Einstellungen vornehmen.
Um das Theme zu aktivieren fügen Sie theme = "terrassa" am Ende der Datei ein. Andere Einstellungen, wie z.B. title können Sie hier auch ändern.
Die config.toml-Datei sollte später diesen Inhalt besitzen:
baseURL = "/"
languageCode = "de-de"
title = "Mein Hugo Projekt"
theme = "terrassa"Nun erstellen wir noch eine Startseite für unser Projekt und testen ob das HUGO-Framework die Webseite erfolgreich erstellen kann.
Offnen Sie in ihrem Terminal den Projektordner - z.B. /
Um eine neue Startseite zu erstellen geben Sie hugo new _index.md -k page ein. Die Datei wird automatisch im Projektordner unter /content/_index.md erstellt.
Öffnen Sie die Datei mit ihrem Texteditor - sie ist bis auf den Header leer.
---
title: ""
description: ""
images: []
draft: true
menu: main
weight: 0
---Sie können nun der Seite einen Titel und eine Beschreibung geben, ändern Sie draft auf false und weight auf 1. Unterhalb der Trennstriche des Headers können Sie nun den Inhalt der Seite verfassen. Eine Besonderheit des HUGO-Frameworks ist, dass Sie den Inhalt auch in der Auszeichnungssprache Markdown verfassen können. Ein ausführliches Tutorial zu Markdown finden Sie auf der Seite https://www.markdowntutorial.com/.
Fügen Sie unterhalb des Headers einen Beispieltext ein - z.B.
---
title: "Meine Hugo Webseite"
description: "Tutorial"
images: []
draft: false
menu: main
weight: 1
---
# Hello World!
## Das ist meine erste HUGO-WebseiteSpeichern Sie die Änderung der Datei ab.
Nun können Sie testen, ob die Seite erfolgreich erstellt werden kann. Dazu bietet HUGO einen eigenen kleinen Webserver, der die Webseite lokal verfügbar macht.
Öffnen Sie ein Terminal im Projektordner und geben Sie hugo serve ein. Sie sollten folgende Ausgabe erhalten:
➜ hugo serve
Start building sites …
hugo v0.84.0+extended darwin/amd64 BuildDate=unknown
| EN
-------------------+-----
Pages | 1
Paginator pages | 0
Non-page files | 0
Static files | 3
Processed images | 0
Aliases | 0
Sitemaps | 1
Cleaned | 0
Built in 5 ms
Watching for changes in /Users/****/hugo-tut/tutorial/{archetypes,content,data,layouts,static,themes}
Watching for config changes in /Users/****/hugo-tut/tutorial/config.toml
Environment: "development"
Serving pages from memory
Running in Fast Render Mode. For full rebuilds on change: hugo server --disableFastRender
Web Server is available at //localhost:1313/ (bind address 127.0.0.1)
Press Ctrl+C to stopSie können die Webseite nun über ihren Browser aufrufen, dazu geben Sie http://localhost:1313 in die Adresszeile des Browsers ein.
Sie sollten nun die Webseite angezeigt bekommen:
Beenden Sie den Server im Terminal wieder mit STRG/control + C.
Anschließen prüfen Sie, ob HUGO die Seite erstellen kann. Dazu müssen Sie nur den Befehl hugo in das Terminal eingeben. Hugo erstellt nun die Webseite und legt Sie im Verzeichnis public/ ab.
Bei erfolgreicher Erstellung sollten Sie folgenden Ausgabe erhalten:
➜ hugo
Start building sites …
hugo v0.84.0+extended darwin/amd64 BuildDate=unknown
| EN
-------------------+-----
Pages | 7
Paginator pages | 0
Non-page files | 0
Static files | 3
Processed images | 0
Aliases | 2
Sitemaps | 1
Cleaned | 0
Total in 21 msNun müssen wir die Änderungen noch in der Versionsverwaltung Git hinterlegen. Dies machen Sie mit den Befehlen git add * um alle Dateien zu erfassen und git commit -m "inital commit" um die Änderungen festzuschreiben.
Anschließend können Sie alle Änderungen in das zuvor erstellte GitLab Projekt hochladen, dies wird im Git Context auch als pushen bezeichnet.
Mit dem Befehl git push werden die Änderungen hochgeladen.
Das HUGO-Projekt ist somit fertig erstellt. In den nächsten Schritten erfahren Sie, wie sie einen Server erstellen und einrichten um vollautomatisch aus dem GitLab Projekt eine Webseite zu erstellen und diese im Internet verfügbar machen.
Cloudcomputing Instanz erstellen und einrichten[Bearbeiten | Quelltext bearbeiten]
Instanz erstellen[Bearbeiten | Quelltext bearbeiten]
Für die Erstellung und das Hosting der Webseite können Sie eine Instanz des Cloudcomputing Dienstes der Universität benutzen. Im ZIM HilfeWiki erfahren Sie mehr zum Thema Cloudcomputing. An dieser Stelle werden wir nur eine kurze Anleitung zur Erstellung einer Instanz geben - eine ausführlichere Anleitung finden Sie im QuickStartGuide.
Vorraussetzung ist ein vorhandnes Schlüsselpaar! Falls Sie noch kein Schlüsselpaar angelegt haben, finden Sie hier eine Anleitung, wie Sie ein Schlüsselpaar erstellen.
1. Erstellen Sie einen Datenträger unter Datenträger/Datenträger mit den folgenden Einstellungen:
2. Legen Sie unter Netzwerk/Sicherheitsgruppen eine neue Sicherheitsgruppe an mit dem Namen HUGO-GitLab-Ci an. Erstellen Sie eine neue Sicherheitsregel für den Port des SSH-Dienstes - hier bietet OpenStack bereits eine Standardregel.
Erstellen Sie eine weitere Sicherheitsregel für den HTTP-Port, auch hier bietet OpenStack eine Standardregel. Soll der Dienst auch über IPv6 erreichbar sein, erstellen Sie eine weitere Regel mit den selben Parameter - ausser CIDR, dort geben Sie ::/0 an.
3. Erstellen Sie eine neue Instanz unter Compute/Instanzen über den Button Instanz starten. Vergeben Sie den Namen Ubuntu-20.04-HUGO. Als Quelle wählen Sie den zuvor erstellen Datenträger aus. Die Wahl der Variante hängt von Ihren Anforderungen ab - für dieses Tutorial wählen wir medium aus. Falls Sie bereits ein Netzwerk angelegt haben, können Sie die Instanz diesem zuordnen. Unter Sicherheitsgruppen ordnen Sie die zuvor erstellte Sicherheitsgruppe der Instanz zu. Ihr Schlüsselpaar sollte automatisch zur Instanz hinzugefügt worden sein. Klicken Sie anschließend auf Instanz starten.
4. Im Kontextmenü der Instanz können Sie dieser eine Floating IP zuweisen, damit diese von Aussen erreichbar ist.
HUGO und NGINX installieren[Bearbeiten | Quelltext bearbeiten]
Verbinden Sie sich per SSH mit der zuvor erstellten Instanz, eine Anleitung dazu finden Sie hier.
Installieren Sie zunächst alle verfügbaren Updates mit dem Befehl:
sudo apt update && sudo apt upgrade -yAnschließend installieren Sie das HUGO-Framework und den Webserver nginx mit dem Befehl:
sudo apt install hugo -y && sudo apt install nginx -yUm zu überprüfen, ob Hugo erfolgreich installiert wurde, können Sie hugo version eingeben. Sie sollten folgende Ausgabe erhalten:
$ hugo version
Hugo Static Site Generator v0.68.3/extended linux/amd64 BuildDate: 2020-03-25T06:15:45ZUm die Installation des nginx-Webservers zu überprüfen, können sie im Browser die Floating IP der Instanz aufrufen.
Dazu geben Sie http://FloatinIP/ in ihren Browser ein und ersetzen FloatinIP durch die Floating IP ihrer Instanz.
Sie sollten die Startseite des nginx-Webserver angezeigt bekommen.
GitLab Runner installieren und registrieren[Bearbeiten | Quelltext bearbeiten]
Damit wir über GitLab automatisiert die Seite erstellen und hosten können, müssen wir auf der im vorherigen Schritt erstellten virtuellen Maschine noch den GitLab-Runner installieren. Dazu geben Sie folgende Befehle nacheinander in das Terminal ein:
curl -L "https://packages.gitlab.com/install/repositories/runner/gitlab-runner/script.deb.sh" | sudo bash
sudo -E apt install gitlab-runner -yUm zu überprüfen, ob die Installation erfolgreich war können Sie gitlab-runner --version eingeben. Sie sollten folgende Ausgabe erhalten:
$ gitlab-runner --version
Version: 14.0.1
Git revision: c1edb478
Git branch: refs/pipelines/326100216
GO version: go1.13.8
Built: 2021-06-23T16:35:23+0000
OS/Arch: linux/amd64Als nächsten Schritt fügen Sie den gitlab-runner Benutzer zu der Gruppe sudo hinzu, damit dieser Befehle mit erhöhten Rechten ausfürhen kann:
sudo usermod -a -G sudo gitlab-runnerAnschließend deaktivieren Sie die Passwortabfrage für den Benutzer, damit später bei der GitLab CI/CD Pipeline keine Probleme auftreten.
Dazu öffen Sie mit dem Befehl sudo visudo die sudoers-Datei und tragen am Ende der Datei gitlab-runner ALL=(ALL) NOPASSWD: ALL ein.
Speichern Sie die Datei mit STRG/control + O und schließen Sie den Texteditor mit STRG/control + X.
Nun können Sie den GitLab Runner in ihrem Projekt registrieren, dazu benötigen Sie die URL des GitLab Servers und einen Registrigungs-Token. Beides finden Sie auf GitLab in der linken Menüleiste unter Settings -> CI/CD unter dem Punkt Runners.
Um den Registrierungsprozess zu starten, geben Sie sudo gitlab-runner register in ihr Terminal ein. Geben Sie die URL des Server, sowie den Token ein. Anschließend vergeben Sie einen Namen für den Runner, die Eingabe der Tags können Sie frei lassen.
Als Executer wählen Sie Shell aus.
$ sudo gitlab-runner register
Runtime platform arch=amd64 os=linux pid=4656 revision=c1edb478 version=14.0.1
Running in system-mode.
Enter the GitLab instance URL (for example, https://gitlab.com/):
https://git.uni-paderborn.de/
Enter the registration token:
********************
Enter a description for the runner:
hugo-cd-runner
Enter tags for the runner (comma-separated):
Registering runner... succeeded runner=56Loxmyq
Enter an executor: docker, parallels, shell, docker+machine, docker-ssh+machine, custom, docker-ssh, ssh, virtualbox, kubernetes:
shell
Runner registered successfully. Feel free to start it, but if it's running already the config should be automatically reloaded!Anschließend starten Sie den GitLab Runner mit dem Befehl sudo gitlab-runner start
Der Runner sollte nach einigen Minuten unter Settings -> CI/CD unter dem Punkt Runners aufgeführt werden.
GitLab CI/CD Pipeline für ein HUGO Projekt erstellen[Bearbeiten | Quelltext bearbeiten]
Nachdem der GitLab Runner erfolgreich eingerichtet können Sie nun eine GitLab CI/CD Pipeline erstellen. Diese ist im Zuge dieses Tutorial bewusst einfach gehalten. Eine Einführung in Continuous Integration und Continuous Deployment bietet der Artikel zu GitLab CI/CD HilfeWiki. Falls Sie mehr zu diesem Thema erfahren möchten, bietet das GitLab CI/CD Wiki weiter Informationen und Anleitungen.
Öffnen Sie zunächst in GitLab ihr Projekt. Klicken Sie auf New File und wählen Sie .gitlab-ci.yml aus. Fügen Sie folgenden Code in die Datei ein:
variables:
GIT_SUBMODULE_STRATEGY: recursive
build:
script:
- cd tutorial
- hugo
artifacts:
paths:
- tutorial/public
deploy:
script:
- sudo cp -r tutorial/public/* /var/www/html/
after_script:
- sudo systemctl restart nginx
only:
- masterUnter variables legen wir zunächst fest, dass git auch alle Submodule beachten soll, dann legen wir die Stage build an. Hier wird per Script zunächst der Ordner des HUGO-Projekts geöffnet und mit dem Befehl hugo die statische Webseite gebaut.
Anschließend wird das public-Verzeichnis des Projekts als Artifact festgelegt, dies ermöglicht es die Daten aus dem Verzeichnis auch aus der Weboberfläche von GitLab herunter zu laden.
In der Stage deploy kopieren wir zunächst den gesamten Inhalt des public-Ordners in das Verzeichnis /var/www/html/. Dies ist das Standardverzeichnis, auf welches der Webserver NGINX zugreift.
Anschließend wird der Webserver neu gestartet, damit er die neuen Daten lädt.
Klicken Sie auf Commit changes um die Änderungen zu speichern. Die Pipeline wird automatisch gestartet. Diese können Sie in der linken Menüleiste unter CI/CD aufrufen und einsehen. Wenn keine Fehler auftreten werden beide Stages mit einem grünen Haken gekennzeichnet. Sollten Fehler auftreten wird die Stage mit einem roten Kreuz gekennzeichnet, weitere Informationen zu dem Problem erhalten Sie in der Ausgab des jeweiligen Jobs.
Die Webseite sollte nun über die Floating IP oder die URL rdi-cloud-xxx-xxx.uni-paderborn.de (xxx-xxx stellt die letzten beiden Stellen ihrer Floating IP dar) der Instanz aufrufbar sein.
