# Upgrade

> Move a Proxus installation to a new release. Back up, pull the new images, let the hub update its database, then upgrade the edge gateways.

Source: https://proxus.io/docs/operate/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. See [Backup and restore](https://proxus.io/docs/operate/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

| Part | During an upgrade |
| --- | --- |
| Container images | Replaced by the new ones. |
| Configuration database | Kept. The hub adds what the new release needs (new tables and columns) the first time it connects to the database. |
| Telemetry database | Kept. |
| `Proxus-config.toml` | Kept as it is. Keys that are new in the release use their default value until you add them. |
| Environment variables in your compose file or manifests | Kept. |

## Upgrading to 2.0.0

Release 2.0.0 turns on TLS for every connection of the platform, with certificates from the
[Certificate Store](https://proxus.io/docs/administer/certificates). 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:
   - 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](https://proxus.io/docs/connect/edge-gateways/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](https://proxus.io/docs/administer/certificates#the-hubs-https-certificate).

**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](https://proxus.io/docs/connect/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

### 1. Back up and keep the current images

Make the backup. Then keep a copy of the images you run now, so you can go back:

```bash
docker image tag proxusplatform/proxus-ui:latest proxusplatform/proxus-ui:before-upgrade
docker image tag proxusplatform/proxus-server:latest proxusplatform/proxus-server:before-upgrade
```

### 2. Download the new images

```bash
cd /opt/proxus
docker compose -p proxus pull
```

If the host has no internet access, load the images you received with `docker load -i <file>` instead. See
[Install without internet access](https://proxus.io/docs/operate/offline-install#upgrade-without-internet-access).

### 3. Recreate the containers

```bash
docker compose -p proxus up -d
```

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

### 4. Sign in and check

1. Open the hub in the browser and sign in. The hub checks the database against the new release and updates it.
   This can take a while on a large database; do not stop the container meanwhile.
2. Check the version at the bottom of the menu (**Version:**) and look at **Platform > System Logs** for errors.

If the database update fails, the hub shows an error instead of the sign-in page and writes the reason to its output.
Keep the message (`docker compose -p proxus logs proxus-ui`) and contact Proxus support. To go back, tag the
`before-upgrade` images as `latest` again (`docker image tag proxusplatform/proxus-ui:before-upgrade
proxusplatform/proxus-ui:latest`, and the same for `proxus-server`), restore the backup and start the stack.

> **Warning:**
The shipped compose file uses the `latest` tag. Every `pull` gets the newest release, also when you only meant to
recreate a container or move to a new machine. Pull only when you plan to upgrade.

## 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.

```bash
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:

```bash
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](https://proxus.io/docs/connect/edge-gateways/install-a-gateway).

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

> **Warning:**
When you upgrade from a release before 2.0.0, pulling the new image is not enough: the gateway also needs the new
TLS settings of the install command. Run a new install command on each gateway host, as described in
[Upgrading to 2.0.0](#upgrading-to-200).

## After the upgrade

- If you use [white labeling](https://proxus.io/docs/administer/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](https://proxus.io/docs/operate/backup-and-restore)
- [Monitoring](https://proxus.io/docs/operate/monitoring)