Development setup
Contributions are welcome. Everything is in one repository, and you usually work on the server and the interface side by side:
git clone https://github.com/antimony-team/antimonycd antimonyantimony/├── server/ The Antimony server, written in Go├── interface/ The web interface and Antimony Desktop, written in React and Electron├── site/ The website with the documentation├── .github/ CI, end-to-end tests and releases└── docker-compose.yml, config.yml, … The deployment files that come with every release| Directory | Language | Runs locally on |
|---|---|---|
server/ |
Go | localhost:3100 (API), localhost:6767 (SSH) |
interface/ |
React, TypeScript, Vite | localhost:5173 |
site/ |
Astro, Starlight | localhost:4321 (this documentation) |
The development ports differ from those of the Docker deployment (8080, 3000 and 6969), so both can run on the same machine.
Server
Section titled “Server”Prerequisites
Section titled “Prerequisites”- Go 1.26
- Task
- containerlab and Docker, for deploying real labs
- golangci-lint for linting
Run it
Section titled “Run it”cd server
# PostgreSQL and a Keycloak instance for OpenID Connectdocker compose up -d
# Build and run with the test configurationtask runtask run builds the server into build/, copies data/, the test config (test/config.test.yml) and test/kinds.conf.yml next to it, and starts it with sudo in development mode. containerlab and packet capture need root.
The development docker-compose.yaml starts:
- PostgreSQL 18 on port 5432. Its init script in
test/postgrescreates theantimonyuser with passwordpassword123. - Keycloak on port 4022 with admin
admin/adminand a realm imported fromtest/keycloak. The test configuration uses it as OpenID provider (http://localhost:4022/realms/antimony, admin groupantimony-admin).
The admin login is admin / admin. After an OpenID login, Keycloak redirects back to http://localhost:3100/users/login/success, which the imported realm allows. If you change openIdRedirectHost in the test configuration, also change the client’s redirect URI in Keycloak.
Other tasks
Section titled “Other tasks”| Task | What it does |
|---|---|
task build |
Builds the server into build/ without running it. |
task run-c9s |
Runs with test/config-c9s.test.yml, using the clabernetes provider. |
task setup-kind |
Creates a local kind cluster named c9s and installs clabernetes 0.10.1. |
task install-c9s |
Installs clabernetes 0.10.1 into the cluster of the current kubeconfig. |
task build-docker |
Builds the Docker image antimony-server:dev. |
task run-docker |
Builds the image and runs it with SQLite and the Docker test configuration. |
task test |
Runs the tests. |
task test-race |
Runs the tests with the race detector, in random order. CI uses this. |
task test-coverage |
Runs the tests with a coverage report. |
task test-e2e-containerlab |
Runs the provider and server end-to-end tests against containerlab on this Docker host, with sudo. CI uses containerlab 0.81.0. |
task test-e2e-clabernetes |
Runs the provider and server end-to-end tests against clabernetes in the cluster of the current kubeconfig, see task setup-kind. |
task lint / task lint-fmt |
Lints or formats the code with golangci-lint. |
task swag |
Regenerates the Swagger documentation in src/docs/. |
task swag-check |
Fails if the committed Swagger documentation is outdated. CI uses this. |
task clean |
Removes build/. |
The integration tests in src/test/ run the whole server in-process with the dummy provider and a test OpenID server, so they don’t need Docker.
API documentation
Section titled “API documentation”The REST API is documented with swag annotations on the handlers. After changing them, run task swag and commit src/docs/. A running server serves Swagger UI at /swagger/index.html.
Interface
Section titled “Interface”Prerequisites
Section titled “Prerequisites”- Node.js 26
- Yarn 1, for example through
corepack enable - Task, for builds and Antimony Desktop. Some distributions install it as
go-task.
Run it
Section titled “Run it”cd interfaceyarn installyarn startThe development server runs on localhost:5173. It forwards /api (without the prefix) and /socket.io to the development server of the backend on localhost:3100.
Scripts and tasks
Section titled “Scripts and tasks”The everyday commands are Yarn scripts:
| Script | What it does |
|---|---|
yarn start |
Development server with hot reload. |
yarn build |
Production build into dist/. |
yarn test |
Runs the unit tests in tests/, which mirrors src/ (e.g. tests/lib/graph/placement.test.ts tests src/lib/graph/placement.ts). |
yarn test:coverage |
Runs the unit tests and reports the coverage of src/lib into coverage/. |
yarn lint |
Lints with gts. |
yarn typecheck |
Type-checks without building. |
yarn e2e |
Runs the end-to-end tests. |
yarn e2e:provider |
Runs the end-to-end tests that deploy with containerlab. |
Everything that takes more than one step is a task in Taskfile.yml. Tasks install the dependencies when needed and skip builds whose inputs haven’t changed. task --list shows them all.
| Task | What it does |
|---|---|
task check |
Lint, type check and unit tests in parallel. |
task build-dev |
Development build with source maps into dist/. |
task preview |
Builds and serves the production build. |
task build-docker |
Builds the Docker image antimony-interface:dev. |
task build-electron |
Builds Antimony Desktop without packaging it. Start it with yarn electron .. |
task package-electron-linux |
Builds Antimony Desktop as AppImage, .deb and .rpm for x86_64 and ARM64 into release/. |
task e2e-provider |
Runs the end-to-end tests that deploy with containerlab, asking for the sudo password first. |
task e2e-ui |
Opens the end-to-end tests in Playwright’s UI. |
task e2e-report |
Opens the report of the last end-to-end run. |
task clean |
Removes the build output. |
Where the interface finds the server
Section titled “Where the interface finds the server”The interface needs no configuration. In the browser, it calls /api and /socket.io on the address it was opened at, which the development server, the e2e preview and Traefik in the Docker deployment forward to the server. Antimony Desktop gets the address of the server it started at runtime.
To build an interface that talks to a server elsewhere, set these variables when building, for example SB_API_SERVER_URL=https://lab.example.com/api yarn build:
| Variable | Default | Description |
|---|---|---|
SB_API_SERVER_URL |
/api |
Base URL of the REST API. |
SB_SOCKET_SERVER_URL |
the page’s own origin | Base URL of the Socket.IO server, without /socket.io. |
End-to-end tests
Section titled “End-to-end tests”The Playwright tests build the server in server/ and start it with the dummy provider and a fresh database, together with a test build of the interface, on ports that don’t collide with development (API 3200, SSH 6200, interface 4180). They need Go besides Node.js, but no Docker image. CI runs them on every push and on pull requests that change the server or the interface.
# Once: install the browsernpx playwright install chromium
yarn e2e # headless, like CIE2E_KNOWN_BUGS=1 yarn e2e # also run the tests of known bugs as normal teststask e2e-ui # interactivetask e2e-report # open the last reportTests of bugs that aren’t fixed yet are marked with knownBug() and expected to fail. The interface’s e2e/README.md explains how to write tests. To test against a server image instead, set SB_E2E_BACKEND_IMAGE=<image>, for example antimony-server:dev after task build-docker in server/.
The tests in e2e/provider/ deploy labs with a real containerlab instead and check the nodes, shells and stats in the interface. The server runs as root for containerlab, so they need containerlab, the alpine:latest image and sudo without a password prompt. task e2e-provider runs sudo -v first and then yarn e2e:provider. They only clean up labs they created themselves.
Documentation
Section titled “Documentation”This site is built with Astro and Starlight.
cd sitenpm installnpm run dev| Path | Contents |
|---|---|
src/pages/index.astro |
The landing page |
src/content/docs/docs/ |
The documentation pages, in Markdown and MDX |
src/components/diagrams/ |
The diagrams, as Astro components with inline SVG |
openapi/antimony.swagger.json |
Copy of the server’s Swagger file for the REST API reference |
plugins/release-version.mjs |
Fills in the version of the current release, see below |
Install commands and download links name the files of the current release, so that they can be copied as they are. Write %VERSION% where the version goes, in text, code or links. The build replaces it with the latest stable release from GitHub, or the newest pre-release while there’s no stable one, and with x.y.z if there’s no release or GitHub can’t be reached. Set ANTIMONY_RELEASE=0.2.0 to build with another version. The release workflow rebuilds the website after every release.
Update the REST API reference after the server’s API changes:
npm run sync-api # from server/src/docs/swagger.jsonnpm run sync-api -- <path or URL> # from somewhere elseContinuous integration
Section titled “Continuous integration”| Workflow | Runs on | What it does |
|---|---|---|
ci.yml |
Pushes to development and main, PRs, tags v*, manually |
The server’s lint, Swagger check, build with a startup smoke test and tests with the race detector, and the interface’s lint, type check and unit tests with coverage (uploaded as the artifact coverage-report), all in parallel. Then the Docker images, and Antimony Desktop (AppImage, .deb and .rpm for x86_64 and ARM64), which is kept as the artifact antimony-desktop. For a v* tag, e2e.yml runs as well, and the release follows once it passes. |
fuzz.yml |
Nightly, manually | Fuzz tests of the server |
e2e.yml |
Pushes to development and main, PRs, tags v* (through ci.yml), manually |
The server’s provider and server end-to-end tests against containerlab and against clabernetes in a kind cluster, and the interface’s end-to-end tests against the server of the same commit, once with the dummy provider and once deploying with containerlab |
release.yml |
Called by ci.yml for tags v* |
Packs the deployment files with that version, writes their checksums and those of Antimony Desktop to SHA256SUMS, attests them, creates the GitHub release with them and starts docs.yml |
docs.yml |
Pushes to main and PRs that change site/, release.yml, manually |
Builds this website and publishes it to GitHub Pages from main |
Pull requests only run the jobs of the parts they change: a change in interface/ skips the server’s jobs and the provider tests, and a change in server/ skips the interface’s jobs. The interface’s end-to-end tests run for changes on either side, since they test both. Pushes and tags always run everything.
ci.yml builds the images for amd64 and arm64. Pull requests only build them. Pushes publish them as :dev (from development) or :main (from main), and tags as :<version>, :<major>.<minor> and :latest, under ghcr.io/antimony-team/antimony/server and ghcr.io/antimony-team/antimony/interface. Every published image contains an SBOM and its build provenance, and gets a build attestation signed by GitHub.
To release a version, tag it on main and push the tag, for example git tag v0.2.0 && git push origin v0.2.0. The release is created once the end-to-end tests pass and both images of that version are published, since its deployment archive and Antimony Desktop start them.