Foundry · Infrastructure · swarm-routing/ns3-containers

ns3-containers

ns-3 pre-built and tested, so a contrib module compiles alone in seconds.

Unlocked: v1.0.0 released, 2 epics in progress, 3 planned Computed from its 6 epics · release v1.0.0, as they stood on .

RepositoryImage on GHCR

What it does

ns3-containers publishes ghcr.io/swarm-routing/ns3-dev (public, no login): ns-3 configured and built with Ninja at /opt/ns-3. A downstream module is linked into the warm tree by ns3-build-contrib and compiles alone; the smoke gate counts the Ninja steps (8 today, gate 40) to prove the cache was hit.

Automatic pipelines build only the release ns-3 supports (its latest), read from upstream's tags by tools/ns3_matrix.py, never a hand-typed version. Older releases are built on demand and kept as history. Four profiles: default, debug (CI), sanitized (ASan + LSan + UBSan) and optimized (ns-3's release, for campaigns only, never -march=native).

What is tested is what is tagged: each image is built once, every test stage runs on that build by digest (structure, profile, smoke, integration, unit, Trivy security), and the published tags are a carbon copy of that digest, then signed and attested. A published number pins the immutable :<ver>-<profile>-<sha7> tag.

The image pipeline itself is versioned: a release archives the Dockerfile, ns3-build-contrib, the test stages and tools/ at a commit, while an image tag stays the ns-3 release it was built from. Before a latest-* tag moves, the downstream canary builds and tests every org module on the new image.

Diagrams

ns3-containers: the publish-images pipelineThe publish-images pipeline: resolve the supported ns-3 release and base digests; build each image once as a candidate; run every test stage on that digest (structure, profile, smoke, integration, unit, security); promote by retagging the same digest; sign; attest; move the latest tags; discard the run's candidates.resolvens3_matrix.pybase digestsbuild oncecandidate inns3-dev-citest by digeststructure, profilesmoke, integrationunit, securitypromoteretag thesame digestsigncosignattestprovenancelatest-*moving tagsclean updiscard this run'scandidates
What is tested is what is tagged: one build, every test by digest, tags are a copy of that digest (imagetools create), never a rebuild.
ns3-containers: base × profile matrixWhich profiles are built for the supported ns-3 release on each base: Ubuntu 24.04 gets default, debug, sanitized and optimized; Debian 13 and Debian 13 slim get default and debug; Alpine, experimental, gets debug.defaultdebugsanitizedoptimizedUbuntu 24.04builtbuiltbuiltbuiltDebian 13builtbuilt——Debian 13 slimbuiltbuilt——Alpine (exp.)—built——
Images built for the supported release (the latest ns-3; 3.49 today). Older releases: on demand, Ubuntu, default and debug.
ns3-containers: a downstream module in CI (UML sequence diagram)How a protocol repository's CI uses an image: the reusable workflow pulls ns3-dev latest-debug, mounts the module, ns3-build-contrib links it into the warm ns-3 tree and builds only the module, then test.py runs its suites.protocol CIns3-dev imagens3-build-contribns-3 tree /opt/ns-3docker run latest-debugmount module (read-only)link into contrib/ninja: only the module's targetsbuilttest.py -s <module>suites pass / fail
A downstream CI job: only the module compiles (8 Ninja steps on the smoke fixture).

Package structure

The repository's layout, its licence per directory (LICENSING.md) and what exists today.

Directories of swarm-routing/ns3-containers
PathWhatLicenceState
docker/DockerfileBASE_IMAGE x NS3_VERSION x BUILD_PROFILE imageGPL-2.0-onlypresent
docker/scripts/build-contrib.sh/usr/local/bin/ns3-build-contrib: --strict-warnings, --coverage, --quality-modulesMIT OR GPL-2.0-onlypresent
tools/ns3_matrix.py (supported vs on-demand releases, base digests, tags), pr_tests.py, pass_markers.py, cache_tags.pyMIT OR GPL-2.0-onlypresent
tools/release/dist.sh: the release asset, the pipeline's source tarballMIT OR GPL-2.0-onlypresent
test/run.shevery test stage against one image ref (the candidate digest in CI)MIT OR GPL-2.0-onlypresent
test/{structure,profile,smoke,integration,unit}.shthe image contract, the profile's promise, incremental build, ns-3 simulates, ns-3's own suitesMIT OR GPL-2.0-onlypresent
test/downstream.{sh,txt}the downstream canary: every org module built and tested on the image (gates latest-*)MIT OR GPL-2.0-onlypresent
test/fixtures/swarm-hello (C++17..C++23 module), manet-canary, profile-probeGPL-2.0-onlypresent
.github/workflows/release.yml (releases through the org workflow); publish-images.yml (resolve, build once, test by digest, promote, sign, attest)GPL-2.0-onlypresent

Where it sits in the colony

The swarm-routing organisation: who depends on whomDependency graph of the swarm-routing organisation. ARA, BeeAdHoc, Termite and HOPNET link against swarm-core, which was extracted from AntHocNet, and register as arms in ns3-tools; AntHocNet runs its benchmarks on ns3-tools' harness; swarm-core and ns3-tools build and run inside the ns3-containers images; ns3-tools writes verdicts into benchmarks; the Colony Arena site builds AntHocNet's core to WebAssembly and will render the benchmarks leaderboard; the .github repository's reusable CI runs inside the ns3-containers images.linkslinkslinkslinksextractsarmarmarmarmbenchbuilds inruns inverdictscore/ → WASMleaderboard (planned)CI imagesAntHocNetprotocol · liveARAprotocolBeeAdHocprotocolTermiteprotocolHOPNETprotocolswarm-coreshared modulens3-toolsharness · readersns3-containersns3-dev imagesbenchmarksdatasets · verdictsColony Arenathis site.githubreusable CI · templatesdashed arrow: «use» dependency (UML); highlighted: this project and its neighbours
ns3-containers and its neighbours in the organisation.

Quests

The repository's epics and their sub-issues, as the issues stood on 2026-11-13: 13 of 32 sub-issues closed.

Closed: 1 epic

Cite this project

Using ns3-containers in a paper? Cite the project as below, and the works it rests on from its references.

Text

Joppi, Daniel Henrique (n.d.). ns3-containers (version 1.0.0) [Computer software]. https://doi.org/10.5281/zenodo.24202109

BibTeX

@software{ns3containers,
  author  = {Joppi, Daniel Henrique},
  title   = {ns3-containers},
  version = {1.0.0},
  doi     = {10.5281/zenodo.24202109},
  url     = {https://github.com/swarm-routing/ns3-containers}
}

Version
1.0.0
Author
Daniel Henrique Joppi · ORCID
DOI
10.5281/zenodo.24202109
Licence
GPL-2.0-only

Read from CITATION.cff at main when this site was built.

References

The 1 work docs/references.bib lists, read at main when this site was built. Each links its DOI; a work with none links its publisher's or institution's page.

Software it builds on

Sources

The status and the quests come from the repository's issues and releases (2026-11-13); the other facts on this page are kept by hand from its AGENTS.md (as of 2026-11-08).