Upgrade

Die offizielle Methode, um die Platform auf eine neue Version zu aktualisieren, besteht ausschließlich darin, den Installations-Oneliner auf demselben Server erneut auszuführen. Führen Sie ihn einfach erneut aus, ohne vorherige Löschung oder Bereinigung. Die Betriebsskripte, die compose-Datei und die Images der neuen Version werden dabei mitinstalliert, ebenso wie neue Dienste, die in der aktuellen Version eingeführt wurden (z. B. Vor-Ort-App).

Informationen darüber, welche Schnittstellen pro Version angepasst werden müssen und welche Vorgänge beim ersten Start ablaufen, finden Sie in den Upgrade-Notes. Dieses Dokument beschreibt das Verfahren, die Upgrade-Notes die versionsspezifischen Besonderheiten.

Unterstützungsbereich

Unterstützt werden die letzten drei Versionen ab Version 2026.11. Versionen 2026.10 oder älter können nicht aktualisiert werden; führen Sie in diesem Fall eine Neuinstallation durch (bei einem Upgrade-Versuch schlägt dieser fehl und das System wird automatisch auf die ursprüngliche Version zurückgesetzt).

Zeitpunkt

Führen Sie das Upgrade durch, wenn eine neue Version veröffentlicht wurde. Der Oneliner installiert die aktuelle Version vom Download-Server.

Vor jedem Release wird im Staging-Bereich ein Upgrade von der vorherigen Version → aktuellen Version genau nach diesem Verfahren durchgeführt, um sicherzustellen, dass Daten erhalten bleiben und die Migration erfolgreich abgeschlossen wird.

Vorbereitung

1. Überprüfen Sie die regulären Backups. Der Oneliner führt unmittelbar vor dem Upgrade ein automatisches Backup durch, welches jedoch primär der Wiederherstellung dient. Stellen Sie gemäß Backup und Wiederherstellung sicher, dass aktuelle regelmäßige Backups von PostgreSQL und Aster TSDB vorhanden sind.
2. Prüfen Sie den Festplattenplatz. Da das automatische Backup das gesamte Datenvolume kopiert, muss am Backup-Ort (Standard /var/backups/kopens/upgrade) ausreichend freier Speicherplatz vorhanden sein, der die Größe des Volumes übersteigt.
3. Lesen Sie die Upgrade-Notes der Zielversion. In einigen Versionen wurden Bezeichnungen geändert, sodass Schnittstellen gemeinsam mit dem Server aktualisiert werden müssen.
4. Sichern Sie manuelle Änderungen an bin/env.sh. Da der Oneliner den Installationsordner (/opt/kopens/plantpulse-platform-docker) löscht und neu herunterlädt, gehen dort vorgenommene Änderungen verloren. Hinterlegen Sie Konfigurationen in den unten genannten Server-Dateien.

Erhalten bleibt	Ort
Daten	Docker-Volume pp-data · pp-temp · pp-backup · pp-opcua-pki
Dienst-Credentials · Konfiguration (Sidecar)	/etc/kopens/plantpulse-platform.env — Zeilen mit Werten werden beibehalten
Serverspezifische Werte (externe IP etc.)	/etc/kopens/platform.node.env
Worker-Liste	/etc/kopens/workers.roster
Platform Root CA	/etc/kopens/ca/
Zeitzone · Sprache	Die durch die vorherige Installation im Sidecar hinterlegten PP_TZ · PP_LANG werden beibehalten

Verfahren

Verbinden Sie sich per SSH mit dem Server und führen Sie den gleichen Befehl aus wie bei der Installation.

sudo -i
curl -fsSL https://product.kopens.io/plantpulse-platform/install.sh | bash

Falls Sie Firewall-Regeln manuell verwalten, fügen Sie wie bei der Installation --skip-fw hinzu.

curl -fsSL https://product.kopens.io/plantpulse-platform/install.sh | bash -s -- --skip-fw

Es ist nicht erforderlich, den Stack vorab zu stoppen oder zu löschen. Der Oneliner führt folgende Schritte aus:

