> ## Documentation Index
> Fetch the complete documentation index at: https://docs.scanoss.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Upgrading and backing up

> Upgrade a self-hosted Earnie to a new release, back up its database, data directory, and configuration, and roll back if an upgrade goes wrong.

This page applies when you host Earnie yourself. It assumes you installed Earnie as described in [Installing Earnie](/en/latest/earnie/self-hosting/installation). 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.

1. Stop the services:

   ```bash theme={null}
   docker compose stop
   ```

2. Copy the data directory and `tenant.env` to your backup location. For example:

   ```bash theme={null}
   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.

3. Start Earnie again:

   ```bash theme={null}
   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:

```bash theme={null}
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:

```bash theme={null}
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:

```bash theme={null}
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.

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

## Upgrade

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

1. **Back up.** Take a full backup first. Database migrations only move forward, and Earnie has no downgrade. See [Back up](#back-up).

2. **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.

3. **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.

4. **Set the version.** In `tenant.env`, set the new version:

   ```text theme={null}
   EARNIE_VERSION=vX.Y.Z
   ```

5. **Run the installer.**

   With access to the container registry:

   ```bash theme={null}
   ./install.sh
   ```

   From the offline archive, join the parts, check them, and pass the archive. See [From the offline image archive](/en/latest/earnie/self-hosting/installation#from-the-offline-image-archive).

   ```bash theme={null}
   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

```bash theme={null}
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.

1. Stop the services:

   ```bash theme={null}
   docker compose down
   ```

2. 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 `/`:

   ```bash theme={null}
   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
   ```

3. 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:

   ```bash theme={null}
   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.

4. Use the bundle of the previous release. Check that `EARNIE_VERSION` in the restored `tenant.env` names that release.

5. Run the installer. If the server can't reach the container registry, pass the previous release's archive:

   ```bash theme={null}
   ./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:

1. Prepare the new server as in [Prepare the host](/en/latest/earnie/self-hosting/installation#prepare-the-host).
2. Put the bundle for the version you backed up on the new server.
3. Restore `tenant.env` and the data directory. Restore the database as in [Roll back](#roll-back).
4. 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.
5. Run the installer, with the offline image archive if the server can't reach the container registry.

## What's next

* [Installing Earnie](/en/latest/earnie/self-hosting/installation) covers configuration and TLS.
* [Self-hosting requirements](/en/latest/earnie/self-hosting-requirements) lists the disk space your backups need to cover.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.