Skip to content

Development setup

Contributions are welcome. Everything is in one repository, and you usually work on the server and the interface side by side:

Terminal window
git clone https://github.com/antimony-team/antimony
cd antimony
antimony/
├── 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.

Terminal window
cd server
# PostgreSQL and a Keycloak instance for OpenID Connect
docker compose up -d
# Build and run with the test configuration
task run

task 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/postgres creates the antimony user with password password123.
  • Keycloak on port 4022 with admin admin / admin and a realm imported from test/keycloak. The test configuration uses it as OpenID provider (http://localhost:4022/realms/antimony, admin group antimony-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.

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.

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.

  • Node.js 26
  • Yarn 1, for example through corepack enable
  • Task, for builds and Antimony Desktop. Some distributions install it as go-task.
Terminal window
cd interface
yarn install
yarn start

The 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.

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.

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.

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.

Terminal window
# Once: install the browser
npx playwright install chromium
yarn e2e # headless, like CI
E2E_KNOWN_BUGS=1 yarn e2e # also run the tests of known bugs as normal tests
task e2e-ui # interactive
task e2e-report # open the last report

Tests 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.

This site is built with Astro and Starlight.

Terminal window
cd site
npm install
npm 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:

Terminal window
npm run sync-api # from server/src/docs/swagger.json
npm run sync-api -- <path or URL> # from somewhere else
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.