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 under the project name proxus (see Docker). With another project name, the volume names start with that name instead of proxus_.
• A backup location outside the hub's machine, with room for the telemetry database.
• Shell access to the host with permission to run docker.

What to back up

All data of the stack is in five Docker volumes:

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

Check the exact volume names on your host:

docker volume ls --filter name=proxus_

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.

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

docker compose -p proxus stop

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

docker compose -p proxus 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 proxus_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 -p proxus stop

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

docker compose -p proxus 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 -p proxus 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 -p proxus start proxus-ui proxus-server

Restore on a new machine

1. Install Docker and copy the backed-up docker-compose.yml to /opt/proxus.
2. Create the containers and volumes without starting them: docker compose -p proxus create in /opt/proxus.
3. Fill the empty volumes with the for loop above (without the stop), then start with docker compose -p proxus start.
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