1.3.1. Our Docker Environment Explained

This section will not explain in depth what docker is or what the concepts are. This is assumed to be known. It it isn’t here, are two tutorials: Tutorial1 and Tutorial2

1.3.1.1. Docker tools and files in AS ROS

First, where can you find the docker related files and tools for this repository:

Everything can be found in the ./docker/ directory. There you can find:

• The Docker file for building the docker images (Dockerfile)

• Additional resources like the necessary python libraries (additional_resouces/)

• Entrypoint script for the docker containers (entrypoint_scripts/)

• Scripts for building an image and running a container (build_docker.sh and run_docker.sh)

In previous versions there existed two different images since they have different level of dependencies which cannot be met by every host system.

Since Version 2.0.2 we only have one docker image. That means that everything needed for AS ROS is always installed, even if you cannot use the camera perception since you do not own a NVIDIA GPU. This reduces the maintance and testing work. For systems without a NVIDIA GPU, one has to specify this when running the docker container. You will then be able to use all features of the Autonomous System except the camera perception.

The docker image is based on the TensorRT 21.10 ubuntu based image by NVIDIA. This image is compatible and tested with the NVIDIA 470 Drivers, CUDA 11.4.2 and TensorRT 8.2.3.

The docker image will install the python dependencies which lay under additional_resources/requirements.txt/ during the build process.

There is another python requirement file: additional_resources/requirements_startup.txt. This file is used by the entrypoint script. This file includes some source directories which should be installed on first container startup to install the python files locally. Those are for exmaple some command line interfaces like the CLI to migrate a rosbag.

The entrypoint script will initialize catkin on the first container startup and install the local python dependencies (additional_resources/requirements_startup.txt). It will also start a webserver to serve the meshes for visualization in foxglove. If specified during running the container, the mission machine module will be automatically launched by the entrypoint script to start the Autonomous System.

1.3.1.2. Setting up environment to run a docker container

Currently only Unix (Linux and Mac OS) systems are fully supported to run our docker containers. This doesn’t mean you cannot use Windows to develop or run AS ROS, we just recommend to install and use Windows Subsystem for Linux, e.g. for Windows 10 and for Windows 11

For the following tutorial it is assumed that you have a Unix system.

1. First you need to have docker installed:

   Ubuntu

   curl -fsSL https://get.docker.com -o get-docker.sh && sudo sh get-docker.sh
   

   It is recommend to execute docker post install commands for managing docker as non-root user.

   Windows 10

   1. You need to activate Windows Subystem for Linux first.

   2. You also need to activate the functionality of a virtual PC for WSL v2 and download the update package for linux kernels.

   3. Install VcXsrv to be able to use GUIs within docker containers.

   4. Make sure that the to be installed ubuntu envorinment uses WSL v2:

      wsl --set-default-version 2
      

   5. Install a terminal ubuntu environment as Windows Subsystem for Linux:

      wsl --install -d Ubuntu-20.04
      

   6. Install docker according to their documentation

      1. Use WSL 2 instead of Hyper V

   Windows 11

   1. Make sure that the to be installed ubuntu envorinment uses WSL v2:

      wsl --set-default-version 2
      

   2. Install a terminal ubuntu environment as Windows Subsystem for Linux:

      wsl --install -d Ubuntu-20.04
      

   3. Install docker according to their documentation

      1. Use WSL 2 instead of Hyper V

2. If you have a NVIDIA GPU and want to use it inside the docker container:

   Ubuntu

   1. Install the nvidia 470 drivers for you system

      1. Open the Additional Drivers tab inside the Software & Update application.

      2. Install the proprietary nvidia-driver-470 graphic driver.

   2. Download CUDA 11.4.2 and install it according to the instructions on the download website. The run file is recommended when the 470 nvidia driver is not the recommended driver for you system, since it is then easier to install.

   3. Download and install tensorrt 8.2.3. You have to create a nvidia developer account first.

   4. install the NVIDIA docker container toolkit according to the respective documentation.

   Windows

   1. Download CUDA 11.4.2 for WSL and install it according to the instructions on the download website inside the WSL.

   2. Download and install tensorrt 8.2.3 inside the WSL. You have to create a nvidia developer account first.

1.3.1.3. Build a AS ROS docker image

Since they are multiple parameters to set when one wants to build an image, it is recommended to use the written build script instead of using docker build manually.

To use it, change your directory in a console on the host system (Unix oder Windows Subsystem for Linux) to the docker directory and execute:

Ubuntu

./build_docker.sh

Windows

wsl -e bash ./build_docker.sh

The script will ask you mutliple things:

1. Whether you want to build without cache. Normally you can always use the cache. This is especially useful if you are testing a new docker image.

2. A tag that should be used for the built image. This is useful to build different images for different versions of AS ROS. Normally you can just use latest.

Afterwards the container will be built. The building can take 15-45 minutes, depending on your system power and internet connection. Latter is the most important.

The built image can then be run.

1.3.1.4. Run a AS ROS docker image

To use the built image you need to run it. This will create a docker container.

Since this will also need multiple parameters, it is recommended to use the written run scripts instaed of using docker run manually.

To use it, change your directory in a console on the host system (Unix oder Windows Subsystem for Linux) to the docker directory and execute:

Ubuntu

./run_docker.sh

Windows

wsl -e bash ./run_docker.sh

The script will ask you mutliple things:

1. Which image tag should be run. This refers to the tag you specified in the last step of the build process.

2. Whether the Autonomous System should automatically should be started on container startup. This is not recommended for development cases, since you want to manually decide which launch files to launch and which not. It is necessary for the live system on the ACU to activate this features.

