## Gitlab-pages

GitLab ist eine umfangreiche Webanwendung zur Versionsverwaltung für Softwareprojekte auf Basis von Git die auch Wiki-Funktionen und Issue Tracking bietet. Das Transferportal der HFT-Stuttgart betreibt eine eigene GitLab-Instanz für die Hochschule für Technik Stuttgart und ihre Kooperationspartner unter einer Open-Access-Lizenz. Mit GitLab Pages besteht für Angehörige der HFT die Möglichkeit, eine öffentliche statische Projektwebsite aus einem GitLab-Projekt heraus zu erzeugen.

Die URL, unter der die Seite dann zu finden ist, lautet:

https://transfer.hft-stuttgart.de/pages/EIGENTUEMER/PROJEKTNAME/

Zugriff auf Gitlab

## Gitlab-pages Projekte

### Gitlab-pages Projekt erstellen

Um ein eigenes Gitlab-pages Projekt zu erstellen und damit eine eigene Projektseite zu erstellen, führen Sie folgende Schritte aus:

1. Legen Sie sich auf https://transfer.hft-stuttgart.de ein Benutzerkonto an bzw. loggen Sie sich mit Ihren HFT-Nutzerdaten in das Transferportal ein.
2. Besuchen Sie die Website https://transfer.hft-stuttgart.de/gitlab/explore/projects
3. Loggen Sie sich mit ihren Anmeldedaten ein
4. Standardmäßig wird Ihr Projekt als persönliches Projekt veröffentlicht, es wird also an Ihren persönlichen Benutzernamen gekoppelt, der dann auch in der URL auftaucht. Wenn Sie dies nicht wünschen, erstellen Sie eine neue Gruppe, unter der Sie das Projekt erstellen. Klicken Sie dazu auf Groups, Your Groups und wählen New group aus. Hier können Sie nun der Gruppe einen entsprechenden Namen geben.

   Wichtig: Dieser Name wird später auch in der URL auftauchen, unter der Ihre Seite aufrufbar ist.

   Nach Klick auf create group wird Ihre Gruppe angelegt, und Sie werden automatisch zur Gruppenseite weitergeleitet.
5. Legen Sie ein neues Projekt an, indem Sie auf den Button New Project klicken
6. Wählen Sie Create from template aus und nutzen Sie ein Template aus dem Bereich Instance , Klicken Sie dort auf Use template
7. Nun können Sie ihr Projekt befüllen. Tragen Sie mindestens die Grundinformationen wie Project name und Project description ein.
8. Klicken Sie auf Create project
9. Ihr Projekt wird nun erstellt und enthält automatisch die notwendigen Grundeinstellungen für das Publizieren einer Website über die Funktion Pages. Vor allem wird im Repositorium der Ordner Public angelegt.
10. Um Ihre eigenen Projektinhalte zu veröffentlichen, können Sie entweder eine komplett eigene HTML-Seite erzeugen oder sich an unseren Vorgaben aus dem Template orientieren. Eine Anleitung zur Verwendung unserer Vorlage finden Sie im Bereich Gitlab-pages Template benutzen
11. Sobald Sie Änderungen an Ihrer Seite vornehmen und diese in den Master-Branch eintragen (der Standard-Branch ihres Projektes), wird das Projekt veröffentlicht. Um den Link zu sehen, unter dem Sie Ihre Seite finden, gehen Sie in der Sitebar auf der linken Seite unter CI / CD auf Jobs und wählen den obersten Job mit den Namen pages aus. Im nun angezeigten Log finden Sie die Adresse, unter der Ihr Projekt ausgerollt wurde.
12. Für weitere Schritte gehen Sie zum nächsten Abschnitt.

### Gitlab-pages Projekt ändern

Nachdem Ihr Projekt das erste Mal veröffentlicht wurde, möchten Sie sicherlich Änderungen an der Seite vornehmen. Dafür gehen Sie wie folgt vor:

