Upgrading and backing up

This page applies when you host Earnie yourself. It assumes you installed Earnie as described in Installing Earnie. Run every command from the bundle directory. The examples write backups into the current directory. Move them off the server, or write them straight to your backup location. A backup holds tenant.env and your data, so keep it as safe as tenant.env itself.

Back up

Back up three things:

What	Why
The PostgreSQL database	It holds your projects, findings, decisions, policies, approvals, and audit trail.
The data directory	`EARNIE_DATA_DIR`, `/var/lib/earnie` by default. It holds scan archives, scan results, caches, uploaded AI models, and certificates. If you run PostgreSQL as a container, its files are in `<EARNIE_DATA_DIR>/postgres`.
`tenant.env`	It holds your configuration and your secrets.

Keep tenant.env in a safe place with the same care as a password. Earnie encrypts the GitHub and GitLab credentials and the single sign-on client secret that it stores in the database. The encryption keys are EARNIE_INTEGRATIONS_KEK_HEX and EARNIE_SSO_KEK_HEX in tenant.env. A restored database is only useful with the same two keys. Without them, Earnie can’t read those stored credentials, and you would have to connect your Git servers and single sign-on again.

Option 1: stop Earnie, then copy everything

This gives a backup in which the database and the data directory agree with each other. Earnie is unavailable while it runs.

Stop the services:
docker compose stop
Copy the data directory and tenant.env to your backup location. For example:
sudo tar -czf earnie-backup-$(date +%F).tar.gz /var/lib/earnie tenant.env
If you use your own PostgreSQL server, also take a backup of the database with your usual tool, for example pg_dump, while Earnie is stopped.
Start Earnie again:
docker compose start

Option 2: back up while Earnie runs

Use pg_dump for the database. Copy the data directory and tenant.env separately. For the bundled PostgreSQL:

docker compose exec -T postgres pg_dump -U earnie -d earnie -Fc > earnie-db-$(date +%F).dump

Use the values of ONPREM_PG_USER and ONPREM_PG_DB if you changed them from earnie. For your own PostgreSQL server:

pg_dump -h db.example.com -U earnie -d earnie -Fc > earnie-db-$(date +%F).dump

With the bundled PostgreSQL, don’t copy <EARNIE_DATA_DIR>/postgres while Earnie runs, because the copy can be unusable. Exclude it and rely on the pg_dump file:

sudo tar --exclude=/var/lib/earnie/postgres -czf earnie-data-$(date +%F).tar.gz /var/lib/earnie tenant.env

A backup taken while scans run can also hold a database and scan archives from slightly different moments. Only Option 1 gives you a backup that agrees with itself.

Test your backup. Restore it on a spare server at least once, so you know the steps work before you need them.

Upgrade

Each release has a version number, vX.Y.Z. To upgrade:

Back up. Take a full backup first. Database migrations only move forward, and Earnie has no downgrade. See Back up.
Get the new release. Ask your SCANOSS contact for the new installation bundle. If your server can’t reach the container registry, ask for the new offline image archive too.
Use the new bundle. Replace the files in your bundle directory with the files from the new release, but keep your tenant.env. Compare the new tenant.env.example with your tenant.env and add any new setting you want to change.
Set the version. In tenant.env, set the new version:
EARNIE_VERSION=vX.Y.Z

Run the installer. With access to the container registry:

./install.sh

From the offline archive, join the parts, check them, and pass the archive. See From the offline image archive.

cat earnie-onprem-images-vX.Y.Z.tar.gz.part-* > earnie-onprem-images-vX.Y.Z.tar.gz
sha256sum -c earnie-onprem-images-vX.Y.Z.sha256
./install.sh earnie-onprem-images-vX.Y.Z.tar.gz

The installer loads or pulls the new images and restarts Earnie. Database migrations run automatically when Earnie starts, before the API accepts requests. Earnie is unavailable for a short time while it restarts. Schedule the upgrade for a quiet period.

Check the upgrade

docker compose ps
curl -fsS https://earnie.example.com/healthz

Every service must be healthy, and /healthz must answer with a success status. Then sign in and open a recent project to confirm that your data is there.

Roll back

You can’t downgrade the database. To go back to the previous version, restore the backup you took before the upgrade, then install the previous version.

Stop the services:
docker compose down

Restore your data. Empty the data directory, then extract the backup into it, so no file from after the backup stays behind. tar stored the paths without the leading /, so extract from /:

sudo find /var/lib/earnie -mindepth 1 -delete
sudo tar -xzf earnie-backup-YYYY-MM-DD.tar.gz -C / var/lib/earnie
sudo tar -xzf earnie-backup-YYYY-MM-DD.tar.gz tenant.env

Restore the database. For the bundled PostgreSQL, you restore the data directory in the previous step, which includes <EARNIE_DATA_DIR>/postgres. If you took a pg_dump backup instead, remove <EARNIE_DATA_DIR>/postgres, start only the database, and restore into it:
docker compose up -d --wait postgres docker compose exec -T postgres pg_restore -U earnie -d earnie --clean --if-exists < earnie-db-YYYY-MM-DD.dump
For your own PostgreSQL server, restore into an empty database with pg_restore or your usual tool.
Use the bundle of the previous release. Check that EARNIE_VERSION in the restored tenant.env names that release.
Run the installer. If the server can’t reach the container registry, pass the previous release’s archive:
./install.sh earnie-onprem-images-vX.Y.Z.tar.gz
With registry access, ./install.sh alone is enough.

Anything that happened after the backup, such as scans and decisions, is lost. That is why you back up before every upgrade.

Restore on a new server

To move Earnie to a new server, or to recover after losing one:

Prepare the new server as in Prepare the host.
Put the bundle for the version you backed up on the new server.
Restore tenant.env and the data directory. Restore the database as in Roll back.
Make sure the DNS name in EARNIE_HOST points at the new server. If you use EARNIE_TLS=custom, the certificate files are in the data directory unless you set EARNIE_TLS_DIR elsewhere.
Run the installer, with the offline image archive if the server can’t reach the container registry.

What’s next

Installing Earnie covers configuration and TLS.
Self-hosting requirements lists the disk space your backups need to cover.

Get started

Development

Pull requests & CI

Governance

Evidence & audit

Administration

Migrating

API reference

Back up

Option 1: stop Earnie, then copy everything

Option 2: back up while Earnie runs

Upgrade

Check the upgrade

Roll back

Restore on a new server

What’s next

​Back up

​Option 1: stop Earnie, then copy everything

​Option 2: back up while Earnie runs

​Upgrade

​Check the upgrade

​Roll back

​Restore on a new server

​What’s next

Back up

Option 1: stop Earnie, then copy everything

Option 2: back up while Earnie runs

Upgrade

Check the upgrade

Roll back

Restore on a new server

What’s next