Upgrading to v1.2.0

Koios v1.2.0 supports a direct upgrade from v1.1.x, v1.0.x, and v0.10.x. Database migrations run automatically the first time the new container starts, and the entrypoint takes a pre-migration backup before running them. Before you begin, follow the general update procedure to pull the new image and restart the service.

v1.2.0 has not been released yet

This guide covers a release still under active development. The steps below reflect what has landed so far and may change before general availability. See the v1.2 release notes for the current feature list.

Before You Upgrade

Review each of these against your system. Every one of them changes behavior on first boot:

Models with duplicate input binding order will stop. Two input bindings on the same model can no longer share a binding order. Binding order is not editable on the Bindings page — Koios assigns it from the model file — so renumbering means exporting the model's bindings to CSV, giving each input a distinct order, and importing the file back. See Model Configuration Errors.
Renamed built-in roles do not receive new permissions. If you renamed a role such as Engineer or Administrator, the upgrade skips it and prints a warning naming the permission instead. Grant Component Stacks, the Audit Trail view and export permissions, and web interface certificate management by hand. See Roles & Permissions.
Modbus TCP reads get larger. A hidden cap previously limited every read to 50 registers. Max Registers Per Read (1–125, default 125) is now the only limit. Lower it to the device's published limit if the device rejects large blocks. See Device Parameters.
Integrations may break. Events can no longer be created or edited through the API, the root-event grouping header is gone, and a few filter and sort fields that never worked were removed. Review any integration that writes or groups events. See API Clients.
The component environment list page is gone. Environments are opened and managed from the workspace, and environment bulk actions no longer exist. See Component Environments.

Back up first

The entrypoint saves a pre-migration database backup automatically, but a full volume backup before any upgrade is still the safest practice.

From v1.1.x

This is a drop-in upgrade. No volume or configuration changes are needed:

Pull the new image and restart the service, following Updating Koios.
Migrations run automatically on first boot.
Confirm the new version under System > Overview.

Your existing devices, tags, models, bindings, and component environments carry forward.

From v1.0.x

Also a drop-in upgrade — the seven volume mounts are unchanged. Follow the same three steps as v1.1.x. Nothing introduced between v1.0.x and v1.2.0 requires a service file change.

From v0.10.x

A v0.10.x upgrade needs the same one-time change introduced in v1.0.0: the koios_secrets volume must be mounted so runtime secrets are generated and preserved across restarts. Complete the v1.0.0 migration steps to add the seventh volume mount to your service file, then proceed with the standard update. Your existing credentials are detected and preserved.

The secrets volume is required

The container refuses to start if any of its seven volume mounts is missing and logs FATAL: Required Docker volume mounts missing, listing the paths it could not find. Make sure koios_secrets is mounted before you start the new image. See Migrating to v1.0.0 for the exact mount.

No New Volumes

Component stacks — the isolated package sets introduced in this release — are stored alongside your other uploaded files on the existing media volume. Upgrading needs no service file change and no eighth mount.

Kubernetes deployments

On Kubernetes the chart's default media volume size increases, because that volume now also backs component stacks. If your storage class does not allow volume expansion, pin the previous size in your values file before upgrading.

After Upgrading

Confirm the version under System > Overview.
Check System > Service Status to verify every service is running.
Check your renamed roles for the new permissions listed above.
Confirm any model that was stopped by a duplicate binding order is running again.
If you are upgrading from v1.0.x or v1.1.x, open Components > Libraries. The Core Library now ships as version 1.0.0, without the release-candidate tag it carried before, and the new version is added alongside the one you are running rather than replacing it. Your environments keep running the version they already use until you activate the new one. The components are identical, so activating it is safe and the preview shown before you confirm reports no component changes. Installs coming from v0.10.x, and new installs, start on 1.0.0 with nothing to do. See Component Libraries.
Review the v1.2 release notes for new features.

What's Next

Updating Koios: the general update procedure for any version.
v1.2 Release Notes: everything new in this release.
Backing Up Docker Volumes: back up before you upgrade.

Updating Koios Upgrading to v1.1.0