3. On which type of system you want to run the docker container. You must specify the host system you are executing the the script on. You cannot use Ubuntu with NVIDIA GPU without having an NVIDIA GPU. But you can choose Ubuntu without NVIDIA GPU if you have a NVIDIA GPU.

4. To what the container should be renamed. This is especially useful if you have multiple containers for different versions. You should remember the used container name.

1.3.1.4.1. What is the run script doing?

The run scrupt calls docker run with the necessary parameters to successfully run an AS ROS image:

1. It mounts the ./src/ directory under /workspace/as_ros/src inside the docker container. Thus your written code can be used inside the container and tracked by git on the host system.

2. It mounts the ./logs/ directory to logging directory of ROS (/root/.ros/logs) inside the container. .. todo:: Check logs directory of ros and implement it in run_docker.sh

3. It mounts the ./rosbags/ directory under /workspace/as_ros/rosbags inside the docker container. Thus you can access rosbags from the host system inside the container and the other way around. All rosbags are normally recorded under this directory and all parameters, when recording a rosbag, are saved under /workspace/as_ros/rosbags/paramaters

4. It mounts the ./docs/ directory under /workspace/as_ros/docs inside the docker container, so that you can build the docs inside the docker container and access and track them on you host system.

5. It sets (ROSAUTOSTART) an environment variable whether the Autonomous System should automatically start on contaienr startup.

6. It sets the DISPLAY environment variable to the one set while executing the script, so that you can start GUIs within the container but display it on the host system (see Using GUIs inside an AS ROS container).

7. It sets an option that the docker container used the exact same network as the host system. This is normally not done, but rather explicitlty described which ports should be forwarded. This is not done for our system. This also allows that the ACU can access the socketcan interface for the CAN Bus.

8. It specified that the container should always be restart unless it is explicitlty stopped.

9. When specified that a system with GPU is used, an option is set that the container should use all available GPUs.

10. It sets a option that the container should be startet in the background (detached).

11. It renames the container to the specified container name.

1.3.1.5. Work with docker containers

You can view a list of all running containers with

docker ps

and a list of all containers with

docker ps -a

You can stop, start and restart a docker container with one of the respective commands:

docker stop <container_name_or_id>
docker start <container_name_or_id>
docker restart <container_name_or_id>

You can run a command inside a docker container with

docker exec -it <container_name_or_id> <command>

1.3.1.6. Work with an AS ROS container

To start a console inside the docker container you can execute the following from an console of you host system:

Listing 1.1 Start a console session inside the docker container

docker exec -it <container_name_or_id> bash

1.3.1.6.1. Initialization of an AS ROS container without Autostart

The first thing you have to do after running a container without autostart after the first time, is to build and source the catkin workspace inside the docker container.

1. Start a console session inside the docker container

2. Ensure all git submodules are up to date:

   git submodule update --init --recursive
   

3. Build and source the catkin workspace:

   Listing 1.2 Build and source the catkin workspace

   catkin build && source /workspace/as_ros/devel/setup.bash
   

   This may take some minutes, depending on you system power. (ACU: 30-40s, RasperryPI: 10+ min).

After changing the catkin workspace, e.g. adding another package, changing a message definition, but not changing or adding another launch file, you have to rebuild and source the catkin workspace with the described command. Normally the /workspace/as_ros/devel/setup.bash setup file needs to be sourced everytime you enter the docker container. Nowadays this happens automatically when the workspace has been built already when entering the container. So you only need to built the catkin workspace once intially and everytime you change something.

You now have a running and working AS ROS docker container. You can continue with the other steps of the development environment.

1.3.1.6.2. Validating the AS ROS container build

After building your AS ROS container, you can validate that it’s working correctly by following these steps:

1. Download a rosbag file for testing from the shared drive and put it into the rosbags directory: Rosbag test files

2. Migrate the rosbag file using the migrator tool:

   migrator rosbags/rosbag_name.bag
   

   You can check available migration options in the rosbag migrator documentation. Typically, you may want to remove visualization data, while keeping transforms. If you are not using an NVIDIA GPU, you might want to remove lidar points and images as well.

3. Run the debug pipeline to process the rosbag:

   roslaunch utilities debug_pipeline.launch input_rosbag:=/workspace/as_ros/rosbags/rosbag_name.bag mission:=6 vehicle:=rennate perception:=no mapping:=no control:=no
   

   More information about pipeline options can be found in the pipeline documentation.

4. After the pipeline completes (it will stop automatically), create a visualization file:

   visualizer rosbags/rosbag_name.bag -v rennate
   

   Additional visualization options are documented in the visualizer documentation.

5. Open the generated visualization file with Foxglove Studio to inspect the results.

If all these steps complete successfully, your AS ROS container is properly configured and ready for development.

1.3.1.6.3. Using GUIs inside an AS ROS container

To use a GUI inside an AS ROS container you have two do the following things:

Ubuntu

1. Open an console on the host system on the display you want the GUI to work on and execute:

   ./utils/xhost.sh
   

   This will allow the container to access the respective display.

2. Start the GUI.

Windows 10

VcXsrv needs to be installed, see Setting up environment to run a docker container

1. Start XLaunch from the Windows Start Menu. Choose

   1. Multiple Windows and -1 as Display Number

   2. Start no client

   3. Clipboard, Native opengl and Disable access control

2. Start the GUI

Windows 11

1. Start the GUI

If you want to use a GUI inside an AS ROS container over VNC, see Connect via VNC to ACU