# Packaging with Docker

Site [llms.txt](/llms.txt)

---

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](/user-guide/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

```yaml
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](https://github.com/art-e-fact/navigation2_ignition_gazebo_example/blob/main/Dockerfile)

## 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](https://gallery.ecr.aws/artefacts/ros2). 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](https://docs.nvidia.com/datacenter/cloud-native/container-toolkit/install-guide.html) and [user guide](https://docs.nvidia.com/datacenter/cloud-native/container-toolkit/user-guide.html) 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:
```docker
# 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)