# Backup and restore

> Proxus has no built-in backup. What to back up in the Docker stack, how to make a consistent copy of its volumes, and how to restore it.

Source: https://proxus.io/docs/operate/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.

> **Warning:**
Proxus does not make backups by itself. There is no backup button and no scheduled backup in the product. Set up the
backup described here, or your company's own volume or database backup, and test a restore.

## Before you start

- The hub runs with the shipped `docker-compose.yml` under the project name `proxus` (see [Docker](https://proxus.io/docs/operate/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:

| Volume | Contains | If you lose it |
| --- | --- | --- |
| `proxus_config` | `Proxus-config.toml`, the message broker's credentials and TLS files (`nats/`), the keys that protect sign-ins (`keys/`), the Certificate Store key (`keys/STORE/certificate-store.key`), OPC UA certificates of the gateway, log files | Every remote edge gateway must be installed again, every user is signed out, the configuration is back to defaults, and the certificates in the database cannot be read. |
| `proxus_proxus-db-volume` | The configuration database (PostgreSQL): devices, profiles, tags, rules, pipelines, users, roles, certificates, license, audit trail | Everything you set up in the hub. |
| `proxus_clickhouse_data` | The telemetry database (ClickHouse): every stored value and the system logs | All history: trends, reports, logs. |
| `proxus_nats` | Messages waiting in the broker, and broker account data | Messages not yet delivered. |
| `proxus_proxus_modules` | Add-on modules installed in the hub | Add-ons must be installed again. |

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

> **Danger:**
The `config` volume and the configuration database belong together. Back them up at the same time and restore them
together. The broker credentials in `config` are what every edge gateway trusts: without them, all remote gateways
must be enrolled again. The Certificate Store key in `config` decrypts the private keys stored in the database:
without it, every certificate (the platform CA, the hub's HTTPS and NATS certificates, the gateways' certificates,
outbound target certificates) has to be created or uploaded again.

Check the exact volume names on your host:

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

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

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

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

```bash
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](https://proxus.io/docs/administer/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](https://proxus.io/docs/operate/upgrade)
- [Security](https://proxus.io/docs/operate/security)