Backups and restore

What to back up

What	How	Holds
.env	Copy it somewhere safe, once and after each change	Every secret, including HN_SECRET_KEY
PostgreSQL	pg_dump, daily (below)	Users, configuration, attacks, mitigations, the audit log, notification history, the license
Configuration bundle	Configure → Export / import	Your configuration in a portable form, for another server
ClickHouse	Usually not backed up	Flow records and rollups: analytics data that ages out anyway

.env and the database belong together

HN_SECRET_KEY in .env encrypts the SNMP communities, BGP passwords and notification credentials stored in PostgreSQL. A database backup restored with a different key loses them all: you’d have to enter them again. Keep .env with your backups, and keep both private.

Back up PostgreSQL

cd /opt/heimnull
sudo docker compose exec -T postgres sh -c 'pg_dump -U "$POSTGRES_USER" -Fc "$POSTGRES_DB"' > ~/heimnull-$(date +%F).pgdump

This takes a consistent copy while Heimnull runs and writes it to your home directory. The dump holds password hashes and the encrypted secrets, so store it as carefully as .env.

To take one every night, create /etc/cron.d/heimnull-backup (cron runs it as root, so no sudo), and keep 14 days:

30 3 * * * root cd /opt/heimnull && mkdir -p /var/backups/heimnull && docker compose exec -T postgres sh -c 'pg_dump -U "$POSTGRES_USER" -Fc "$POSTGRES_DB"' > /var/backups/heimnull/heimnull-$(date +\%F).pgdump && find /var/backups/heimnull -name '*.pgdump' -mtime +14 -delete

Then copy /var/backups/heimnull off the server with your usual backup tool.

Restore onto the same or a new server

1. Install as in the install guide, but use your saved .env instead of running env-template: copy it to /opt/heimnull/.env (sudo chmod 600 it).

2. Start Heimnull once, so the databases exist, then stop the application:

   cd /opt/heimnull
   sudo docker compose up -d --wait
   sudo docker compose stop heimnull

3. Restore the dump:

   sudo docker compose exec -T postgres sh -c 'pg_restore -U "$POSTGRES_USER" -d "$POSTGRES_DB" --clean --if-exists' < ~/heimnull-2026-10-19.pgdump

4. Start everything again:

   sudo docker compose up -d --wait

Sign in with your usual account. Restore with the same Heimnull release the dump came from, or a newer one: migrations bring an older database forward, never back.

Licenses on a new server

The restored database keeps the installation’s ID, so a restored server checks in as the same installation. If the old server keeps running too, both use the license’s seats. See Licensing.

The configuration bundle

Configure → Export / import downloads your configuration as one JSON file: networks, hostgroups, exporters, interfaces, classification rules, host names, saved searches, settings, BGP and notification routing.

• Without secrets (the default), it’s safe to keep in version control or send to someone helping you.
• With secrets, it also holds the users, API tokens (as hashes) and every stored secret in plain text. Export it that way only for a file you’ll keep somewhere safe.

It imports into any Heimnull server, including one with a different HN_SECRET_KEY. Use it to move your setup to a fresh server when you don’t need the attack history, or to copy a configuration between servers. From a script, an admin API token can fetch it from GET /api/config/export (see API).

Flow history (optional)

Flow records age out (30 days of raw flows by default), so most servers don’t back them up. To keep them anyway, stop the stack and copy the heimnull_hn-ch volume, or use ClickHouse’s own BACKUP command with a backup disk configured.