Back Up On-Premises

The only thing to which Pro Custodibus writes is its database; so to back up Pro Custodibus, you only need to back up its database.

However, if you’re not using a configuration-management system with your Pro Custodibus servers, you may also want to back up the following:

  • environment variable settings used for the API

  • TLS certificates and keys you’ve generated

  • Let’s Encrypt and Certbot settings, if using Certbot for your TLS certs

  • web server configuration used for the app UI (and API if reverse-proxied)

  • Pro Custodibus EE license keys

ALEK

The only configuration settings you need to keep in sync with your database are the ALEK (Application-Level Encryption Key) settings. ALEK settings are configured via API server’s environment variables prefixed with DB_ALEK_*.

In a production configuration, you’d ideally pull the ALEK secret material from your key-management system. In that case, you’d just need to make sure you keep track of the ALEK source (either via configuration management, or via some other form of documentation).

If, however, you are simply storing the ALEK secret material on the local system (which is the default), make sure you back it up securely — if you lose access to it, you will not be able to decrypt previously stored WireGuard keys (or other secrets stored in the database).

Docker

If you installed Pro Custodibus with the generate-docker-compose.sh script, you can back up the database by navigating to the directory containing the docker-compose.yml file, and running the following command (when the db container is running):

$ cd /srv/containers/procustodibus
$ sudo docker-compose exec -T db pg_dump -U postgres -F tar procustodibus_db |
    gzip > procustodibus_db.tar.gz

You can then tar up the full directory hierarchy and copy it to some other machine:

$ cd $HOME
$ tar cf procustodibus-backup.tar -C /srv/containers procustodibus
$ scp procustodibus-backup.tar somewhere-else.example.com:.

And extract that tar on the other machine. Then start up just the db:

$ tar xf procustodibus-backup.tar
$ cd procustodibus
$ sudo docker-compose up db
Creating network "procustodibus_default" with the default driver
Creating volume "procustodibus_db" with default driver
Pulling db (postgres:alpine)...

...

db_1   | 2023-08-07 01:46:59.261 UTC [52] LOG:  database system was shut down at 2023-08-07 01:46:59 UTC
db_1   | 2023-08-07 01:46:59.267 UTC [1] LOG:  database system is ready to accept connections

Once the db container has started up, you can restore the database back-up by running the following command in another terminal:

$ cd procustodibus
$ gunzip < procustodibus_db.tar.gz |
    sudo docker-compose exec -T db pg_restore -U postgres \
    -d procustodibus_db --clean --if-exists

Once that command finishes, you can start up all the containers:

$ sudo docker-compose down
$ sudo docker-compose up
Pulling api (procustodibus/api-ee:latest)...

...

api_1  | 01:47:08.094 [info] Running ApiWeb.Endpoint with cowboy 2.10.0 at :::4000 (http)
api_1  | 01:47:08.102 [info] Access ApiWeb.Endpoint at https://custos.internal.example.net

The Pro Custodibus instance restored on the new machine now has the same data and configuration as the old, backed-up version.

Database

If you installed the database natively (instead of via Docker), you can back up the Pro Custodibus database just like you would back up a standard PostgreSQL database.

A flexible way to back up an individual database is with the pg_dump utility, using the following command (compressing the back-up with gzip):

$ sudo -iu postgres pg_dump -F tar procustodibus_db |
    gzip > procustodibus_db.tar.gz

A database backed-up this way can be restored with the following pg_restore command (if the database instance already exists):

$ gunzip < procustodibus_db.tar.gz |
    sudo -iu postgres pg_restore -d procustodibus_db --clean --if-exists

If the database instance doesn’t exist yet, create it first with the API’s init.sql script, as described in the Init SQL section of the install docs.