Docker for ROS Development

This repository provides ROS1 and ROS2 Docker images for easy development with the wheelchair.

This documentation is split into four parts:

• List of features and images
• Instructions for everyone (GHCR authentication)
• How to use an image
• How to build an image

Note

This repository uses GitHub Actions for CI/CD. Further documentation on how we have implemented this is available in the CI/CD documentation.

List of ROS2 Features and Images

Image name	Base image	Intended target	Features
humble	ubuntu:jammy	x86_64 laptop	- ROS2 Humble Hawksbill packages - non-root user
humble_gpu	nvidia/cuda:12.2.2-devel-ubuntu22.04	x86_64 laptop	- ROS2 Humble Hawksbill packages - CUDA - CuDNN - non-root user
humble_harmonic	humble_gpu	x86_64 laptop	- Gazebo Harmonic (recommended over fortress)
wheelchair2_base	humble	x86_64 laptop	- Realsense SDK - Livox SDK
wheelchair_2_base_gazebo	humble_harmonic	x86_64 laptop	- ros2_control - RGLGazeboPlugin - Nvidia Optix for gz-sim - Realsense SDK - Livox SDK
humble_jetson	nvcr.io/nvidia/l4t-jetpack	Jetson (ARM64)	- ROS2 Humble Hawksbill packages - non-root user
wheelchair2_base_jetson	humble_jetson	Jetson (ARM64)	- Realsense SDK - Livox SDK

Caution

The ROS1 images are currently under development and have not been heavily tested. They may be unstable or contain significant bugs.

Authenticating to GitHub Container Registry

To pull or push images to the GitHub Container Registry, you need to authenticate using a personal access token (PAT) with the write:packages and repo scopes.

Brief steps are given below, but you can find more detailed instructions in the GitHub documentation.

1. Create a personal access token (PAT) with the required scopes.

2. Log in to the GitHub Container Registry using the following command:

   echo <YOUR_PAT> | docker login ghcr.io -u <YOUR_GITHUB_USERNAME> --password-stdin

3. Verify that you are logged in by running:

   docker info

Debugging

If docker throws the error even after restarting the Docker daemon:

Cannot connect to the Docker daemon at unix:///var/run/docker.sock. Is the docker daemon running?

You can try the following steps:

1. Docker networking requires IP forwarding. Check if it's enabled:

   sysctl net.ipv4.ip_forward

2. If it returns 0, enable it with:

   sudo sysctl -w net.ipv4.ip_forward=1

3. Then restart the Docker daemon:

   sudo systemctl restart docker

Pulling an image

To download a pre-built image from GitHub Container Registry (ghcr.io), use the following command:

docker pull ghcr.io/smart-wheelchair-rrc/<image_name>:<tag>

Replace <image_name> with the desired image name (e.g., humble, wheelchair2_base). For example:

docker pull ghcr.io/smart-wheelchair-rrc/humble:v3.0

Important

Please be mindful of the tag you are pulling. The latest tag is not used in this repository, so you need to provide a specific version tag (e.g., v3.0).

Building an image

Since this repository uses CI/CD builds, certain considerations must be taken into account when building images:

1. Dependant images

   Certain images depend on other images. For example, wheelchair2_base_gazebo depends on humble_harmonic. If you want to build wheelchair2_base_gazebo, you need to build humble_harmonic first.

   In the dependant image's Dockerfile, you can specify the base image as follows:

   FROM ghcr.io/smart-wheelchair-rrc/humble_harmonic:v3.0

   Again, please be mindful of the tag you are using. If you update a base image, and you want the changes to reflect in the dependant image, you need to rebuild the dependant image with the correct tag of the base image.

2. Online builds must be tagged

   The CI/CD system will not initiate builds if the image is not tagged. Moreover, your tag must follow the SemVer format. For example: v3, v3.0, v3.1.0. So your tag names must start with v and be followed by a version number.

   Once a commit has been tagged and pushed to the repository, the CI/CD system will automatically build the image and push it to the GitHub Container Registry. It will attempt to do this regardless of the branch you are on.

3. Building locally

   If you want to build locally, you're free to use any tags you like, however you should be mindful of dependant images and their tags. You can build an image using the following command:

   docker build -t ghcr.io/smart-wheelchair-rrc/<image_name>:<tag> -f <path/to/Dockerfile> <build_context>

   Replace <image_name> with the desired image name, <tag> with the version tag, and <build_context> with the directory containing the Dockerfile. For example, to build the humble image:

   docker build -t ghcr.io/smart-wheelchair-rrc/humble:v3.0 -f ROS2/AMD64x86/humble/Dockerfile ROS2/AMD64x86/humble

4. Pushing the image

   After building the image, you can push it to the GitHub Container Registry using the following command:

   docker push ghcr.io/smart-wheelchair-rrc/<image_name>:<tag>

   For example, to push the humble image:

   docker push ghcr.io/smart-wheelchair-rrc/humble:v3.0

Important

Avoid using the latest tag.

Explanation of the docker build command

The docker build command is used to create a Docker image from a Dockerfile. Here's a breakdown of the command and its arguments:

docker build -t ghcr.io/smart-wheelchair-rrc/<image_name>:<tag> -f <path/to/Dockerfile> <build_context>

Argument	Value	Example	Description
-t	ghcr.io/smart-wheelchair-rrc/<image_name>:<tag>	ghcr.io/smart-wheelchair-rrc/humble:v3.0	Tags the image with the specified name and version tag.
-f	<path/to/Dockerfile>	ROS2/AMD64x86/humble/Dockerfile	Specifies the path to the Dockerfile to use for building the image.
	<build_context>	ROS2/AMD64x86/humble	The build context, which is the directory containing the Dockerfile and any other files needed for the build.

Recommendations for tagging images

Suggestions for filling in the SemVer version tag.

Let us assume that the latest image before you start working is v3.14. Therefore, the next image you target to release will be v3.15.

However, the CI/CD workflow requires that you tag every commit where you want to build an image AND GitHub requires commit tags to be unique. If you wish to use the online builds to test your changes, you can use the dev* tags. For example, you can tag your commit as dev3.15.0 or dev3.15.1. This way, you can test your changes without affecting the main versioning scheme.

When you are ready to release the next version (most likely a merge commit), you can tag it as v3.15.0 or v3.15. This will trigger the CI/CD workflow to build the image with the correct version tag.

Note

• v* tags should only be used on the master branch.
• dev* tags may be used on any branch (including master).

Git clones inside the Dockerfile

When we're building a package from a GitHub repository, we only need the latest commits. We achieve this using the --depth=1 option in the git clone command. This option tells Git to clone only the latest commit, which is sufficient for building the package.

Moreover, Git usually doesn't print logs to stdout when run in a container, but these are very useful for debugging. We enable these using the --progress --verbose flags. Therefore, a complete git clone command would look like this:

git clone --depth=1 --progress --verbose <repository_url>

As an example:

git clone --depth=1 --progress --verbose https://github.com/rtarun1/Livox-SDK2.git 

Acknowledgements

• The initial Dockerfiles were inspired by the work of soham2560.
• The CI/CD system was set up by eccentricOrange.