Web Entwickler Dominik beschreibt in dieser Migrations-Anleitung unterschiedliche Herausforderungen und Stolpersteine beim Umzug des Versionsverwaltungstools „GitLab“. In dem dargestellten Beispiel wird die Version 10.0.2 von einem Webserver mit VM Debian v7 auf ein aktuelles Debian v10 On-Premises-System umgezogen.Dabei erleichtert der Einsatz von Docker

den Installationsprozess. Wir hoffen, dass diese Schritt-für-Schritt-Anleitung allen weiterhilft, die auch einmal das Vergnügen haben GitLab umzuziehen oder Upgrades durchführen zu müssen.

Zunächst einmal: Was ist GitLab?

Bei vielen Softwareprojekten liegt der Quellcode nicht beim Kunden, sondern in der Obhut des Dienstleisters. Hierbei bietet das dezentrale Verwaltungstool „GIT“ viele Vorteile in Bezug auf die Versionsverwaltung. Die Web-Anwendung „GitLab“ setzt noch einen oben drauf:  Entwicklerinnen und Entwickler werden mit Hilfe einer Weboberfläche bei der Nutzerverwaltung unterstützt. Ebenso ermöglicht das Tool die Integration von anderen Services wie bspw. das Ticketsystem „Easy Redmine“.

In diesem Migrationsbeispiel wurde GitLab vor etwa drei Jahren auf einem öffentlichen Webserver bereitgestellt. Bis dato: Ohne jede Art von problematischen Zwischenfällen. Im Zuge einer Umstrukturierung soll GitLab nun auf ein On-Premises-System umgezogen werden.

Herausforderungen und Stolpersteine beim Pläne schmieden

GitLab Version 10.0.2. lief bisher auf einem Debian v7 Server und soll nun auf einem aktuellen Debian v10 umgezogen werden. Schnell wurde dafür ein Plan erstellt.

Der Plan:

1. Backup auf alten Server erstellen und extrahieren.
2. Neues GitLab auf neuem Server installieren.
3. Backup auf neuen Server einspielen.

Fertig! – Nicht ganz …

„You can only restore a backup to exactly the same version and type (CE/EE) of GitLab on which it was created. “
Quelle: GitLab,  https://docs.gitlab.com/ee/raketasks/backup_restore.html (2020)

Ok. Wir brauchen also auf dem neuen Server exakt dieselbe Version von GitLab, wie auf dem Alten. Rasch ging es an einen neuen Plan.

Der neue Plan:

1. Backup auf alten Server erstellen und extrahieren.
2. Altes GitLab auf neuem Server installieren.
3. Backup auf neuen Server einspielen.
4. GitLab auf aktuelle Version upgraden.

Fertig!

GitLab selbst empfiehlt in seiner Installationsanleitung, die Installation mithilfe von „Omnibus“ vorzunehmen. Omnibus installiert alle benötigen Programme, wie zum Beispiel „PostgreSQL“, „Redis“ und „Unicorn“.

Auf der Suche nach den alten Packages stellte sich aber heraus, dass für die GitLab Version, die sich in unserem Fall im Einsatz befindet, keine Omnibus Unterstützung angeboten wird. Also stattdessen alles manuell installieren? Eine Alternative gibt es da noch: Docker.

Warum Docker? Warum eigentlich nicht.

Docker ist eine Software, die durch Containervirtualisierung eine isolierte Umgebung schafft. Hier stehen für ein Programm nur die benötigten Ressourcen bereit. In unserem Fall enthält also ein Container GitLab mit allen Programmen und Tools, die es benötigt.

Ein großer Vorteil dieser Isolation ist, dass man einen Container einfach wieder entfernen kann, ohne dabei Datenmüll zu hinterlassen, falls dieser bspw. einmal nicht richtig funktioniert. In diesem Beispiel nutzen wir Docker analog zu Omnibus. Frei nach dem Motto: Einmal hin – alles drin.

Im „DockerHub“ existiert sogar noch ein altes Containerpaket für die Version GitLab 10.0.2 – YEAH!
Nun muss nur noch ein neuer verbesserter Plan her.

