Guide

Upgrading

Upgrade Heimnull to a new release, what happens during the upgrade, and how to pin a version.

Heimnull doesn’t upgrade itself. The System page tells you when a new release is out, with its release notes and the commands below. It checks registry.heimnull.com every 6 hours.

Upgrade

cd /opt/heimnull
sudo curl -fsS -o docker-compose.yml https://registry.heimnull.com/docker-compose.yml
sudo docker compose pull
sudo docker compose up -d --wait

Always fetch docker-compose.yml first. docker compose pull updates the images only, while some of what a release needs (container settings, ClickHouse’s configuration) lives in that file. Your own settings are in .env, which the download doesn’t touch, and so is a docker-compose.override.yml. If the compose file is older than the image needs, the System page says so.

Before a major release (the first number changes, for example v3 to v4), read its release notes: it needs more than these commands, and the notes say what.

What happens

Migrations for PostgreSQL and ClickHouse run when the heimnull container starts, before anything else in it. They only move forward.
Flows are lost for 2 to 5 seconds while the container restarts (UDP isn’t buffered).
BGP sessions drop and come back. Routers withdraw Heimnull’s routes and receive them again once the sessions are up; active mitigations stay in force in Heimnull and are announced again.
ClickHouse restarts if its configuration in the compose file changed: a few seconds, while ingest buffers.
Built-in classification rules update when the release brings newer ones. Rules you’ve edited or added are kept.

Check afterward

Open System: every component ok, the exporters receiving, and no insert errors. The version shows there too, or from the command line:

sudo docker compose exec heimnull heimnull version

If the System page says ClickHouse runs an outdated configuration, recreate it once:

sudo docker compose up -d --force-recreate clickhouse

Pin a version

HN_VERSION in .env chooses which release docker compose pull fetches:

`HN_VERSION`	Follows
`latest` (the default)	Every release
`v3`	Every release before 4.0: features and fixes, no major upgrades
`v3.1`	Patches of 3.1 only
`v3.1.1`	That release only

Releases are numbered vMAJOR.MINOR.PATCH: MAJOR when an upgrade needs more than pulling the new image, MINOR for features, PATCH for fixes.

Going back

Migrations don’t run backward, so an older image may not start on a database a newer one has migrated. To go back to an earlier release, restore the backups you took before the upgrade (see Backups and restore) and set HN_VERSION to that release. Take a PostgreSQL backup before a major upgrade.