Letzte Aktualisierung am 27.06.2026, 22:06:17 Uhr

Mit der Veröffentlichung von Uptime Kuma 2.0 steht ein bedeutendes Upgrade an. Da ich selbst Uptime Kuma produktiv einsetze, habe ich mich intensiv mit den Änderungen und dem Migrationsprozess beschäftigt.

Die neue Hauptversion bringt zahlreiche Verbesserungen bei Performance und Datenhaltung mit sich, enthält aber auch einige Breaking Changes, die vor einem Upgrade berücksichtigt werden sollten.

In diesem Artikel zeige ich, worauf bei der Migration von Uptime Kuma v1 auf v2 zu achten ist und wie das Upgrade möglichst reibungslos gelingt.

Warum auf Uptime Kuma 2.0 wechseln?

Der wichtigste technische Fortschritt in Version 2 liegt in der Überarbeitung der Datenhaltung. Während der Migration werden bestehende Heartbeat-Daten in ein neues, optimiertes Format überführt. Dadurch verbessert sich insbesondere die Performance bei größeren Installationen mit vielen Monitoren und umfangreichen Historien.

Allerdings bedeutet diese Umstellung auch, dass die Migration je nach Datenmenge einige Zeit in Anspruch nehmen kann.

Backup ist Pflicht

Die Entwickler weisen mehrfach darauf hin, vor dem Upgrade ein vollständiges Backup des data-Verzeichnisses anzulegen. Tatsächlich wird dies in der offiziellen Anleitung besonders hervorgehoben.

Vor dem Start der eigentlichen Migration empfiehlt es sich daher, folgende Vorbereitungen zu treffen:

1. Uptime Kuma stoppen
2. Das gesamte data-Verzeichnis sichern
3. Die Sicherung überprüfen
4. Während der Migration keine Unterbrechung verursachen

Dieser letzte Punkt ist besonders wichtig. Wird der Migrationsprozess unterbrochen oder abgebrochen, kann die Migration nicht einfach fortgesetzt werden. Stattdessen muss zunächst das zuvor erstellte Backup zurückgespielt und der gesamte Vorgang erneut gestartet werden.

Als Unterbrechung gelten beispielsweise das Stoppen des Containers, ein Neustart des Servers oder andere Eingriffe, die den laufenden Prozess beeinflussen.

Wie lange dauert die Migration?

Die Dauer hängt stark von der Größe der Datenbank ab. Laut Entwicklerangaben benötigte eine Installation mit 20 Monitoren und 90 Tagen Historie etwa sieben Minuten. Größere Umgebungen können deutlich länger benötigen. in Einzelfällen berichten Nutzer von mehreren Stunden Migrationszeit.

Um den aktuellen Fortschritt zu verfolgen und mögliche Fehler frühzeitig zu erkennen, empfiehlt es sich, die Container-Logs während des gesamten Vorgangs zu überwachen.

Dies kann bequem mit folgendem Befehl erfolgen:

docker compose logs -f

In meiner Umgebung werden aktuell 82 Monitore überwacht. Wobei die gespeicherten Historiedaten bis ins Jahr 2023 zurückreichen. Das data-Verzeichnis hatte zum Zeitpunkt der Migration eine Größe von rund 19 GB.

Entsprechend zeit intensiv fiel auch der Migrationsprozess aus: Die vollständige Migration benötigte in meinem Fall etwas mehr als zwei Tage. Betrieben wird die Instanz auf einem Cloud-Server von Hetzner. Wer ebenfalls eine größere Uptime-Kuma-Installation mit mehreren Jahren Historie betreibt, sollte daher ausreichend Zeit für die Migration einplanen und keinesfalls von einer Dauer von nur wenigen Minuten oder Stunden ausgehen.

Besonderheit bei der Nutzung von Traefik

Wer Uptime Kuma hinter einem Reverse Proxy wie Traefik betreibt, muss für die Migration einige zusätzliche Anpassungen an der Docker-Compose-Konfiguration vornehmen. Es genügt nicht, lediglich den Image-Tag auf die neue Version zu ändern.

Für die Dauer der Migration muss der Abschnitt ports in der docker-compose.yml ergänzt werden, damit Uptime Kuma direkt über den entsprechenden Port erreichbar ist. Gleichzeitig sollten die Traefik-spezifischen Konfiguration Abschnitte, beispielsweise Labels für das Routing, vorübergehend auskommentiert werden.

Nach erfolgreichem Abschluss der Migration können die Änderungen wieder rückgängig gemacht werden. Die ports-Direktfreigabe wird entfernt und die ursprüngliche Traefik-Konfiguration wieder aktiviert. Erst danach sollte die Instanz wieder regulär über den Reverse Proxy bereitgestellt werden.

Es empfiehlt sich, vor den Änderungen eine Sicherung der docker-compose.yml anzulegen, um bei Problemen schnell auf die ursprüngliche Konfiguration zurückkehren zu können.