Skip to content

Deploy with Docker

Every release of Antimony comes with a ready-to-use deployment, antimony-deployment.tar.gz: a Docker Compose file with Antimony, PostgreSQL and the Traefik reverse proxy, plus the configuration files. It starts the Antimony images of its release from the GitHub container registry. Antimony deploys labs with containerlab on the same host.

Docker deploymentBrowsers connect to Traefik on port 8080. Traefik routes the root path to the interface on port 8100, and /api and /socket.io to the Antimony server on port 3000. The server stores data in PostgreSQL and starts lab containers through the Docker socket with containerlab. SSH clients connect to the server's SSH port directly.Browserhttp://host:8080SSH / Wiresharkssh -p 6969Docker host · network_mode: hostTraefik:8080 · HTTProutes by pathInterface:8100 · static filesAntimony server:3000 REST + Socket.IO:6969 SSHprivileged · pid: hostcontainerlab insideconfig.yml//api/socket.ioPostgreSQL:5432Docker daemon/var/run/docker.sockLab containersclab-<instance>-<node>shells, capture
The default Docker Compose setup. Traefik routes requests by path to the interface and the server. The server starts lab containers next to itself through the host's Docker daemon.
  • A Linux host with Docker Engine and the Compose plugin
  • Enough memory for your labs: 1–4 GB per network node, depending on the image
  • Port 8080 reachable for your users, or another port set with SB_PORT
  1. Download the deployment of the current release, Antimony 0.1.0.

    Terminal window
    curl -fsSL https://github.com/antimony-team/antimony/releases/download/v0.1.0/antimony-deployment.tar.gz | tar -xz
    cd antimony
  2. Create .env from the example and fill it in.

    Terminal window
    cp .env.example .env

    Set the passwords and secrets. Generate random values with openssl rand -hex 32. If port 8080 is taken on your host, set SB_PORT to another one.

  3. Start Antimony.

    Terminal window
    docker compose up -d

    The first start downloads the images. Then open http://<host>:8080 and sign in with SB_ADMIN_USERNAME and SB_ADMIN_PASSWORD.

That’s it. To change settings, such as enabling OpenID Connect or switching to clabernetes, edit config.yml and restart the server with docker compose restart server. All settings are described in Configuration.

File Purpose
docker-compose.yml The services: Traefik, PostgreSQL, the interface and the server, with the images of the release.
.env.example Web port, passwords, secrets and the version. Copy it to .env.
config.yml Server configuration.
kinds.conf.yml Per-kind settings, such as SSH logins for terminals.
postgres/init-database.sh Creates the database and its user on the first start.

Data is stored in:

Path Contents
/srv/antimony/ Topologies, bind files and lab directories
./.db/ PostgreSQL data
./mnt/ssh/ Host key of the SSH server

Back up /srv/antimony/ and ./.db/ together.

Port Service Open to
8080 (SB_PORT) Web interface and API over plain HTTP, through Traefik Your users
6969 SSH server for terminals and packet capture Trusted networks only. It doesn’t authenticate clients.

The API on 3000, the interface on 8100 and PostgreSQL on 5432 only listen on localhost. All services use the host’s network, so these ports must still be free on the host.

The deployment of a release starts the images of that release, ghcr.io/antimony-team/antimony/server:<version> and ghcr.io/antimony-team/antimony/interface:<version>. To run another version, set it in .env:

.env
ANTIMONY_VERSION=0.1.0 # a release
ANTIMONY_VERSION=dev # the development version, updated with every change

Every release lists the SHA-256 checksums of its files in SHA256SUMS. The install script checks the deployment archive against it before it unpacks anything. To check a download yourself:

Terminal window
curl -fLO https://github.com/antimony-team/antimony/releases/download/v0.1.0/SHA256SUMS
sha256sum -c SHA256SUMS --ignore-missing

The release files and the images also carry signed build provenance: a record, signed by GitHub, that they were built by the workflows of the Antimony repository from the code of that version. Check it with the GitHub CLI:

Terminal window
gh attestation verify antimony-deployment.tar.gz --repo antimony-team/antimony
gh attestation verify oci://ghcr.io/antimony-team/antimony/server:0.1.0 --owner antimony-team
gh attestation verify oci://ghcr.io/antimony-team/antimony/interface:0.1.0 --owner antimony-team

The images also contain a software bill of materials (SBOM), the list of every package inside them, for your vulnerability scanner:

Terminal window
docker buildx imagetools inspect ghcr.io/antimony-team/antimony/server:0.1.0 --format '{{ json .SBOM }}'

Run the install script again in the folder above your installation, or update by hand:

  1. Download the deployment of the new release, as when installing, into a new folder.

  2. Copy its docker-compose.yml, .env.example and postgres/ over your installation. Keep your .env, config.yml and kinds.conf.yml, and compare them with the new examples.

  3. Start the new version:

    Terminal window
    docker compose up -d

Running labs keep running while the server restarts, and the server reattaches to them when it’s back. Set SB_JWT_SECRET in .env so that users stay signed in.

With HTTPS

Put a reverse proxy that handles HTTPS in front of Antimony, for example Caddy, nginx or your organization’s proxy, and forward all requests to localhost:8080 with WebSocket upgrades. Then only open the proxy’s port to your users, not 8080.

SQLite instead of PostgreSQL

For small installations, start the server with -sqlite, and remove the database service and the server’s depends_on: database:

docker-compose.yml
services:
server:
command: -config=./config.yml -sqlite
volumes:
- ./mnt/db:/app/db
config.yml
database:
localFile: ./db/antimony.db
Behind your own reverse proxy

Remove the traefik service and the traefik.* labels, and configure your proxy to:

  • serve the interface (localhost:8100) at /
  • forward /api/* to the server (localhost:3000) without the /api prefix
  • forward /socket.io/* to the server (localhost:3000) with WebSocket upgrades

The interface and the API must be on the same host name.

Why the server container is privileged

The server runs containerlab and reaches into the lab containers it creates:

Setting Needed for
/var/run/docker.sock Creating and controlling lab containers through the host’s Docker
/var/run/netns, /var/lib/docker, /etc/hosts containerlab’s network namespaces, links and host entries
privileged, user: root Creating links and capturing packets inside container network namespaces
pid: host Reading container interfaces and joining their namespaces through /proc
cgroup: host CPU and memory statistics from cgroup v2
network_mode: host Reaching the nodes’ management addresses for terminals
/srv/antimony at the same path containerlab passes bind file paths to the host’s Docker, so they must exist at the same location on the host
Problem Solution
The page says “Unable to connect to the Antimony server.” Check docker compose logs server. The server logs Antimony API is running and ready to serve calls! when it’s up.
cgroup v2 is required for container stats The host uses cgroup v1. Current distributions use cgroup v2 by default.
Failed to retrieve containers from clab inspect. Exiting. The server can’t reach Docker. Check that the Docker socket is mounted.
Nodes start without their configuration files /srv/antimony isn’t mounted at the same path in the container.
Everyone is signed out after an update SB_JWT_SECRET isn’t set in .env.
Docker Desktop on Linux Antimony needs Docker Engine. If both are installed, run Compose with DOCKER_HOST=unix:///var/run/docker.sock.