Skip to content

Self-hosting

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 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 shows. A rollback to an earlier major version needs this backup (see 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:

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:

# 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.

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:

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:

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:

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 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 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 explains what happens, how much disk space it needs, how to check it and how to roll it back.