1. Klicken Sie die Datei, die Sie ändern wollen, in der Projektübersicht an
2. Klicken Sie in der sich nun öffnenden Dateiansicht auf Edit
3. Bearbeiten Sie ihre Datei
4. Um die Änderungen zu speichern und auf ihrer Seite sofort zu übernehmen, klicken Sie auf Commit changes
5. In der Projektübersicht sehen Sie nun den Status der Deployment-Pipeline, die ihre Webseite auf unserem Server veröffentlicht. Durch Klick auf das Symbol gelangen Sie zu einer Übersicht aller für Ihr Projekt angelaufenen Pipelines.
   Durch Klick auf eine Pipeline wird Ihnen eine Erklärung zum aktuellen Status angezeigt, der Sie auch eventuelle Probleme entnehmen können.
   Eine fehlerfrei durchgelaufene Pipeline liefert etwa ein solches Ergebnis:
   Für eine Übersicht über häufig auftretende Fehler und was man dagegen tun kann, siehe hier .
6. Wenn die Änderungen an Ihrer Homepage ohne Probleme übernommen wurden, sehen Sie dies an einem grünen Haken in der Projektübersicht

### Gitlab-pages Seite entfernen

Um Ihre gitlab-pages Seite zu entfernen, gibt es zwei Möglichkeiten. Sie können entweder das gesamte Projekt löschen, oder aber nur die öffentliche Seite, das Projekt aber behalten, um daran Änderungen vorzunehmen. Um nur die Seite, nicht aber das Projekt an sich zu löschen, gehen Sie wie folgt vor:

1. Klicken Sie in der linken Sitebar auf Settings und pages .
2. Klicken Sie in der sich nun öffnenden Konfigurationsansicht auf Remove pages . Dies entfernt die Seite von unserem Server, das Projekt an sich bleibt aber erhalten.

## Häufige Fragen und Probleme

- ###### Pipeline schlägt beim Schritt pages-test fehl

  In diesem Fall ist Ihr Projekt noch nicht vollständig konfiguriert. Bitte konfigurieren Sie ihr Projekt entsprechend der Vorlage im nächsten Abschnitt

- ###### Ich habe ein Gitlab-pages-Projekt erstellt, unter Settings/ pages steht aber eine kryptische URL der Form *.thishost.local:8090/*, die nicht funktioniert.

  Dies ist die interne Repräsentation des Projektes auf unserem Server und ist somit nicht von außerhalb ereichbar. Um die tatsächliche, von außen erreichbare URL Ihrer Seite zu finden, gehen Sie in der Sitebar auf der linken Seite unter CI / CD auf Jobs und wählen den obersten Job mit den Namen pages aus. Im nun angezeigten Log finden Sie die Adresse, unter der Ihr Projekt ausgerollt wurde.

- ###### Ich möchte größere Projektdaten hochladen, wie groß darf mein Projekt maximal sein?

  Gegenwärtig ist die Gesamtgröße der ausgerollten Seite (Ordner public ) auf 2 GB beschränkt.

Administratorkontakt

## Gitlab-pages Template pages-basic benutzen

Wir stellen eine Vorlage für Projektwebseiten zur Verfügung.

### Erste Schritte

A template can be a single page or it can be multiple pages with a menu to select them. If the name of a template begins with the word "simple" then it is a single page template. This is the general structure of a template:

assets folder: You place in this folder files that should be common for the single page or all the pages of your gitlab template. E.g. you should place any personal avatars or partner logos in the corresponding folders (images, logos).

home folder: This is the default folder where you place your main page (think of it as the landing page).

settings.js: This is the file where you select the settings for your gitlab page.

You should not make changes to some of the files.

Red: Those files should not be changed.

Orange: Those files should be replaced by your own files. The filename should remain the same. If there are files that should be replaced depends on the template you choose.

Green: Those files you can edit.

Blue: In those folders you can add your additional files. In case of assets, images, logos etc. In case of a template folder, your custom css, javascript or any other files.

Um unsere Vorlage zu benutzen, müssen Sie folgende Schritte ausführen:

