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.
Requirements
Section titled “Requirements”- 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
Install
Section titled “Install”-
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 -xzcd antimony -
Create
.envfrom the example and fill it in.Terminal window cp .env.example .envSet the passwords and secrets. Generate random values with
openssl rand -hex 32. If port 8080 is taken on your host, setSB_PORTto another one. -
Start Antimony.
Terminal window docker compose up -dThe first start downloads the images. Then open
http://<host>:8080and sign in withSB_ADMIN_USERNAMEandSB_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.
What’s in the deployment
Section titled “What’s in the deployment”| 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.
Versions
Section titled “Versions”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:
ANTIMONY_VERSION=0.1.0 # a releaseANTIMONY_VERSION=dev # the development version, updated with every changeVerifying downloads
Section titled “Verifying downloads”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:
curl -fLO https://github.com/antimony-team/antimony/releases/download/v0.1.0/SHA256SUMSsha256sum -c SHA256SUMS --ignore-missingThe 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:
gh attestation verify antimony-deployment.tar.gz --repo antimony-team/antimonygh attestation verify oci://ghcr.io/antimony-team/antimony/server:0.1.0 --owner antimony-teamgh attestation verify oci://ghcr.io/antimony-team/antimony/interface:0.1.0 --owner antimony-teamThe images also contain a software bill of materials (SBOM), the list of every package inside them, for your vulnerability scanner:
docker buildx imagetools inspect ghcr.io/antimony-team/antimony/server:0.1.0 --format '{{ json .SBOM }}'Updating
Section titled “Updating”Run the install script again in the folder above your installation, or update by hand:
-
Download the deployment of the new release, as when installing, into a new folder.
-
Copy its
docker-compose.yml,.env.exampleandpostgres/over your installation. Keep your.env,config.ymlandkinds.conf.yml, and compare them with the new examples. -
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.
Variations
Section titled “Variations”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:
services: server: command: -config=./config.yml -sqlite volumes: - ./mnt/db:/app/dbdatabase: localFile: ./db/antimony.dbBehind 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/apiprefix - 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 |
Troubleshooting
Section titled “Troubleshooting”| 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. |