Skip to content

Docker File

Docker Banner

Jetson Xavier NX

ubuntu 24.04

Prerequisites#

Important

Before building or running docker containers, ensure Docker is installed on the base station/Micipsa:

  1. Install Docker on Ubuntu
  2. Post-Installation steps to manage Docker as a non-root user.

Architecture#

The docker/ directory defines the containerized runtime environment for the Micipsa robot stack. It is organized into module-specific Docker images, each corresponding to a functional layer of the robot, along with shared configuration and orchestration files.

The base subfolder holds the common foundation image that all other layer images inherit from. Every other folder contains a Dockerfile structured as a four-stage build: base, build, dev, and deploy.

Each module typically contains:

  • Dockerfile: Defines the image build
  • entrypoint.sh: Startup script executed when the container launches

Foundation Image#

The micipsa/base:jazzy image serves as the minimal shared ROS 2 runtime for all layer images that inherit from this base image. It is built using configurable build arguments, allowing flexibility for future upgrades:

Build Argument Default Value Description
BASE_IMAGE ubuntu:24.04 Base operating system image
ROS_DISTRO jazzy ROS 2 distribution to install

With these build arguments, upgrading the entire stack to a newer or older ROS 2 distribution only requires rebuilding the foundation image with the desired ROS_DISTRO (and BASE_IMAGE, if needed). Since every layer image inherits from micipsa/base, they automatically pick up the new version on their next build, with no need to edit any of their individual Dockerfiles.

The image includes:

  • ROS 2 with ros-base packages
  • RMW implementation: rmw-cyclonedds-cpp is installed and configured via RMW_IMPLEMENTATION=rmw_cyclonedds_cpp
  • Non-root user: A user micipsa with UID/GID 1000 is created. The default ubuntu user (which occupies UID 1000 on Ubuntu 24.04) is removed to avoid conflicts

Layer Images#

Stages#

Every layer Dockerfile follows the same four-stages pattern.

The deploy stage inherits directly from the Foundation Image and not the layer own base stage, keeping the final image lean by discarding all build dependencies and build tooling, it copies only the compiled install artifacts from the build stage and installs the runtime dependencies required to run the package, resulting in a minimal, production image.

Entrypoint pattern#

All layer containers have their own entrypoint entrypoint.sh file.

It sources the ROS 2 environment (/opt/ros/${ROS_DISTRO}/setup.bash), then sources the workspace overlay if one has been built (/ros2_ws/install/setup.bash).

Build#

Important

All docker build commands must be run from the repository root (the parent directory of infra/), since the Dockerfiles use relative COPY paths that only resolve correctly from that location.

Warning

The foundation image must be built first, every layer image depends on it. If you don't want to use it, you'll need to edit that layer's Dockerfile accordingly.

Don't forget the trailing dot at the end of the docker build command.

Foundation Image#

cd ~/ros2_ws/src/micipsa/
docker build \
  -f infra/docker/base/Dockerfile \
  -t micipsa/base:jazzy-1.0.0 \
  .

Once built, tag the Foundation image as:

docker tag micipsa/base:jazzy-1.0.0 micipsa/base:foundation

Layer Image#

Important

Make sure to set --target to the environment stage you actually want.

Also make sure the image tag (-t micipsa/layer:ros_distro-1.0.0) reflects what you're actually building. See Tag Image.

For example, to build the actuation layer image:

cd ~/ros2_ws/src/micipsa/
docker build \
  --target deploy
  -f infra/docker/actuation/Dockerfile \
  -t micipsa/actuation:jazzy-1.0.0 \
  .

Run#

docker run -it micipsa/<layer>:<tag>

To open a second interactive shell inside a running container:

docker exec -it <container_name> bash

Tag Image#

Images follow a structured naming convention:

<repository>/<layer>:<ros_distro>-<semver>