Packaging with Docker

For many common use cases, given a valid artefacts.yaml configuration file, Artefacts will run automatically, both when running on the artefacts infrastucture (run-remote) and when using artefacts run --in-container. Please refer to cloud-simulation for more details about running jobs on the artefacts infrastructure.

Artefacts also supports custom Docker configuration files. This guide explains the condition for running smoothly on Artefacts.

When to use a custom Dockerfile or image name

When running on Artefacts cloud simulation (run-remote), or when using artefacts run --in-container, you currently need to specify a custom Dockerfile or image in the following situations:

• Not using ROS
• Not using a supported ROS version
• Not using a supported simulator
• Your project has a separate / additional build stage to the src folder of the project repository.
• Your project has other specific requirements

my-job:
  type: test
  package:
    docker:
      build: # Sample with a custom Dockerfile. Another option is to specify an image.
        dockerfile: ./Dockerfile

An example Dockerfile is available on our nav2 example project

Artefacts Base Images

We have prepared a number of images which you are freely welcome to use as a base layer of your ROS2 projects. These base images contain:

• The tag’s corresponding ROS version (e.g. humble-fortress contains the ros-humble-ros-core package)
• The tag’s corresponding simulator
• Commonly used ROS dependencies for that ROS/simulator combination (such as ros-humble-ros-ign-bridge in our ROS2 Humble / Fortress base image)
• Necessary build tools (catkin / colcon)
• Initializes and updates rosdep
• The artefacts CLI
• For our jazzy (Ubuntu 24, Python 3.12) images, a virtual environment is already set up at /opt/venv and activated. The PYTHONPATH environment variable is pre-configured to include both the virtual environment’s site-packages and the system’s dist-packages. This ensures that both pip-installed packages and ROS packages are available, even after sourcing ROS. As a result, you do not need to create or manually configure a Python virtual environment.

A full list of public available base images are can be found ECR public registry. They follow the below naming convention:

public.ecr.aws/artefacts/<framework>:<framework_version>-<simulator>-gpu
# -gpu is optional
# Examples:
public.ecr.aws/artefacts/ros2:humble-fortress
public.ecr.aws/artefacts/ros2:humble-fortress-gpu

By using these base images, your project Dockerfile will then need to perform (as a minimum) the following steps:

• Copy over your project files
• Install your ROS dependencies
• Build your project
• Run the artefacts client

As an example, a ROS2 Humble / Ignition Fortress project’s Dockerfile could look like the following to work with artefacts:

# Use the artefacts ROS2 humble base image
FROM public.ecr.aws/artefacts/ros2:humble-fortress

# Set the working directory and copy our project
WORKDIR /ws
COPY . /ws/src

# ROS dependencies
RUN rosdep install --from-paths src --ignore-src -r -y
# Source ROS version and build
RUN . /opt/ros/galactic/setup.sh && colcon build --symlink-install

WORKDIR /ws/src

# Source colcon workspace and run the artefacts client
CMD . /ws/install/setup.sh && artefacts run $ARTEFACTS_JOB_NAME

Dockerfile requirements

The docker file must currently comply to 2 requirements:

• it must install the CLI (already installed in artefacts provided base images)

RUN pip install artefacts-cli

• the container launch command must run the CLI:

CMD artefacts run $ARTEFACTS_JOB_NAME

It can then be run with artefacts run <job_name> --in-container (local) or artefacts run-remote <job_name> (cloud simulation)