1. Herunterladen der Betriebsskripte und der compose-Datei der neuen Version neben den Installationsordner.
2. Bei vorhandenem Stack: Erkennung als Upgrade und Durchführung eines Backups ([1/4] An installed stack (…) was found - this run is an UPGRADE) — siehe unten.
3. Ersetzen des Installationsordners durch die neue Version und Durchführung der Vorab-Prüfung (preflight.sh).
4. Falls Docker bereits läuft, wird die OS-Konfiguration übersprungen. Firewall-Regeln werden neu angepasst — dabei werden auch Ports für neue Versionen geöffnet (bestehende Regeln bleiben erhalten).
5. Im Sidecar werden Zeilen mit Werten beibehalten; nur neue Einträge der aktuellen Version werden ergänzt.
6. Herunterladen der neuen Images und Neustart des Stacks. Die Volumes werden beibehalten.
7. Warten auf drei aufeinanderfolgende erfolgreiche Boot-Validierungen (maximal 25 Minuten).

Falls die neue Version Migrationen enthält, dauert der erste Start länger. Der Oneliner wartet, bis die Migrationen abgeschlossen sind, bevor der Stack vollständig gestartet wird. Die geschätzte Dauer pro Version finden Sie in den Upgrade-Notes.

Automatisches Backup und Vorab-Prüfung

Auf einem installierten Server ruft der Oneliner vor jeder Änderung bin/upgrade-backup.sh der neuen Version auf. Wenn die Prüfung fehlschlägt oder das Backup nicht erfolgreich ist, wird keine Änderung vorgenommen und der alte Stack wird einfach wieder gestartet.

Schritt	Aktion	Bei Ablehnung
1	Prüfung: Version alt → Version neu innerhalb der letzten 3 Versionen	Ausgabe des Grundes und Ablehnung. Ältere Versionen müssen stufenweise aktualisiert werden
2	Prüfung: Ist der aktuelle Stack im Normalzustand (status.sh)	Defekte Stacks werden nicht aktualisiert — zuerstige Reparatur erforderlich
3	Prüfung: Ausreichend Speicherplatz für Kopie des Volumes + Installationsordners	Speicherplatz freigeben oder Backup-Ort ändern (PP_UPGRADE_BACKUP_DIR)
4	Aufzeichnung der aktuellen Version und der Images pro Dienst (Digest)	—
5	Stop des Stacks über das reguläre Verfahren und Cold-Copy des Datenvolumes, /etc/kopens und des Installationsordners	Bei Kopierfehlern wird der alte Stack wieder gestartet

Backups werden in /var/backups/kopens/upgrade/<시각>-<판>/ erstellt. Nach einem erfolgreichen Upgrade werden nur die letzten zwei Backups aufbewahrt. Die Downtime beginnt mit dem Stoppen des Stacks und endet mit der erfolgreichen Boot-Validierung der neuen Version — die Zeit für die Kopie des Datenvolumes kommt hinzu.

Versionsfixierung

Obwohl der Oneliner die aktuelle Version vom Download-Server bezieht, können die Image-Versionen über PP_IMAGE_TAG im Sidecar (/etc/kopens/plantpulse-platform.env) fixiert werden.

PP_IMAGE_TAG=2026.11

Alle Dienste werden mit dieser Version gestartet; der Data Lake folgt ebenfalls, sofern nicht anderweitig definiert (PP_IMAGE_TAG_DATALAKE). Werte in /etc/kopens/platform.node.env haben Vorrang vor dem Sidecar, und dienstspezifische PP_IMAGE_TAG_<서비스> haben wiederum Vorrang vor /etc/kopens/platform.node.env. Wenn der Oneliner bei fixierter Version erneut ausgeführt wird, kommt dies einer Neuinstallation derselben Version gleich — zum Upgrade müssen die Fixierungen geändert oder entfernt werden.

Verifizierung

Der Oneliner schließt erst mit «Installation complete.» ab, wenn die Boot-Validierung erfolgreich war. Prüfen Sie das Ergebnis wie bei der Installation.

cd /opt/kopens/plantpulse-platform-docker/bin
./status.sh        # 0 = 정상 / 2 = 비정상
./ops-check.sh

curl -kfsS https://<server-ip>:4950/api/health | jq   # "status":"OK" 또는 "WARN" 이면 정상

Überprüfen Sie, ob der am Ende ausgegebene SHA-256 der Platform Root CA mit dem Wert vor dem Upgrade übereinstimmt. Bei einer erneuten Ausführung auf demselben Server bleibt die Root CA unverändert.

