tutorials vrx_docker_interactive

Option 1: Build interactively using docker commit

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.

Build a Minimal Working Image

Follow the steps below to get a minimal version of a competitor image up and running:

Step 1: Get a clean ROS Humble Docker image

• Open a terminal and execute the following:

  docker run --name my_container -it ros:humble-ros-base-jammy
  

  The run command does several things:
  • 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:

    root@<container_id>:/#
    

    where the container ID is the hash assigned to the container by Docker.

Step 2: Add development tools

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 replace nano 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.

Step 3: Edit the entrypoint script

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.

Step 4: Create run_my_system.bash

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.

Step 5: Test run_my_system.bash

• Run

  /run_my_system.bash &
  

  to execute the script in the background.
• 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.

  rostopic echo /wamv/thrusters/left_thrust_cmd
  

• You should receive /wamv/thrusters/left_thrust_cmd data (which is set to 2.0 in the script).

Step 6: Save your changes locally

• 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

  docker ps -a
  

  to list all containers. You should see your container my_container. The STATUS should indicate that the container exited recently.
• Copy the Container ID of my_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}
  

Step 7: Push your image to Dockerhub

• 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.

Optional: Make your repository private

• 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.

Developing your image further

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.

Adding local files with docker cp

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 named my_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