tutorials vrx_docker_interactive - osrf/vrx GitHub Wiki
In this tutorial we begin by pulling a clean ROS 2 Humble Docker image. We then manually run desired commands in a terminal to setup the system, and use docker commit
to make our changes permanent.
- This is one of two options for building a competitor image.
- The second option is described here.
- This development process is more similar to the experience of developing directly on a machine, and thus has a lower barrier of entry for first-time Docker users.
- For new Docker users, this is probably the fastest way to get started.
Follow the steps below to get a minimal version of a competitor image up and running:
- Open a terminal and execute the following:
The run command does several things:
docker run --name my_container -it ros:humble-ros-base-jammy
- It will check whether the
ros:humble-ros-base-jammy
image exists locally. - If not, it will download the image from DockerHub. (This may take a few minutes.)
- Once the download is complete, it will run the image and create a container, which we've called
my_container
. - The
-it
options specify that we want an "interactive" session and a "terminal." - When the command is finished it will open an interactive Bash session for you to run commands.
- Note that your terminal prompt will change to:
where the container ID is the hash assigned to the container by Docker.
root@<container_id>:/#
- It will check whether the
This Bash session is very barebones. It does not have a text editor yet, so we will install one now.
- In the Bash session you just opened run
apt update && apt install -y nano
or replacenano
with your text editor of choice. - Note that running this command in the session installs nano inside your container, not on your host system.
- Proceed similarly to add any other development tools you need.
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 edit this script so it calls the run_my_system.bash
script, which we will provide.
-
Use the text editor to edit
ros_entrypoint.sh
. For example:nano /ros_entrypoint.sh
-
Replace all the text with the following:
#!/bin/bash set -e # setup ros environment source "/opt/ros/$ROS_DISTRO/setup.bash" /run_my_system.bash
-
Save your changes and exit.
Now that we've told the entrypoint script to call run_my_system.bash
, we need to add that script to the system.
- Open the new script in a text editor:
nano /run_my_system.bash
- Copy the following text into the blank 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.
- Run
to execute the script in the background.
/run_my_system.bash &
- You should see the ros core service start up, and the output of the echo message, "Sending forward command", from the script you just created.
- Hit enter to get back to a command prompt.
- Check that your script is publishing data as expected.
ros2 topic echo /wamv/thrusters/left/thrust
- You should receive
/wamv/thrusters/left/thrust
data (which is set to 2.0 in the script).
- Everything you have done up until this point has altered the Docker container, which is running in system memory.
- We now need to commit these changes back to a Docker image so they will be persistent.
To do this:
- Run
exit
to leave this container. Your prompt will change to indicate you are back on your host computer. - Run
to list all containers. You should see your container
docker ps -a
my_container
. TheSTATUS
should indicate that the container exited recently. - Copy the
Container ID
ofmy_container
from the far left column. - Set up some useful variables, substituting the appropriate values below:
AUTHOR_NAME=<your_name> CONTAINER_ID=<container_id> USERNAME=<dockerhub_username> IMAGE_NAME=<name_your_image> TAG=<image_version>
-
AUTHOR_NAME
is your name. -
USERNAME
must match the username of your Dockerhub account. -
CONTAINER_ID
must be the ID you copied in the previous step. -
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.
-
- Run
docker commit -m "<Write your commit message here.>" -a ${AUTHOR_NAME} ${CONTAINER_ID} ${USERNAME}/${IMAGE_NAME}:${TAG}
- For example:
AUTHOR_NAME=Michael_McCarrin CONTAINER_ID=a0e1e92cb6a5 USERNAME=virtualrobotx IMAGE_NAME=vrx-competitor-example TAG=v2.2023 docker commit -m "Start from ros-humble-base and add run_my_system.bash" -a ${AUTHOR_NAME} ${CONTAINER_ID} ${USERNAME}/${IMAGE_NAME}:${TAG}
- 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 can click Collaborators and add
virtualrobotx
.
Once you have a minimal image working, you can continue to develop it by repeating the process above. Be sure to use docker commit
and docker push
to save your changes periodically and push them to the Dockerhub repository.
As you develop your image, you may need to add files from your host system. There are several ways to do this, but one convenient method is to use the docker cp
command.
- While your container is running, open a new terminal, and navigate to the directory of the file you want to copy.
- Run
docker cp <your_local_file> <container_name>:/path/to/file/in/container/
- For example, if you want to copy
script.py
to/root/scripts
inside your container namedmy_container
, run:docker cp script.py my_container:/root/scripts
- For full documentation of the
docker cp
command, see https://docs.docker.com/engine/reference/commandline/cp/
Back: Image Creation Overview | Up: VRX Docker Image Overview | Next: Option 2: Scripted |
---|