Upgrade

At the end of this guide, the hub and its edge gateways run the new release, with all devices, rules, users and stored values kept. You do not run database scripts yourself: the hub updates its own database.

Before you start

• A backup made just before the upgrade. The installer makes it for you; otherwise see Backup and restore. There is no way back to the old release without it.
• The release notes of the new version.
• A maintenance window. Devices are not read while the gateways restart.

What changes and what stays

Upgrading to 2.0.0

Release 2.0.0 turns on TLS for every connection of the platform, with certificates from the Certificate Store. Plan these extra steps around the normal upgrade below.

Before the upgrade

1. Make the backup as usual. The config folder (the config volume, or the hub's shared config disk on Kubernetes) now also holds keys/STORE/certificate-store.key, the key that decrypts the certificates in the store. It is created on the first start of 2.0.0, so include the config folder in every backup from then on. If you set PROXUS_CERTIFICATE_STORE_KEY instead, keep that value safe.
2. Open the new ports in your firewall: 8443 (the hub's HTTPS, on by default) on the hub host, and 8883 (MQTT over TLS) on edge gateway hosts where devices publish to the gateway's broker.

After the hub has started

3. Restart the hub's NATS server once, so it starts with TLS (the installer does this by itself):
   • Docker: docker restart hub-server
   • Kubernetes: restart the hub-server pods, for example kubectl -n proxus-ha rollout restart statefulset/hub-server (namespace proxus for the local variant).
4. Run the install command of every edge gateway again: Connect > Edge Gateways, open the gateway, select Install, and run the new command on its host. Gateways installed before 2.0.0 cannot connect to the hub until then. They keep reading their devices and buffer the data (48 hours by default), and send it once they are connected. See Install a gateway.
5. If you want browsers to trust the hub's HTTPS certificate, renew the old one: in Security > Certificate Store, select Proxus (Self-Signed) and select Renew. The new certificate is issued by the platform CA and covers the hub's names. Then install the platform CA on users' computers (Download CA). See Certificates.

Check the connections that are now verified

6. OPC UA: devices that use the security modes Sign or SignAndEncrypt send no data until their server's certificate is trusted in the store. Open Security > Certificate Store, set Trust View to Rejected, and select Trust for each server you recognise. Devices connect on their next retry. Devices with security mode None are not affected.
7. Outbound targets: a target that connects to a server with a self-signed certificate or a certificate from a private CA (for example your own MQTT broker, Splunk or an AWS IoT endpoint) worked before because nothing was checked. Upload the server's CA to the Certificate Store and choose it as the target's Trusted Server Certificate. Otherwise the connection is refused. See Outbound targets.

Where things moved

• Users, Roles and Certificate Store are now in the new Security menu, between Analyze and Platform. My Details stays under Platform.

Upgrade a Docker installation

With the installer

In the folder that contains proxus-platform, run the installer again and choose Update to … (the new release):

curl -fsSL https://proxus.io/install.sh | bash

irm https://proxus.io/install.ps1 | iex

The installer then:

1. Downloads the compose files of the new release and checks them against the release's checksums and against your settings (.env) and your own changes (docker-compose.override.yml).
2. Downloads the new images while Proxus keeps running. If anything fails up to here, nothing has changed.
3. Asks to go ahead, stops Proxus and makes a backup of its configuration (settings, configuration database, add-ons) in proxus-platform/backups/, with checksums. It checks there is enough free disk space first. The telemetry database and the message broker's data are not copied and not changed: the new release keeps using them. Back them up on their own schedule.
4. Starts the new release and waits until every service is healthy and the hub runs the new images. The hub updates its database on this first start; on a large database this takes a while.
5. Runs the steps a release needs beyond new images (for 2.0.0: restarting the message broker).

Devices are not read from step 3 until the hub is healthy again, usually a few minutes. Your settings, your override file, Keycloak and the stack's name and volumes are kept.

If the new release does not start correctly, the installer offers to go back and, unless you say no, puts the backup back and starts the previous release again. The log of the run (proxus-platform/logs/) and the hub's output are what Proxus support needs.

If the update was interrupted (closed terminal, power loss), run the installer again: it sees the unfinished update and offers to go back to the previous release with its backup, or to start the new release again.

To go back later, run the installer and choose Restore a backup. Devices, users and settings changed since that backup are replaced; stored values are kept. Going back to an older release always works through a backup: an older release cannot read a database the newer one has updated.

For an unattended update, for example from a maintenance job, add update --yes:

cd /opt && curl -fsSL https://proxus.io/install.sh | bash -s -- update --yes

It updates only when a newer release exists, and goes back automatically when the new release does not start.

Try a preview

Before a release, Proxus may publish previews of it (for example 2.1.0-preview.1) for partners who want to try it early. A preview is never offered by the installer and never becomes latest on Docker Hub: you get one only by naming it. Update to it the same way, with the same backup and automatic way back:

curl -fsSL https://proxus.io/install.sh | bash -s -- update --version 2.1.0-preview.1

On Windows: $env:PROXUS_COMMAND='update'; $env:PROXUS_VERSION='2.1.0-preview.1'; irm https://proxus.io/install.ps1 | iex. Previews are listed as pre-releases on the releases page. When the release itself comes out, a plain update moves the hub from the preview to it. Use previews on test systems first: going back from a preview to an earlier release works only through the backup made before the update.

Without the installer

For an installation you manage from a compose file yourself:

1. Make a backup.

2. In the installation folder, replace docker-compose.yml with the one of the new release (from the release), and set the new release in .env:

   .env

   PROXUS_VERSION=2.1.0

3. Download the images, then recreate the containers:

   docker compose pull
   docker compose up -d

   Compose replaces only the containers whose image or settings changed. The volumes stay.

4. Open the hub in the browser and sign in. Check the version at the bottom of the menu (Version:) and look at Platform > System Logs for errors.

If the hub shows an error instead of the sign-in page, keep its output (docker compose logs proxus-ui), set the previous release in .env again, put back the previous docker-compose.yml, restore the backup and start the stack.

If the host has no internet access, load the images you received with docker load -i <file> instead of docker compose pull. See Install without internet access.

Upgrade a Kubernetes installation

The manifests use imagePullPolicy: IfNotPresent with a fixed tag, so a node that already has the image does not download a new one by itself.

1. Make the backup, including the config volumes.
2. Set the new image tag in your kustomization (an images: entry), or set imagePullPolicy: Always.
3. Apply and restart, as below.
4. Sign in and check the version and the system logs as for Docker.

kubectl apply -k Deployment/kubernetes/ha
kubectl -n proxus-ha rollout restart deployment/proxus-ui deployment/proxus-server-gateway-1

The hub replicas are replaced one at a time, so the web interface stays available. The gateway pod is stopped and started again.

Upgrade the edge gateways

The hub's own gateway, SYSTEM, is part of the stack above and is upgraded with it. Upgrade every remote edge gateway right after the hub, so hub and gateways run the same release.

On each gateway host, the installer put the gateway in /opt/proxus/proxus-edge-<ID>, where <ID> is the gateway's ID. Pull and recreate it there:

cd /opt/proxus/proxus-edge-3
sudo docker compose -p proxus-edge-3 -f compose.yaml pull
sudo docker compose -p proxus-edge-3 -f compose.yaml up -d

Instead, you can create a new install command for the gateway in the hub and run it on the host again. It replaces the containers and gives the gateway new credentials; the old ones stop working. See Install a gateway.

Check on Connect > Edge Gateways that every gateway shows Connected again.

After the upgrade

• If you use white labeling, check that your logo is shown; upload it again if not.
• Read the release notes for new configuration keys you may want to set.

What's next

• Backup and restore
• Monitoring