Updating and backing up the application

This page is for the technical administrator of a MyZapp instance installed on their own servers (see "Installing the application on your own servers"). On an instance hosted by the publisher, backups and updates are handled by the host.

What to back up

An instance keeps its state in two places only:

the PostgreSQL database: all data and all settings;
the application data volume: its local configuration (with the encrypted secrets), the logs and the uploaded files.

The containers themselves hold nothing worth keeping: they are recreated identically from the image. Also back up, separately, the server files: .env, the secrets/ folder and, if used, the views-override/ folder. Keep the security keys exported at installation with the same care.

Backing up

The backup.sh script, supplied with the application, produces in one command:

a database dump, db_ followed by the date, in the pg_restore format (it is not a readable SQL file);
an archive of the data volume, appdata_ followed by the date.

Run it from the orchestration file's folder: ./backup.sh .env ./backups. It keeps the last 10 backups of each type; BACKUP_RETENTION_COUNT in .env changes that number.

Optionally, set in .env:

encryption of the backups (BACKUP_ENCRYPT=true, with a passphrase or a GPG public key);
an off-site copy to one or more destinations: FTP, S3-compatible storage, Windows share, already mounted share or server reachable over SSH (BACKUP_OFFSITE_TYPES). By default, a failed off-site copy is only a warning; BACKUP_OFFSITE_REQUIRED=true makes it an error.

The application does not run this script by itself: schedule it on the server, for example every night with cron. The full list of settings is at the top of the script.

Restoring

The same procedure applies after an incident and to rebuild an instance on a new server.

Start only the database and stop the application, so that no migration is applied during the restore.
If the backups are encrypted, decrypt them first.
Restore the database with pg_restore and the --clean --if-exists options, in the webbase-postgres container.
Restore the data volume from its archive: its current content is replaced.
Restart everything, then check that /health answers Healthy.

A database restored on another installation (for example a production copied to a test instance) can show an identity conflict on the Licenses page: then choose between a new instance and a moved instance (see "Managing the instance licenses").

Updating the version

Back up: an update has no automatic rollback.
Load the new image (docker load for a file) or set its version in WEBBASE_IMAGE, in .env.
With a registry, pull the new image: docker compose -f docker-compose.onprem-client.yml pull.
Restart: docker compose -f docker-compose.onprem-client.yml up -d. The data is kept.

At startup, each module applies its own database migrations. Then check:

the Instance status screen, which shows the new version, and the Support diagnostics screen, which must show Up to date for each module (see "Monitoring the instance");
the Changelog, which lists the changes of the installed version;
the documentation shipped with the version, to import again (see "Update the documentation").

Read the version notes before updating: some require an extra step, for example copying a new orchestration file.

A customized view must be in views-override/: it is the only location kept from one version to the next.

If the update fails

If a migration fails, the application does not start and the database may be left in an intermediate state. To go back to the previous version:

restore the backup made just before the update (see above);
put the old version back in WEBBASE_IMAGE;
restart.

Putting the old image back alone is not enough when the new version has already migrated the database: applied migrations are not undone. The old image remains available on the server as long as it has not been deleted.

Changing the PostgreSQL version

A new major version of PostgreSQL does not read the data files of the previous one: changing only the database image does not work. It takes a full dump, a new database in the new version, then restoring the dump. Keep an image that includes the pgvector extension, used by the knowledge base: without it, the restore fails.