1. Anpassen der Standardwerte in settings.js

   Wichtig: Werden diese Werte nicht angepasst, wird das Projekt nicht auf unseren Servern ausgerollt und die deployment-Pipeline wirft einen Fehler

   Klicken Sie dazu im Ordner public auf die Datei settings.js und editieren Sie die Datei.

   Those are the default values for the social networks/personal website of a participant and the default avatar. It is recommended not to change them, but you can add another social network if you want.

   The switches control which parts of you gitlab page should turn on or off. E.g. if you want a single page and not a menu then you change the menu value to OFF.

   Here you change the project logo. The logo will appear centered at the top of the page. If the switch for the project logo is OFF then it will not be visible.

   Here you change the project name. If the switch for the project name is OFF then it will not be visible.

   Here you change the menu of your gitlab page. A menu can be linked with a folder/template or with an external link, e.g. a demo. You can add or remove menu entries. You hide the menu when the switch is OFF. Don't forget to add the forward slash at the end of a menu link if it is pointing to a folder.

   Here you change the participants. You can use default values for a social network (They point to HFT's social networks) or you can use your own profiles. You can also add your personal webpage. You can add or remove a social network. You can also use a personal avatar or the default one (DEFAULT.avatar).

   Here is an example of two participants.

   Here you change the footer logos of a project's partners. If you don't want a logo to link to an external website then use the href value EMPTY_LINK. The title will appear when you hover the mouse over a logo.

   Klicken Sie anschließend auf commit changes , um die Änderungen zu speichern.

### Avatar hinzufügen

To add a personal avatar:

1. Öffnen Sie den Ordner public/assets/images
2. Klicken Sie auf das + im Oberen Bereich, und anschließend auf Upload File
3. It is recommended the avatar to be square or portrait oriented. Also, better do not upload large avatars (>500px).

### Logo hinzufügen

Um ein eigenes Projektlogo zum Projekt hinzuzufügen, müssen Sie folgende Schritte ausführen:

1. Öffnen Sie den Ordner public/assets/logos
2. Klicken Sie auf das + im Oberen Bereich, und anschließend auf Upload File

3. The logo should be square with dimentions 300x300 pixels

4. Fügen Sie die gewünschte Datei hinzu und klicken Sie auf Upload File
5. Öffnen Sie nun im Ordner public die Datei settings.js und editieren diese.

   In der Zeile mit projectLogo schreiben Sie nun DATEINAME in die Anführungszeichen, um den Pfad zum Logo anzugeben. Ein Klick auf Commit changes speichert die Datei.

6. Nun erscheint auf all Ihren Seiten das Projektlogo neben dem Logo der Hochschule.

### Neue Seite hinzufügen

Um Ihrem Projekt neue Seiten hinzuzufügen, führen Sie folgende Schritte aus:

1. Visit the templates folder and edit the index.html file. Select all the text inside this file and copy it. Then click the button cancel.
2. Klicken Sie im Ordner public auf das +, das sich oben neben dem Pfad befindet
3. Klicken Sie dort auf New File
4. Paste the text you copied from the template
5. Geben Sie die Dateinamen index.html ( wichtig: Endung .html)
6. Nun können Sie noch den Inhalt der Seite anpassen. Wenn Sie mit dem Inhalt der Seite zufrieden sind, speichern Sie sie durch Klick auf Commit changes
7. Ihre Seite wird nun automatisch auf den Server übertragen und ist unter folgender Adresse erreichbar:

   https://transfer.hft-stuttgart.de/pages/EIGENTUEMER/PROJEKTNAME/DATEINAME

### simple_raw template

This is a single page template with arbitrary content. In order to change the contents you have to edit the index.html file.

### simple_thesis template

This is a single page template for a thesis. Inside the home folder you have to replace the files with the cover of your thesis and the actual thesis file. Then you have to edit the index.html file and replace your name, year, etc.

### generic template

When you use the generic template there is an additional folder called templates. Inside this folder you will find all the available templates. In order to use a template, you have to copy the folder from templates/<template name> and paste it (when you edit your pages locally) in the root folder. Then it’s a good practice to rename this folder with the menu text you want to link it. Notice that the home page always points to the home folder. That means if you want to use a template as home page then you have to rename the folder to home.