Zum Inhalt

Image-Version anheben

Vor jedem Update den Changelog lesen

Dreh nie nur den Tag hoch. Zwischen der alten und der neuen Version können Breaking Changes liegen, geänderte oder entfernte Einstellungen, Datenbank-Migrationen oder Zwischenversionen, die man nicht überspringen darf. Lies deshalb den Changelog aller Versionen zwischen der alten und der neuen, nicht nur den der neuen.

Ziel

Eine App läuft auf einer neueren Version ihres Images, mit allen dafür nötigen Änderungen an der Konfiguration, und der Versionssprung steht nachvollziehbar im Repo.

Voraussetzungen

  • du kannst eine Änderung ausrollen (Änderung ausrollen); diese Anleitung folgt ihren Schritten und sagt nur, was bei einem Update dazukommt
  • gelesen: Podman, die Seite der App unter Anwendungen, vor allem die Abschnitte „Updates“ und „Backup“, und Backup

Schritte

1. Neuesten Stand holen und plan ausführen

Wie in Änderung ausrollen, Schritt 1 bis 3, im Ordner des Hosts, auf dem die App läuft.

Erwartet: No changes detected. All units are up to date.

2. Aktuelle und neue Version notieren

Öffne die Stack-Datei der App (syslet/<host>/stack-<app>.cue; welche, steht auf der Seite der App unter „Wo es liegt“). Bei den meisten Apps steht der Tag oben in der Datei, etwa in syslet/werner/stack-hedgedoc.cue:

Text Only
1
image: hedgedoc: tag: "1.12.0"

Bei Images, die nur ein Begleiter der App sind, etwa die Datenbank, steht der Tag direkt in der Zeile Image: des Containers, zum Beispiel Image: "docker.io/library/postgres:17.10-alpine".

Die neue Version suchst du dir in den Release Notes der App heraus; der Link steht auf ihrer Seite unter „Updates“. Nimm eine Version, die wirklich als Release veröffentlicht ist, keine Vorabversion (-rc, -beta).

Steht auf der Seite der App, dass wir das Image selbst bauen (Discourse, Engelsystem, Membertool), muss die neue Version erst gebaut und bereitgestellt werden; wie, steht dort unter „Updates“ und „Besonderheiten“.

3. Changelog lesen

Lies die Release Notes jeder Version zwischen der alten und der neuen, von der ältesten zur neuesten. Notiere dir alles, was eine dieser Fragen mit Ja beantwortet:

  • Ändert sich eine Einstellung, die wir in der Stack-Datei setzen (unter Environment:, in eingebundenen Konfigurationsdateien), oder fällt sie weg?
  • Kommt eine Einstellung neu dazu, die gesetzt werden muss?
  • Muss eine bestimmte Zwischenversion zuerst installiert werden?
  • Wird die Datenbank migriert, oder braucht es eine neue Version der Datenbank?
  • Steht unter „Updates“ auf der Seite der App eine Stolperfalle von früheren Updates?

Bei PostgreSQL hebst du ohne Absprache nur die Nebenversion an, also die Zahl hinter dem Punkt (17.10 → 17.11). Eine neue Hauptversion (17 → 18) kann die vorhandenen Daten nicht lesen; frag dafür in Signal nach.

Ist dir unklar, was eine Änderung für uns bedeutet, frag in Signal nach, bevor du weitermachst.

4. Letztes Backup prüfen

Für Apps auf werner, im Ordner syslet/werner:

Bash
1
cue cmd -t unit=system-backup.service status

Erwartet: in der Zeile Active: inactive (dead) since … mit dem Datum der letzten Nacht, und in der Zeile Process: status=0/SUCCESS.

Steht dort ein älteres Datum oder status=1/FAILURE, ist das letzte Backup nicht in Ordnung: kein Update, sondern zuerst Wenn healthchecks.io einen Fehler meldet.

Ob die App überhaupt gesichert wird, steht auf ihrer Seite unter „Backup“. Apps ohne Backup, etwa alle auf containerhost, kannst du bei einem Fehler nur auf die alte Version zurücksetzen, nicht ihre Daten wiederherstellen; bei einer Datenbank-Migration (Schritt 3) frag in diesem Fall vorher in Signal nach.

5. Tag und Konfiguration ändern

Trag in der Stack-Datei die neue Version ein, etwa:

Text Only
1
image: hedgedoc: tag: "1.12.1"

Ändere im selben Zug alle Einstellungen, die du in Schritt 3 notiert hast. Musst du über eine Zwischenversion gehen, trag zuerst nur diese ein und durchlauf die Schritte 5 bis 9 für sie, dann noch einmal für die Zielversion.

Formatieren wie in Änderung ausrollen, Schritt 5.

6. plan ausführen

Bash
1
cue cmd plan

Erwartet: unter Images to pull: das neue Image, unter Unit file changes: beim Container der App [Container] Image mit old: und new: und, falls du Einstellungen geändert hast, auch diese. Ein Beispiel steht in Änderung ausrollen, Schritt 6.

Zeigt plan mehr, roll nicht aus, sondern geh nach plan zeigt unerwartete Änderungen vor.

7. Ausrollen

Bash
1
cue cmd apply

Erwartet: dieselbe Ausgabe wie bei plan, dann Continue? (yes/no); tippe yes. apply lädt das neue Image und startet den Container neu; die App ist dabei kurz nicht erreichbar.

8. App und Logs prüfen

Sieh in die Logs des Containers, den du aktualisiert hast, etwa hedgedoc-server:

Bash
1
cue cmd -t unit=hedgedoc-server.service logs

Erwartet: die App startet ohne Fehlermeldungen; bei einer Datenbank-Migration erscheinen dazu Meldungen, die mit einer Erfolgsmeldung enden. Mit Ctrl+C beendest du die Ausgabe.

Öffne dann die Adresse der App im Browser, melde dich an und probier aus, was die meisten Leute damit tun, etwa ein Dokument öffnen und bearbeiten.

Danach noch einmal:

Bash
1
cue cmd plan

Erwartet: No changes detected. All units are up to date.

9. Committen und pushen

Wie in Änderung ausrollen, Schritt 9 und 10. Die erste Zeile der Commit-Message nennt App, alte und neue Version, darunter stehen der Link auf die Release Notes und die Einstellungen, die du geändert hast:

Text Only
1
2
3
update hedgedoc from 1.12.0 to 1.12.1

Release Notes: https://hedgedoc.org/releases/

Nicht so: update backrest to 1.14.1 (7966c87) nennt weder die alte Version noch die Release Notes. Ein gutes Beispiel mit geänderter Konfiguration ist update nextcloud to 20260825_084538.

Prüfen

  • Die App ist unter ihrer Adresse erreichbar, du kannst dich anmelden, und sie tut, was sie soll.
  • In den Logs stehen nach dem Start keine Fehler.
  • cue cmd plan zeigt „No changes“, und git status zeigt Your branch is up to date with 'origin/main'.

Wenn etwas schiefgeht