Requirements

Software

The operating system and Docker setup Heimnull runs on, and why it needs Docker Engine rather than Docker Desktop.

Operating system

Any current 64-bit Linux that runs Docker Engine: Debian 12 or later, Ubuntu 22.04 LTS or later, RHEL 9 or later and its rebuilds (Rocky Linux, AlmaLinux), or Fedora. Heimnull needs nothing from the operating system beyond Docker Engine. The guides are written for Debian 13; Ubuntu 22.04 or later works the same way, and on the others only the Docker install differs.

Keep the server’s clock synchronized (NTP, systemd-timesyncd or chrony). Heimnull corrects routers whose clocks drift, but it measures them against its own.

Docker Engine

Heimnull needs Docker Engine with the compose plugin, version 2.23 or later. The compose file carries ClickHouse’s configuration inline, which older Compose releases can’t read.

sudo docker compose version

Docker Desktop doesn’t work, on Linux or anywhere else. Heimnull uses the host’s network directly so it can see your routers’ real source addresses and talk BGP on port 179. Docker Desktop runs containers in its own virtual machine, so “the host’s network” would be that VM’s, and nothing from your routers would reach Heimnull. The install’s env-template step warns when it finds Docker Desktop.

Install Docker Engine from Docker’s own packages (Install Docker Engine). The install guide shows how on Debian.

What runs

Container	Image	Network
`heimnull`	`registry.heimnull.com/heimnull`	The host’s network
`postgres`	`postgres` (Docker Hub)	Its port on 127.0.0.1 only
`clickhouse`	`clickhouse/clickhouse-server` (Docker Hub)	Its ports on 127.0.0.1 only

The heimnull container runs the flow collector, detection and mitigation, the BGP speaker (GoBGP), the API and the web server (Caddy), under a supervisor that restarts any process that exits. It runs with every Linux capability dropped except the few it needs: binding the web port and port 179, raising its UDP receive buffers, and switching to an unprivileged user for the API and web server.

A server needs only two files, both in /opt/heimnull: docker-compose.yml, downloaded from registry.heimnull.com, and .env, with your settings and secrets. Everything else lives in Docker volumes:

Volume	Holds
`heimnull_hn-pg`	PostgreSQL: users, configuration, attacks, mitigations, the audit log
`heimnull_hn-ch`	ClickHouse: flow records, rollups, attack samples, SNMP counters
`heimnull_hn-datasets`	Downloaded datasets (ASNs, geolocation, provider ranges)

A browser

The web interface works in current versions of Firefox, Chrome, Edge and Safari.