Upgrade
The official way to upgrade the Platform to a new version is simply to re-run the installation one-liner on the same server. Run it again as is, without deleting or cleaning up. This process deploys the operational scripts, compose files, and images of the new version, and also deploys new services (e.g., Frontline App) introduced in the new version.
For version-specific integration changes and first-boot behavior, refer to the Upgrade Notes. This document describes the procedure, while the Upgrade Notes describe version-specific precautions.
The support range covers the three most recent versions since version 2026.11. Upgrades are not supported for versions 2026.10 and below; please perform a clean installation (attempting an upgrade will result in failure and the system will automatically roll back to the original version).
When to Upgrade
Upgrade when a new version is released. The one-liner installs the current version available on the download server.
Releases are issued after verifying that an upgrade from the previous version → current version on staging follows this procedure, ensures data persistence, and completes the migration.
Before You Begin
- Verify routine backups. Although the one-liner performs an automatic backup immediately before the upgrade, that backup is for rollback purposes. Ensure that regular backups of PostgreSQL and Aster TSDB are up to date as per Backup and Recovery.
- Check disk space. Automatic backup copies the entire data volume; therefore, there must be sufficient free space at the backup location (default
/var/backups/kopens/upgrade) exceeding the volume size. - Read the Upgrade Notes for the target version. Some versions may require updating integrations along with the server due to name changes.
- Migrate any manual modifications made to
bin/env.sh. The one-liner deletes and re-downloads the installation folder (/opt/kopens/plantpulse-platform-docker), so any modifications within it will be lost. Store configurations in the server-side files listed below.
| Persisted Items | Location |
|---|---|
| Data | Docker volumes pp-data · pp-temp · pp-backup · pp-opcua-pki |
| Service credentials · configuration (sidecar) | /etc/kopens/plantpulse-platform.env — Lines with values are preserved |
| Server-specific values (External IP, etc.) | /etc/kopens/platform.node.env |
| Worker list | /etc/kopens/workers.roster |
| Platform Root CA | /etc/kopens/ca/ |
| Timezone · Language | Uses PP_TZ · PP_LANG left by the previous installation in the sidecar |
Procedure
Connect to the server via SSH and execute the same command used during installation.
sudo -i
curl -fsSL https://product.kopens.io/plantpulse-platform/install.sh | bash
If you manage firewall rules manually, append --skip-fw as you did during installation.
curl -fsSL https://product.kopens.io/plantpulse-platform/install.sh | bash -s -- --skip-fw
There is no need to stop or remove the stack first. The one-liner performs the following steps:
- Downloads the new version's operational scripts and compose files next to the installation folder.
- If an installed stack exists, it identifies it as an upgrade and performs a backup first (
[1/4] An installed stack (…) was found - this run is an UPGRADE) — see below. - Replaces the installation folder with the new version and performs a pre-inspection (
preflight.sh). - If Docker is already running, OS configurations are skipped. Firewall rules are re-applied — ports introduced in the new version are opened at this time (existing rules are preserved).
- For the sidecar, lines with values are kept, and only items newly introduced in the new version are filled.
- Downloads new images and restarts the stack. Volumes are re-attached as they were.
- Waits until boot verification passes three consecutive times (maximum 25 minutes).
If the new version includes a migration, the first boot will take longer. The one-liner waits for the migration to complete before fully starting the stack. Estimated times per version are listed in the Upgrade Notes.
Automatic Backup and Pre-inspection
On an installed server, the one-liner calls bin/upgrade-backup.sh of the new version before changing anything. If the inspection is rejected or the backup fails, it ends by restarting the old stack without changing anything.
| Step | Action | When Rejected |
|---|---|---|
| 1 | Whether installed version → new version is within the recent 3 versions | Logs the reason and rejects. Update stepwise for older versions |
| 2 | Whether the current stack is healthy (status.sh) | Broken stacks are not upgraded — fix first |
| 3 | Whether there is space to copy the entire volume + installation folder | Free up space or change backup location (PP_UPGRADE_BACKUP_DIR) |
| 4 | Record current version and image (digest) per service | — |
| 5 | Stop the stack via normal procedure and cold copy data volumes · /etc/kopens · installation folder | Restarts old stack if copying fails |
Backups are created at /var/backups/kopens/upgrade/<시각>-<판>/, and upon a successful upgrade, only the two most recent backups are retained.
Downtime occurs from the moment the stack is stopped until the new version passes verification — this includes the time required to copy data volumes.
Version Pinning
While the one-liner downloads the current version from the download server, the image version can be pinned using PP_IMAGE_TAG in the sidecar (/etc/kopens/plantpulse-platform.env).
PP_IMAGE_TAG=2026.11
All services will boot with that version, and the data lake will follow unless specified otherwise (PP_IMAGE_TAG_DATALAKE).
The value in /etc/kopens/platform.node.env takes precedence over the sidecar, and per-service PP_IMAGE_TAG_<서비스> takes precedence over that.
Running the one-liner while a version is pinned results in re-installing the same version — change or remove the pin when upgrading.
Verification
The one-liner completes with «Installation complete.» only after passing boot verification. Once finished, verify as you did during 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" 이면 정상
Check if the SHA-256 of the Platform Root CA printed at the end is the same as before the upgrade. The Root CA remains unchanged when re-running on the same server.
The Upgrade downtime: line in the success banner indicates the actual downtime. Results are recorded for every upgrade.
| Record | Location |
|---|---|
| Upgrade history (When · From version to version · Success/Failure · Backup location) | /etc/kopens/upgrade-history.log |
| Installer log | /var/log/kopens/install-*.log |
New Services
If the number of services increases in a new version, the container count in docker ps will increase. Since the one-liner deploys the new compose file, no separate action is needed; simply enter the configuration (address, account, etc.) for that service as per its documentation. For version 2026.11, refer to the «After Upgrade» section of the Upgrade Notes.
What Not to Do
| Action to Avoid | Reason |
|---|---|
Upgrading via ./update.sh | Not the official upgrade procedure. It only changes images while keeping old operational scripts and compose files, meaning it will not recognize services introduced in the new version |
Cleaning up with remove.sh · down.sh before re-running | Unnecessary. The one-liner deploys over the existing stack |
bin/tools/remove-all-volumes.sh | Deletes volumes — including data and backup volumes (pp-backup). This is a tool unrelated to upgrades |
Modifying bin/env.sh inside the installation folder | Will be deleted during the next upgrade. Place modifications in the sidecar or platform.node.env |
Troubleshooting
If the one-liner ends with [ERROR], the failed inspection items are printed. Diagnose the state and contact support with a diagnostic bundle.
cd /opt/kopens/plantpulse-platform-docker/bin
./status.sh
./logs.sh [서비스]
./doctor.sh # 지원 요청용 tarball. 비밀값은 마스킹됩니다
Automatic Rollback on Failure
If an upgrade fails, the backup location is printed in the UPGRADE FAILED block, and the system automatically rolls back to the previous version by default.
Rollback reverts not just the images, but the data back to the backup point, as the new version's migration may have already altered the schema.
Data received after the timestamp in the block (the time the stack was stopped) will be lost after the rollback. Since the upgrade itself is still marked as «Failed», resolve the cause and run the same one-liner again.
To diagnose the failed state without rolling back, run with PP_UPGRADE_AUTO_ROLLBACK=0. In this case, manually roll back using the command printed in the block.
/opt/kopens/plantpulse-platform-docker/bin/upgrade-rollback.sh /var/backups/kopens/upgrade/<시각>-<판>
Air-gapped Network
The one-liner cannot be used in air-gapped networks. Unpack the new version bundle and re-run bin/airgap-load.sh within it.
The process is as follows: first back up the installed stack in the same manner, load the images, and then run the installer; if it fails, it will automatically roll back in the same way.
Instructions for transferring and verifying the bundle are in Air-gapped Installation. update.sh is not for upgrades in air-gapped networks.