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

# Upgrade to a new release

> Move a self-hosted Notifuse to a new release with Docker Compose, check the result and roll back if needed.

An upgrade replaces the Notifuse image and restarts it. Notifuse updates its databases by itself when it starts on the new release.

## Read the changelog first

Open the [changelog](https://www.notifuse.com/docs/changelog.md) and read every release between your version and the new one. Some releases have a **Before you upgrade** note with a change to make in the same step as the upgrade, such as a new `SECRET_KEY` value for 42.0 or `WEBHOOK_DELIVERY_ALLOW_PRIVATE_HOSTS` for webhooks on your own network.

When **Check for updates** is on, the root user and workspace owners see a card on the workspace list when a new release is out. Its **See what's new** button opens every release since yours, each with its **Before you upgrade:** notes and a **Full changelog** link.

## Back up

Back up every database and keep `SECRET_KEY` with the dumps, as [Backups](https://www.notifuse.com/docs/self-hosting/backups.md) shows. A rollback to an earlier major version needs this backup (see [Rolling back](#rolling-back)).

Set `DB_EXPECT_EXISTING=true` in `.env` if it is not already there. If the upgrade ever left Notifuse facing an empty database, it would stop instead of starting a new installation.

## Upgrade with Docker Compose

`compose.yaml` takes the release from `NOTIFUSE_VERSION`:

```yaml compose.yaml
image: notifuse/notifuse:${NOTIFUSE_VERSION:-v44.0}
```

The default after `:-` is the release the file was published with. Choose one of the two ways to change it, from the directory that holds `compose.yaml`.

**Pin the version in .env**

Set the new release in `.env`, then pull and restart:

```bash
# In .env: NOTIFUSE_VERSION=v44.0
docker compose pull
docker compose up -d
```

**Download the new compose.yaml**

Replace your `compose.yaml` with the latest one, then pull and restart. Your `.env` stays as it is. Copy any change you made to `compose.yaml` into the new file.

```bash
curl -fsSL https://raw.githubusercontent.com/Notifuse/notifuse/main/compose.yaml -o compose.yaml
docker compose pull
docker compose up -d
```

If `.env` sets `NOTIFUSE_VERSION`, that value wins over the default in the file: update it too.

`docker compose pull` downloads the new image while the old one keeps running. `docker compose up -d` then replaces the container. Notifuse gets up to 70 seconds to stop: the automation step under way and the emails being sent finish first.

To check which release Compose will run before you restart, look at the resolved image:

```bash
docker compose config | grep 'image: notifuse'
```

> [!NOTE]
>
> Up to 43.0, `compose.yaml` builds Notifuse from the clone of the repository it sits in. In such a clone, check out the new release (`git fetch --tags && git checkout v44.0`), then run `docker compose up -d`. From 44.0, the file runs the published image unless you pass `--build`.

## What happens at startup

When the new release starts, Notifuse runs its database migrations before it serves any request:

1. It checks the PostgreSQL version. Since 44.0, it refuses to start on PostgreSQL older than 17 and says which version it found.
2. It compares the major version recorded in the system database (`43` for 43.0) with its own.
3. It applies each migration in between to the system database, then to every workspace database.
4. It records the new version. Some migrations then make Notifuse exit once, and Docker starts it again (`restart: unless-stopped`).

With several instances on the same database, one applies the migrations and the others wait for it (42.2 and later). Follow the progress in the log:

```bash
docker compose logs -f api
```

The log ends this step with `Migration process completed successfully`, or `Database is up to date, no migrations needed` when the major version did not change. If a migration fails, Notifuse does not start, and the log names it: `migration failed for version …`.

## Check the version

Sign in and open the workspace list. Its footer shows the running version, such as **Notifuse v44.0**. The account menu shows it too.

From the command line, the console's configuration file carries it:

```bash
curl -s https://emails.yourcompany.com/config.js | grep VERSION
```

Then check that `https://emails.yourcompany.com/healthz` answers `{"status":"ok"}`, and open a workspace to check your data.

## Rolling back

Notifuse records only the major version in the database, and it has no down migrations.

Within the same major version (44.1 back to 44.0, for example), set the previous release in `NOTIFUSE_VERSION` and run `docker compose up -d`. Notifuse starts on the same database.

Across major versions, the older release refuses to start on a database the newer one migrated. The log says `database is at version 44, this build is version 43 - refusing to start`. To go back:

1. Stop the stack with `docker compose down`.
2. Set the previous release in `NOTIFUSE_VERSION`, or put back its `compose.yaml`.
3. Restore the backup you took before the upgrade into an empty database, as [Restoring](https://www.notifuse.com/docs/self-hosting/backups.md#restoring) shows, with the `SECRET_KEY` the backup was taken with.

Anything written since the backup is lost.

When the upgrade was the one to 44.0, which also moves PostgreSQL to 18, use the copy that `compose.yaml` keeps instead: [Rolling back](https://www.notifuse.com/docs/self-hosting/upgrading-postgresql.md#rolling-back) puts back the PostgreSQL 17 data as it was before the upgrade, with the previous release's `compose.yaml`.

## Upgrading PostgreSQL

Version 44.0 moves `compose.yaml` from PostgreSQL 17 to 18, and the first `docker compose up -d` on it upgrades the database too. [Upgrading PostgreSQL](https://www.notifuse.com/docs/self-hosting/upgrading-postgresql.md) explains what happens, how much disk space it needs, how to check it and how to roll it back.
