Backup and restore

At the end of this guide, you have a copy of everything a Proxus hub needs to start again with all its devices, rules, users, stored values and gateway connections, and you know how to restore it.

Before you start

• The hub runs with the shipped docker-compose.yml (see Docker). Its volume names start with the stack's name: COMPOSE_PROJECT_NAME in .env, which is proxus for new installations and proxus-platform for installations made with an earlier installer. The commands below use it as $P.
• A backup location outside the hub's machine, with room for the telemetry database.
• Shell access to the host with permission to run docker.

Back up and restore the configuration with the installer

In the folder that contains proxus-platform, run the installer and choose Back up the configuration now, or run it with a command:

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

The installer measures the configuration and checks that there is enough free disk space, stops Proxus (devices are not read meanwhile, usually under a minute), copies the configuration, verifies the copies and starts Proxus again. It does not copy the telemetry database (clickhouse_data) or the message broker's data (nats), and never changes them: after a restore Proxus keeps using them. Each backup is a folder in proxus-platform/backups/, named by its time and release, with:

To restore, run the installer and choose Restore a backup, or name the backup:

curl -fsSL https://proxus.io/install.sh | bash -s -- restore --backup 20261028-063634-v2.1.0

Proxus goes back to that backup's configuration and release, and the installer waits until it is healthy. Devices, users and settings changed since the backup are replaced; stored values are kept.

To back up the configuration every night, run the installer from the system's scheduler, for example with cron at 02:30:

30 2 * * * cd /opt && curl -fsSL https://proxus.io/install.sh | bash -s -- backup --yes >/dev/null 2>&1

What to back up

All data of the stack is in five Docker volumes. Their names start with the stack's name, for example proxus_config:

Also keep a copy of your docker-compose.yml with your changes.

Check the stack's name and the exact volume names on your host, in the installation folder:

P=$(sed -n 's/^COMPOSE_PROJECT_NAME=//p' .env); P=${P:-$(basename "$PWD")}
docker volume ls --filter "label=com.docker.compose.project=$P"

If you give the hub its Certificate Store key with the environment variable PROXUS_CERTIFICATE_STORE_KEY instead of the file, keep that value with your backups.

Make a full backup (stack stopped)

A copy of the volumes while the stack is stopped is consistent: the databases are not writing. Devices are not read while the stack is stopped, so plan it outside production hours, for example every night or every week.

In the installation folder, with $P set as above:

BACKUP=/backup/proxus/$(date +%F)
mkdir -p "$BACKUP"
cp docker-compose*.yml .env "$BACKUP/"

docker compose stop

for v in config proxus-db-volume clickhouse_data nats proxus_modules; do
  docker run --rm -v ${P}_$v:/data:ro -v "$BACKUP":/backup alpine \
    tar czf /backup/$v.tar.gz -C /data .
done

docker compose start

Copy the folder to your backup location and keep several generations.

Back up the configuration database while running

To keep the configuration safe between full backups without stopping anything, dump the configuration database and copy the config volume. Run it daily, or before a large change:

BACKUP=/backup/proxus/$(date +%F-%H%M)
mkdir -p "$BACKUP"
docker exec postgresql pg_dump -U proxus -p 5442 -d proxus -Fc > "$BACKUP/proxus-db.dump"
docker run --rm -v ${P}_config:/data:ro -v "$BACKUP":/backup alpine \
  tar czf /backup/config.tar.gz -C /data .

This does not include stored values. Use the full backup for those.

If you changed the database user, password or name in your compose file, use your values instead of proxus.

Restore on the same machine

Stop the stack, replace the contents of each volume with the backup (here from a full backup in $BACKUP), and start the stack again:

docker compose stop

for v in config proxus-db-volume clickhouse_data nats proxus_modules; do
  docker run --rm -v ${P}_$v:/data -v "$BACKUP":/backup alpine \
    sh -c "find /data -mindepth 1 -delete && tar xzf /backup/$v.tar.gz -C /data"
done

docker compose start

Then sign in and check devices, trends and users.

To restore only the configuration database from a pg_dump file, stop the hub and the gateway, restore, and start them again:

docker compose stop proxus-ui proxus-server
docker exec -i postgresql pg_restore -U proxus -p 5442 -d proxus --clean --if-exists < "$BACKUP/proxus-db.dump"
docker compose start proxus-ui proxus-server

Restore on a new machine

1. Install Docker and copy the backed-up compose files and .env into a new folder, for example /opt/proxus-platform. For an installer backup, copy the whole backup folder to the new machine and take them from its files/ folder.
2. Create the containers and volumes without starting them: docker compose create in that folder.
3. Fill the empty volumes with the for loop above (without the stop), then start with docker compose start. For an installer backup, the archives are named after the full volume names (<stack>_<volume>.tar.gz).
4. If the new machine has another address, change the address the edge gateways use to reach the hub (port 7422) in your DNS, or install the gateways again. The hub's certificates cover the machine's names and addresses: add the address the gateways and users use to [Service] PublicHostNames, restart, and renew the hub's HTTPS certificate in Security > Certificate Store if browsers report a name mismatch.
5. Sign in. If the license is refused because the License ID changed, ask for a new key. See License.

Kubernetes

On Kubernetes, back up the persistent volumes of the hub and of each gateway (their /app/config) with your cluster's volume backup, and use the backup features of the database operators (CloudNativePG for PostgreSQL, the ClickHouse operator) for the databases. The same rule applies: restore the hub's config volume (with the Certificate Store key) and the configuration database from the same point in time.

Test the restore

A backup you have never restored is a hope, not a backup. Restore to a test machine from time to time, sign in and check that devices, trends and users are there.

What's next

• Upgrade
• Security