docker

Pre-Alpha. This page describes behavior that may change.

Run Ze in a Docker container for evaluation, lab testing, or lightweight deployments where you don't need interface configuration or kernel-level features (VPP, L2TP, nftables).

For production on bare metal or a dedicated VM, see Appliance.

Two images

Ze builds two container images. They carry the same binary and differ in the base.

Image	Recipe	Target	Base	Size
ze:latest	docker/Dockerfile	Deployment	scratch: no shell, no libc, no package manager	119 MB
netlab/ze:latest	docker/Dockerfile.lab	Labs under netlab and containerlab	alpine:3.21 with tini and iproute2	137 MB

The sizes are docker image ls values measured on 2026-08-14. Use the deployment image everywhere except a lab. The lab image carries a shell and ip because containerlab and netlab drive a node from the outside: they run sh and ip inside the container to assign the addresses the topology declares, and a scratch base has neither. See netlab.

Build the deployment image

make ze-docker-build

This produces ze:<YY.MM.DD> and ze:latest. Override the image name or tag:

make ze-docker-build ZE_DOCKER_IMAGE=myregistry/ze ZE_DOCKER_TAG=v1

Both recipes derive their build tags from feature-gates.txt, the same list make ze-build uses, so the container runs the feature set the shipped binary runs. ZE_TAGS adds tags on top of that list. It does not replace it:

make ze-docker-build ZE_TAGS=maprib

That command builds the default feature set plus maprib.

Build the lab image

make ze-docker-lab-build

This produces netlab/ze:latest. ZE_LAB_IMAGE and ZE_LAB_TAG override the name and the tag. The image runs ze under tini, which forwards SIGHUP and SIGTERM to the daemon. SIGHUP is the config-push contract a lab tool uses. See netlab.

Run

Ze needs a config file. Mount one from the host:

docker run --rm -v ./example.conf:/etc/ze/ze.conf ze:latest start /etc/ze/ze.conf

The deployment image ENTRYPOINT is /ze, so everything after the image name is passed to ze. The config path goes behind the start keyword: a bare ze /etc/ze/ze.conf is rejected with unknown command. The lab image keeps the same grammar behind tini.

Expose the ports you need:

Port	Service
179	BGP
1790	SSH CLI
8080	Web UI / API

docker run -d \
  --name ze \
  -p 179:179 \
  -p 1790:1790 \
  -p 8080:8080 \
  -v ./myconfig.conf:/etc/ze/ze.conf \
  -v ./ze-data:/etc/ze \
  ze:latest start /etc/ze/ze.conf

Initialize credentials

Ze requires SSH credentials for CLI access. Initialize them before starting the daemon:

docker run --rm -v ./ze-data:/etc/ze ze:latest init

This prompts for username and password. For scripting:

echo -e "admin\nsecret" | docker run --rm -i -v ./ze-data:/etc/ze ze:latest init

Compose

A ready-made docker/compose.yaml is included in the repo:

cp docker/compose.yaml .
docker compose up -d

The compose file builds the image from source using docker/Dockerfile.

Limitations

The deployment container runs on a scratch base. Features that require kernel access need extra privileges. The same table applies to the lab image:

Feature	Requirement
Interface configuration	--cap-add NET_ADMIN or --privileged
VPP data plane	Not supported in containers (use Appliance)
L2TP tunnels	--cap-add NET_ADMIN + host networking
nftables / firewall	--cap-add NET_ADMIN + --cap-add NET_RAW
Binding port 179	Works by default (container runs as root)

For BGP peering without interface management (route server, looking glass, policy testing), no extra capabilities are needed.

Troubleshooting

Container exits immediately: Ze needs start plus a config path. A bare path (ze:latest /etc/ze/ze.conf) exits 1 with unknown command: /etc/ze/ze.conf. Check docker logs ze.

Cannot connect to CLI: Make sure you ran ze init first and that port 1790 is published.

Peer won't connect: If peering with the host, use --network host or the Docker bridge gateway IP. Container-to-container peering works on a shared Docker network.

See also

• Install for native installation.
• netlab for labs built on the lab image.
• Appliance for the gokrazy VM appliance.
• Quick Start for first-time setup.

Adapted from main/docs/guide/docker.md.