tutorials vrx_docker_scripted - osrf/vrx GitHub Wiki
In this tutorial we automate the entire process of creating the competitor image using a script called a Dockerfile
.
- This is one of two options for building a competitor image.
- The first option is described here.
- The primary advantage of this approach is that it is self-documenting and easily reproducible.
Follow the steps below to get a minimal version of a competitor image up and running:
-
Create a directory to store your
Dockerfile
and any other files needed for your image.mkdir ~/my_vrx_docker; cd ~/my_vrx_docker
-
Create a file called
Dockerfile
, open it in a text editor, and copy in the following:FROM ros:humble-ros-base-jammy # Set up timezone ENV TZ=Etc/UTC RUN echo $TZ > /etc/timezone && \ ln -fs /usr/share/zoneinfo/$TZ /etc/localtime # Install required utilities RUN apt update \ && apt install -y --no-install-recommends \ build-essential \ cmake \ git \ gnupg2 \ nano \ python3-dbg \ python3-setuptools \ python3-vcstool \ ruby \ sudo \ && rm -rf /var/lib/apt/lists/* \ && apt clean -qq # Set up locale RUN sudo apt update && sudo apt install locales \ && sudo locale-gen en_US en_US.UTF-8 \ && sudo update-locale LC_ALL=en_US.UTF-8 LANG=en_US.UTF-8 ARG ROSDIST=humble # Install example ROS package RUN apt update \ && apt install -y --no-install-recommends \ ros-${ROSDIST}-actuator-msgs \ && rm -rf /var/lib/apt/lists/* \ && apt clean -qq # Copy over script to Docker container COPY ./run_my_system.bash / # Use your ros_entrypoint COPY ./ros_entrypoint.sh /
This script does the following:
- The
FROM
command tells Docker to begin from theros:humble-ros-base-jammy
image. - The
RUN
command executes arbitrary commands as if running them on the command line. In this case, they executeapt
to install utilities and ROS packages. We don't actually need these packages yet. They are included as an examples of packages that might be useful later.- Note that a common pattern for
RUN
commands is to chain sequences of commands together using&&
so each command is only run if the previous command succeeds. The reason for grouping commands together in this way is that environmental variables do not persist from one line of theDockerfile
to the next. Only changes that would be written to disk persist. - Conversely, we clear out temporary files after each call to
apt
to avoid writing unneeded files to the disk and cluttering the image.
- Note that a common pattern for
- The
COPY
command copies files from the host file system into the specified location in the docker image. In this case, the two files referenced do not yet exist. We will create them in the next step.
- The
By default, the ros:humble-ros-base-jammy
image we started from is configured to look for and execute the ros_entrypoint.sh
script when it is run. We will create this script and use it to call a custom script that will control our WAMV.
-
First, use a text editor to create a file called
ros_entrypoint.sh
and copy the following text into the file:#!/bin/bash set -e # setup ros environment source "/opt/ros/$ROS_DISTRO/setup.bash" /run_my_system.bash
-
Run
chmod +x ros_entrypoint.sh
to make it executable. -
Now use a text editor to create a file called
run_my_system.bash
and copy the following text into the file:#!/bin/bash # Start ROS2 daemon for discovery if not already started ros2 topic list # Send forward command RATE=1 CMD=2 echo "Sending forward command" ros2 topic pub -r ${RATE} -p 20 /wamv/thrusters/left/thrust std_msgs/msg/Float64 "{data: ${CMD}}" & ros2 topic pub -r ${RATE} -p 20 /wamv/thrusters/right/thrust std_msgs/msg/Float64 "{data: ${CMD}}"
-
Run
chmod +x run_my_system.bash
to make it executable.
We will now use the docker build
command to create an image from the Dockerfile
.
-
First, set up some useful variables, substituting the appropriate values below:
USERNAME=<dockerhub_username> IMAGE_NAME=<name_your_image> TAG=<image_version>
-
USERNAME
must match the username of your Dockerhub account. -
IMAGE_NAME
should describe your image. It will be used to find your image locally and on Dockerhub. -
TAG
can be anything, but we recommend you use it to store version information.
-
-
Build the image:
docker build --tag ${USERNAME}/${IMAGE_NAME}:${TAG} .
-
For example:
USERNAME=virtualrobotx IMAGE_NAME=vrx-competitor-example TAG=v1.2023 docker build --tag ${USERNAME}/${IMAGE_NAME}:${TAG} .
- Run your image
docker run -it ${USERNAME}/${IMAGE_NAME}:${TAG}
- This will use the image you created in the previous step to run a container.
- The container will call the
ros_entrypoint.sh
script, which will execute/run_my_system.bash
. - The
-it
option specifies that we want an interactive terminal. This is useful for our current example because it allows us to see terminal output and kill the container withCTRL+C
when we're finished. (Without this option we would need to use adocker stop
command to close the container.)
- You should see output that looks something like:
/parameter_events /rosout Sending forward command publisher: beginning loop publishing #1: std_msgs.msg.Float64(data=2.0) publisher: beginning loop publishing #1: std_msgs.msg.Float64(data=2.0)
- To verify that the script is working as expected, open a new terminal and get the container ID:
Copy the container ID in the far left column.
docker container ls
- Now we will create a second connection to the running container:
Where
docker exec -it <container_id> bash
<container_id>
is the ID you just copied. This command will open an interactive bash session into the container. - In this session, check that your script is publishing data as expected.
source /opt/ros/humble/setup.bash ros2 topic echo /wamv/thrusters/left/thrust
- You should receive
/wamv/thrusters/left/thrust
data (which is set to 2.0 in the script). - Switch back to your original terminal and hit
CTRL+C
to exit the container. - Note that this will also terminate your secondary bash session.
- Run
docker login
and enter your credentials. - Push your image:
docker push ${USERNAME}/${IMAGE_NAME}:${TAG}
- You should be able to log onto your Dockerhub account at https://hub.docker.com and see your new repository.
- If you want to keep your repository private, you can click on your repository, then click Settings, then Make Private.
- To ensure we can access and evaluate your image, you must click Collaborators and add
virtualrobotx
.
- Once you have a minimal image working, you can continue to develop it by adding commands to the
Dockerfile
and rebuilding. - For efficiency, Docker will only rerun build commands starting from the first line in the Dockerfile which has changed, so it is advantageous to put commands that are unlikely to change (or take a long time to run) toward the top of the file.
- See Docker's Best Practices for Writing Dockerfiles for many useful tips on how to write good
Dockerfiles
, as well as an extensive list of available commands.
- Because each command in a Dockerfile runs with a clean environment, commands that depend on sourcing many environment variables can be tricky.
- Commands that rely on ROS tools are an obvious example.
- The solution is generally to make sure the same run command both sets up the environment and immediately calls the command that requires it.
- For specific working examples, please see the minimal working examples provided in the
vrx-repository
and discussed in the next tutorial.
Back: Option 1: Interactive | Up: VRX Docker Image Overview | Next: Minimal Working Examples |
---|