Der verbesserte neue Plan:

1. Backup auf dem alten Server erstellen und extrahieren.
2. Docker und GitLab Container installieren.
3. Backup auf dem neuen Server einspielen.
4. GitLab auf die aktuelle Version upgraden.

Ok. Der Plan steht. Legen wir los!

Umsetzung & Linux-Shell-Befehle

Im Folgenden werden die notwendigen Schritte sowie die entsprechenden Linux-Shell-Befehle beschrieben:

1. Backup auf dem alten Server erstellen und extrahieren:
   GitLab legt Backups standardmäßig unter „/var/opt/gitlab/backups“ ab. Das in Kürze angelegte Backup kann von dort extrahiert werden.

Jetzt noch extrahieren. In unserem Fall habe ich die „Backup .tar-Datei“ in den FTP-Download-Bereich kopiert und von dort heruntergeladen. Alternativ könnte man auch SCP verwenden:

2. Docker & GitLab Container installieren
Als erstes installieren wir uns Docker im Debian. Hier muss darauf geachtet werden, dass die Hardwareanforderungen erfüllt sind.

Als nächstes installieren wir den älteren GitLab-Container 10.0.2-ee.0.

Zu den –volume:
GitLab speichert verschiedene Einstellungen, Logs und Backups verteilt in verschiedenen Linux Dateiverzeichnissen (/etc , var/log, /var/opt) ab. Damit wir auch außerhalb des Containers mit diesen Daten arbeiten können und diese persistiert sind, mounten wir die drei Verzeichnisse  nach /home/gitlab/*.

Noch ein Blick, ob die Benutzeroberfläche von GitLab erreichbar ist:

Perfekt! Wir sind startklar für Schritt Nummer 3 aus unserem Plan.

3. Backup auf den neuen Server einspielen
   Zunächst  benötigen wir die Backup-Datei auf dem neuen Server. In diesem Fall nutze ich SFTP und kopiere so das Backup in das Home-Verzeichnis. Alternativ könnte man auch SCP verwenden.

GitLab braucht ein bis zwei Minuten bis es wieder neu gestartet ist. Prüfen wir nun die Weboberfläche von GitLab, stellen wir fest: Das Backup hat erfolgreich alle Daten wieder eingespielt. Sogar das Logo von unserem „SampleMe“-Beispiel ist wieder am oberen Bildrand zu erkennen :)

4. GitLab auf die aktuelle Version upgraden
   Jetzt nur noch schnell GitLab von 10.0.2 auf die aktuelle Version (12.9.) upgraden und …CRASH!
   Leider musste ich die schmerzliche Erfahrung machen, dass ein direkter Sprung von GitLab 10 auf 12 nicht möglich ist.

„It is considered safe to jump between patch versions and minor versions within one major version.“
 Quelle: GitLab, https://docs.gitlab.com/ee/policy/maintenance.html#version-12-onwards-extra-step-for-major-upgrades (2020)

Hier ist also ein Step-by-Step-Upgrade nötig:  10.0.2 => 11.0.0 => 11.11.0 => 12.0.0 => latest (12.9.2)
Darum müssen folgende Schritte für jede CONTAINERVERSION wiederholt werden:

• 0.0-ee.0
• 11.0-ee.0
• 0.0-ee.0
• 9.1-ee.0
• latest

Fazit

Cool, jetzt haben wir also GitLab Version 10.0.2 von Server A nach Server B umgezogen und GitLab auf den aktuellen Stand geupgraded. Dabei gab es zwar einige Hürden, für diese gab es aber auch immer eine Lösung. Die Möglichkeit Docker hier einzusetzen hat die Arbeit wesentlich erleichtert. Doch eines sollte man sich merken: Das Upgraden mit zwei Major-Sprüngen kann einfach verhindert werden, indem man regelmäßige Updates durchführt. Also: Einfach dranbleiben!

Ich wünsche auf jeden Fall allen viel Erfolg, die sich dieser Herausforderung stellen und hoffe diese Anleitung hilft anderen weiter.

Euer Dominik