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

# Backups

> Back up and restore a self-hosted Notifuse: every database, and the secret key.

Notifuse keeps its data in several PostgreSQL databases: `notifuse_system` (users, workspaces, settings) and one `notifuse_ws_<workspace id>` database per workspace (contacts, lists, templates, broadcasts, message history, web analytics). A backup needs all of them, and the `SECRET_KEY` the installation runs with: the stored provider credentials are encrypted with it, and a restore without it leaves them unreadable.

> [!WARNING]
>
> A backup of `notifuse_system` alone restores an installation that looks healthy, with its users and workspaces, and holds no contact, broadcast or message. Back up every `notifuse_ws_…` database with it.

## Backing up

With the provided `compose.yaml`, from the directory that holds it (replace `postgres` with your `DB_USER`, and `notifuse` with your `DB_PREFIX`, if you changed them):

```bash
for db in $(docker compose exec -T postgres psql -U postgres -d postgres -Atc \
    "SELECT datname FROM pg_database WHERE datname = 'notifuse_system' OR datname LIKE 'notifuse\_ws\_%'"); do
  docker compose exec -T postgres pg_dump -U postgres -Fc "$db" > "$db.dump"
done
```

Each database lands in its own `.dump` file. Copy them, with `SECRET_KEY`, somewhere other than the server. The dumps are consistent per database; for a backup consistent across them, stop Notifuse first (`docker compose stop api`) and start it again after (`docker compose start api`).

`pg_dumpall` is not a good fit: its restore drops and recreates the role it connects as, which fails, and it writes the role's password hash into the backup.

Copying the files of the database volume while PostgreSQL runs does not give a restorable backup.

## Restoring

Into an installation whose database is empty (a new server, or after `docker compose down -v`), with the same `SECRET_KEY` in `.env` and `DB_EXPECT_EXISTING` unset:

```bash
docker compose up -d postgres
for f in notifuse_*.dump; do
  db=${f%.dump}
  docker compose exec -T postgres createdb -U postgres "$db"
  docker compose exec -T postgres pg_restore -U postgres -d "$db" --exit-on-error < "$f"
done
docker compose up -d
```

Restore before Notifuse starts on the empty database: a first start creates a new, empty `notifuse_system`. Once the restore works, set `DB_EXPECT_EXISTING=true` in `.env`, so that Notifuse refuses to start the day it finds an empty database instead of your data.
