docker-netlogo

Base Dockerfile for CoMSES Net NetLogo images, based on eclipse-temurin:17-jre-jammy Docker images.

Uses a multi-stage build to produce a minimal final image that contains only the NetLogo installation in /opt/netlogo. The builder stage downloads, verifies, and smoke-tests NetLogo; the final stage copies only the verified installation—no example models, build tools, or download artifacts.

Images can be pulled from:

• Docker Hub: https://hub.docker.com/r/comses/netlogo
• GHCR: https://github.com/comses/docker-netlogo/pkgs/container/netlogo

Usage

Building the image

Use the provided Makefile to build and validate the image:

make build          # build comses/netlogo:7.0.4
make validate       # build and run a smoke test

You can override the NetLogo version with NETLOGO_VERSION:

make build NETLOGO_VERSION=7.0.4

The build runs a smoke test in the builder stage to verify the NetLogo installation before producing the final image.

Running headless NetLogo

The image's entrypoint is netlogo-headless.sh. The published image does not include example models—mount your model from the host:

docker run --rm -v "$PWD/examples:/opt/examples:ro" comses/netlogo:7.0.4 \
  --model /opt/examples/wolf-sheep-sd.nlogox \
  --experiment "smoke test" \
  --table -

Replace /opt/examples with the path to your own model directory as needed.

Inspecting the container

To open an interactive shell inside the container for debugging or exploration:

docker run --rm -it --entrypoint /bin/bash comses/netlogo:7.0.4

From there you can inspect the installed files under /opt/netlogo, run NetLogo commands directly, or test scripts.

Pulling from GHCR

docker pull ghcr.io/comses/netlogo:7.0.4
docker pull ghcr.io/comses/netlogo:latest

Available Makefile targets

Target	Description
make build	Build the Docker image
make tag-latest	Build and tag the image as latest
make tag-ghcr	Tag the built image for GHCR (version and latest)
make push-ghcr	Tag and push the image to GHCR (requires docker login ghcr.io)
make validate	Build and run a smoke test
make smoke-test	Run a headless NetLogo model to verify the image
make check-checksum	Verify the NetLogo tarball checksum
make clean	Remove dangling images from the build cache
make distclean	Remove all built images for this project

Releasing

Pushing a git tag matching v* (e.g. v7.0.4) triggers the GitHub Actions workflow which builds the image and pushes it to ghcr.io/comses/netlogo with both the version tag and latest:

git tag v7.0.4
git push origin v7.0.4

The workflow uses the auto-provided GITHUB_TOKEN with packages: write permission — no extra secrets are required. After the first push, set the package visibility to public in the GitHub package settings if desired.