Install Heimnull

This guide starts from a fresh Debian 13 server; Ubuntu 22.04 or later works the same way. It takes about ten minutes. Check the requirements first, especially AVX2 on amd64 and, on Proxmox, the VM’s CPU type.

The commands run as root through sudo. If you’re logged in as root, leave out sudo.

1. Prepare the host

Update the system and install curl:

sudo apt-get update && sudo apt-get -y upgrade
sudo apt-get -y install curl ca-certificates

On amd64, check that the CPU has AVX2:

grep -o -m1 avx2 /proc/cpuinfo

If this prints nothing, stop here: ClickHouse won’t start. On Proxmox, set the VM’s CPU type to host or x86-64-v3, then stop and start the VM. See Server.

2. Install Docker Engine

Install Docker Engine from Docker’s packages. Docker’s convenience script does it in one step on Debian and Ubuntu:

curl -fsSL https://get.docker.com -o get-docker.sh
sudo sh get-docker.sh

Or follow Docker’s step-by-step instructions for its apt repository. Don’t install Docker Desktop: Heimnull needs the host’s network, which Docker Desktop doesn’t give containers.

Check that the compose plugin is there, at version 2.23 or later:

sudo docker compose version

3. Download the compose file and write .env

sudo mkdir -p /opt/heimnull && cd /opt/heimnull
sudo curl -fsS -o docker-compose.yml https://registry.heimnull.com/docker-compose.yml
sudo sh -c 'umask 077; docker run --rm registry.heimnull.com/heimnull:latest env-template > .env'

• The image and the compose file come from Heimnull’s public registry. No login or token is needed.
• env-template writes .env with fresh random passwords and keys, and memory and CPU limits sized for this server.
• Why sh -c: /opt/heimnull belongs to root. In sudo cmd > .env, the redirect runs in your own shell, which can’t write there. Inside sudo sh -c '…', root writes the file, and umask 077 makes it readable by root only.

env-template also checks the machine, and prints a WARNING: line for anything that won’t work or will run short:

• an amd64 CPU without AVX2;
• less than 4 GB of memory (under 7 GB is tight) or fewer than 2 CPUs;
• Docker Desktop instead of Docker Engine.

Fix these before you go on. The warnings go to the terminal, not into .env.

4. Check .env

The defaults suit most servers. Look at these before the first start:

• HN_HTTP_PORT (80): the web port. Change it if something else uses port 80, or if a reverse proxy on this host will take port 80 and 443 (for example 8088; see HTTPS). Don’t use 8080: Heimnull’s internal API already listens on 127.0.0.1:8080.
• Flow ports: NetFlow v9 on UDP 2055, IPFIX on 4739, sFlow on 6343. To change one, add HN_NETFLOW_PORT, HN_IPFIX_PORT or HN_SFLOW_PORT to .env. Every port accepts every format.
• HN_HTTP_TRUSTED_PROXIES: only if a reverse proxy on another machine will sit in front of the web interface.

sudo nano /opt/heimnull/.env

Every variable is described in Environment variables.

Back up .env now

.env holds the database passwords and HN_SECRET_KEY, which encrypts the SNMP communities, BGP passwords and notification credentials stored in the database. If it’s lost, you’ll have to enter all of those again, and a database backup can’t be restored without it. Copy it somewhere safe, and keep it private.

5. Start Heimnull

sudo docker compose up -d --wait

This pulls the images, creates the databases, runs the migrations, and waits until every container reports healthy. The first start takes about a minute. Check the result:

sudo docker compose ps

All three containers (heimnull, postgres, clickhouse) should show healthy. If clickhouse keeps restarting, see ClickHouse won’t start.

6. Open the firewall

Allow the web port from your operators, and the flow ports and BGP from your routers only. Heimnull uses the host’s network, so the host’s own firewall applies to it. With ufw (sudo apt-get install ufw), for example, where your routers are in 192.0.2.0/24 and your operators in 198.51.100.0/24:

sudo ufw allow OpenSSH
sudo ufw allow from 192.0.2.0/24 to any port 2055,4739,6343 proto udp
sudo ufw allow from 192.0.2.0/24 to any port 179 proto tcp
sudo ufw allow from 198.51.100.0/24 to any port 80 proto tcp
sudo ufw enable

Allow SSH before you enable the firewall, or you’ll lock yourself out.

See Network and firewall for every port and the outbound access Heimnull needs.

7. Create the admin account

Open http://<server>/ in a browser. The first visit asks you to create the admin account. There are no default credentials.

Create the admin account quickly!

Until the first admin exists, anyone who can reach the page can create it.

Heimnull is now in its 30-day trial, with every feature and no traffic limit. You don’t need a key yet. See Licensing.

Next

Continue with the first-time setup: your networks, your routers, hostgroups and notifications.