First Time Installation

2.57. First Time Installation#

This guide covers how to install ROS2 via Docker.

If you are already familiar with using Docker, the steps are as follows:

  1. Install Docker

  2. Build a docker image using the provided Dockerfile (docker build -f ros2_jazzy.dockerfile -t ros2_jazzy .)

  3. Run a container from the image

  4. Connect to the container through VSCode

  5. Confirm ROS works by running the turtlesim_node program.

If you are not familiar with Docker, detailed steps can be found bellow.

2.58. Step 0: Installing Prerequisites#

2.58.1. Windows#

If you are using Windows, you must also install WSL2 or HyperV. For this tutorial, we use and recommend WSL2. When prompted by the Docker Desktop installer in step 1, prefer WSL2 over HyperV.

WSL2 can be installed by running: wsl --install in an administrator terminal. An administrator terminal can be accessed by searching for “Terminal” in the Windows search bar, right clicking on the icon, and then selecting “Run as administrator”.

For more info on installing WSL2 for Docker, see this link.

2.58.2. MacOS#

Mac does not have a built in GUI server, so we need to install one. XQuartz is the server we recommend.

  1. Install XQuartz from the link above.

  2. Under the XQuartz menu, navigate to Preferences > Security and ensure “Allow connections from network clients” is checked.

  3. Restart XQuartz

  4. In the XQuartz Terminal that open, run: xhost + localhost

NOTE

Step 4 must be run everytime you restart XQuartz

For more info, see this link.

2.58.3. Linux#

There are no specific prerequisites for Linux.

2.58.4. Step 1: Installing Docker Desktop#

Docker can be be downloaded via Docker Desktop on Windows, Mac, and Linux.

On Linux and Mac, a VM is automatically set up when installing Docker Desktop.

2.58.5. Step 2: Running the Dockerfile#

Docker uses Dockerfiles to create images, which are essentially templates for Docker containers.

The dockerfiles in this directory will set up a blank ROS2 environment for you to work in. This tutorial was made using ros2_jazzy.dockerfile, but it may work for other ROS2 distributions.

To build your image, navigate to the folder where the Dockerfile is stored in the terminal.

If you are unfamiliar with the terminal, and right click on the empty space besides the files. Then, click “Open in Terminal”.

Once you have a terminal in the same directory as the Dockerfile, enter the following command to build the Dockerfile:

docker build -f ros2_jazzy.dockerfile -t ros2_jazzy .

Don’t forget the . at the end!

The -f flag specifies a file to use, and here we use the ros2_jazzy.dockerfile. Other tutorials may require specific images, so you may need different dockerfiles for those tutorials. The -t flag specifies a name, so we named our container ros2_jazzy.

Now, we wait for the image to build.

NOTE

If the Docker engine is not running, you will get an error when you try to use Docker commands. To launch the Docker engine, simply open Docker Desktop.

2.58.6. Step 3: Running the Container#

Now that we have an image, we can run it as a container. This is essentially a lightweight VM where your ROS systems will run.

You should see your image under the images tab of Docker Desktop. Press the play button under actions, and click the blue “Run” when the pop up appears. You will see your container launched, and the status on the top right should say “Running.”

2.58.7. Step 4: Connecting to the Container#

In order to connect to the Docker container, you must use a terminal.

One way to do this is through the VSCode Docker extension and Dev Containers extension to get a workspace inside the Docker environment. This will allow you to view and edit the files more easily, as well as easily create multiple terminal windows. You can install VSCode extensions using the Extensions tab in the sidebar (the four squares)

To use the VSCode Docker Extension, navigate to the Docker tab in the sidebar, locate your running container, right click on it, and select “Attach Visual Studio Code.”

Now, you have a workspace inside the Docker container! In ROS, you will need a lot of terminals open at once. You can create a terminal using the Terminal menu in the top right, and drag it to the main window for easier use.

Alternatively, you can attach any other shell to the docker container by opening a terminal and running:

docker exec -it <container_name> bash

Note that VSCode automatically configures the container for GUI when you attach it to the container. If you do not connect a VSCode workspace first, you must properly configure the DISPLAY environment variable yourself.

2.58.8. Step 5: Testing#

To test, we use the first steps of this tutorial. All of the installation is done in the docker image, so all we need to do is:

  1. Open 2 different terminals

  2. In one terminal, run: ros2 run turtlesim turtlesim_node.

  3. In another terminal, run: ros2 run turtlesim turtle_teleop_key

If needed, you may put the turtlesim_node terminal behind the turtle_teleop_key terminal, but do not close it. Then, you can move vscode to take up half your screen, and have the turtlesim on the other side.

Congrats! ROS2 is now installed in a docker container.

2.59. Launching an Existing Container#

Containers keep all of their files with them. If yo want to access your project that you kept in a container, you should open the same container instead of generating a new one!

To do this, simply go to the “Containers” tab in Docker Desktop, and click the Run button corresponding to your old container. Then, you can continue from step 4.

Contents