Draft: Docker: ns-3 Docker images

Add support to build Docker images of ns-3.

NOTE: This is a work in progress, which will be developed during the following months. Suggestions and improvements are welcome.

To Do

The following is a list of tasks to complete. It contains ideas and personal notes to track the progress of this MR.

• Finish Dockerfile.
  • Use arguments to configure the building process.
  • Define default ns-3 configuration and supported flavors.
  • Each flavor corresponds to a different configuration of ns-3, namely:
    • Build profiles: debug, default and optimized.
    • Dependencies and enabled modules: full and slim.
  • Add labels with metadata about the project.
• Add CI/CD jobs to automatically build Docker images.
  • Create and tag stable releases.
    • Newer releases will be automatically built by the CI/CD.
    • Old releases will need to be manually built.
  • Create and tag a "development" image for the current ns-3-dev (latest commit). This image is built and updated (overriding the former) daily.
  • Use the arguments in the Dockerfile.
• Create template docker-compose.yml with instructions on how to mount directories into the container.
• Create Docker images for the CI/CD and update the CI to use them.
  • Define what Linux OS's will be officially tested by ns-3.
  • Suggest trimming the pool of OS's to only 1-2 (e.g., only the latest two Ubuntu LTS).
• Revise CI / CD settings and permissions, so that only authorized users can run the jobs.
  • Malicious users can create a MR that edits the CI/CD script to push malicious images to the registries. This can happen because we previously configured MRs to run pipelines on nsnam's namespace. This problem does not exist if MRs run pipelines on the fork's namespace.
  • Reference: merge_request_pipelines.html#run-pipelines-in-the-parent-project
• Write documentation.
• Publish Docker images to GitLab's container registry.
• Setup ns-3 organization in Docker Hub and publish the Docker images there.

Vision

My proposal for ns-3 Docker images is similar to what other projects are doing. One example is Tensorflow, which provides Docker images so that users can quickly run scripts without needing to manage dependencies.

https://www.tensorflow.org/install/docker

Objectives

The main objectives for ns-3 Docker images are:

• Provide official Docker images that can be used to quickly run ns-3 simulations, without requiring the installation of dependencies and having ns-3 already configured and built.
• Develop ns-3 simulations and modules using the Docker image as a development environment, alleviating the need to install and manage dependencies.
• Test third-party modules for ns-3, without needing to install dependencies, nor downloading and building ns-3 from scratch.
• Enable users to build their own customized images of ns-3 on their local PCs.
• Use these images as a base image for other Dockerfile's.

Use Cases

Possible use cases include:

• Education, academia and industry: have a ready-to-use environment to quickly edit / run ns-3 simulations, without installing dependencies and building ns-3 from scratch.
• Continuous integration of third-party modules for ns-3, hosted elsewhere.

Distribution of the ns-3 Docker Images

The Docker images will be published in Docker Hub, so that all users can pull them without any limitation or extra configurations. Additionally, the images will also be published in the ns-3 GitLab's container registry.

Official images will be provided for stable releases of ns-3 and a "development" image that is in sync with ns-3-dev (latest commit).

Instructions to Pull, Build and Run Docker Containers

The instructions to pull, build and run ns-3 Docker containers are explained below.

Pull Docker Image from Registries

Pull from Docker Hub (Not Yet Available)

The recommended method for getting a Docker image will be to pull it from Docker Hub. Please note that this feature is not yet available.

To pull a Docker image from Docker Hub (default Docker registry), run the following command on a shell:

# Pull latest image (default)
docker pull ns-3-dev

# Pull another version referenced by TAG (stable release + ns-3 configuration) (e.g., ns-3.40-optimized)
docker pull ns-3-dev:TAG

Pull from GitLab's Container Registry

Alternatively, users can pull Docker images from GitLab's container registry. To do so, run the following commands:

# First, login to GitLab's container registry with your username and password
docker login registry.gitlab.com

# Then, pull the image
docker pull registry.gitlab.com/nsnam/ns-3-dev/ns-3

Build (Custom) Docker Image on Local PC

To build a (custom) Docker image of ns-3-dev on your local PC, run the following command in ns-3's main directory:

docker build -t ns-3-dev .

If you would like to customize this Docker image, feel free to edit Dockerfile to your needs.

Run the ns-3-dev Docker Container

After building the ns-3-dev Docker image, you can run a Docker container of ns-3-dev with the following command:

docker run -it --rm ns-3-dev

The terminal will launch the container directly on the ns-3-dev directory, with the project already configured and built. You can use ns-3 as usual within this shell, namely running examples or tests.

NOTE: For testing purposes, and to speed up the building process, only the core module is enabled for now. If you would like to build a Docker image with the full ns-3 already configured and compiled, edit / remove the line --enable-modules=core of Dockerfile.

Add Custom Modules or Simulation Scripts

To add your own modules or simulation scripts, you can run the Docker container and configure a mount point from a local directory in your PC to a directory in the container. For example, suppose you have a simulation script my-simulation.cc located in your home directory ~/. To run the ns-3-dev Docker container and mount this file to the container's ns-3-dev/scratch/ directory, run the following command:

docker run -it --rm -v ~/my-simulation.cc:/ns-3-dev/scratch/my-simulation.cc ns-3-dev

You can inspect that the file was, indeed, mounted on the container and then build / run the my-simulation.cc by running the following commands on the container's shell:

# Inspect file
ls scratch/

# Build ns-3 with the simulation script (only the new file needs to be compiled)
./ns3 build

# Run the simulation script
./ns3 run my-simulation

Please note that you can share files between the host PC and the Docker container either using Docker volumes or Docker mount points.