Skip to content

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

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

Note: The gpu enabled images are specifically designed to run on the artefacts infrastructure, and with NVIDIA gpus. As a result they do not require any additional environment variables to be set when running on artefacts cloud simulation. They are only available as amd64 (not arm)

If you are running locally, you may need to install the NVIDIA Container Toolkit, and set some environment variables ('ENV'). See NVIDIA's installation guide and user guide for more details.

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 galactic 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)