Die Zeitangabe in der Zeile Upgrade downtime: des Erfolgsbanners gibt die tatsächliche Stillstandszeit an. Jedes Upgrade wird protokolliert.

Protokoll	Ort
Upgrade-Historie (Zeitpunkt · Versionssprung · Erfolg/Fehler · Backup-Ort)	/etc/kopens/upgrade-history.log
Installations-Logs	/var/log/kopens/install-*.log

Neue Dienste

Wenn in der neuen Version zusätzliche Dienste eingeführt wurden, erhöht sich die Anzahl der Container in docker ps. Da der Oneliner diese über die neue compose-Datei startet, sind keine weiteren Maßnahmen erforderlich, außer der Konfiguration des jeweiligen Dienstes (Adresse, Konto etc.) gemäß der entsprechenden Dokumentation. Für die Version 2026.11 beachten Sie bitte den Abschnitt «Nach dem Upgrade» in den Upgrade-Notes.

Warnungen

Verbotene Aktion	Grund
Upgrade via ./update.sh	Kein offizielles Upgrade-Verfahren. Es werden nur Images aktualisiert; Betriebsskripte und compose-Dateien bleiben alt, wodurch neue Dienste nicht erkannt werden
Bereinigung via remove.sh · down.sh vor Neustart	Nicht erforderlich. Der Oneliner startet den Stack über dem bestehenden auf
bin/tools/remove-all-volumes.sh	Löscht Volumes — inklusive aller Daten und Backup-Volumes (pp-backup). Dieses Werkzeug ist nicht für Upgrades vorgesehen
Manuelle Änderung von bin/env.sh im Installationsordner	Wird beim nächsten Upgrade gelöscht. Änderungen sind im Sidecar oder in platform.node.env vorzunehmen

Fehlerbehebung

Wenn der Oneliner mit [ERROR] endet, werden die fehlgeschlagenen Prüfpunkte ausgegeben. Erstellen Sie basierend auf dem Status ein Diagnosepaket und senden Sie dieses an den Support.

cd /opt/kopens/plantpulse-platform-docker/bin
./status.sh
./logs.sh [서비스]
./doctor.sh        # 지원 요청용 tarball. 비밀값은 마스킹됩니다

Automatisches Rollback bei Fehlern

Bei einem fehlgeschlagenen Upgrade wird der Backup-Ort im Block UPGRADE FAILED angezeigt und das System wird standardmäßig automatisch auf die vorherige Version zurückgesetzt. Ein Rollback setzt nicht nur die Images, sondern auch die Daten auf den Zeitpunkt des Backups zurück, da die Migration der neuen Version das Schema bereits geändert haben könnte.

Nach einem Rollback gehen Daten verloren, die während der Laufzeit der neuen Version anfallen

Daten, die nach dem im Block angegebenen Zeitpunkt (Zeitpunkt des Stoppens des Stacks) eingegangen sind, sind nach dem Rollback nicht mehr vorhanden. Da das Upgrade weiterhin als «fehlgeschlagen» gilt, beheben Sie die Ursache und führen Sie denselben Oneliner erneut aus.

Um den fehlgeschlagenen Zustand für eine Diagnose beizubehalten, führen Sie den Befehl mit PP_UPGRADE_AUTO_ROLLBACK=0 aus. In diesem Fall muss das Rollback manuell über den im Block angegebenen Befehl durchgeführt werden.

/opt/kopens/plantpulse-platform-docker/bin/upgrade-rollback.sh /var/backups/kopens/upgrade/<시각>-<판>

Air-Gap-Netzwerke

In Air-Gap-Netzwerken kann der Oneliner nicht verwendet werden. Entpacken Sie das Bundle der neuen Version und führen Sie bin/airgap-load.sh erneut aus. Dabei wird der installierte Stack zunächst analog gesichert, die Images werden geladen und anschließend wird der Installer gestartet. Im Fehlerfall erfolgt analog ein automatisches Rollback. Die Methode zum Übertragen und Validieren von Bundles finden Sie unter Air-Gap-Installation. update.sh stellt auch in Air-Gap-Netzwerken kein Upgrade dar.