ROS Development in Docker on Mac and Windows

ROS development has many dependencies. It is challenging to set it up. Docker simplifies this.


Port 22: SSH Warning

When ssh-ing into a virtual robot where the host machine uses port 22, you can run into issues where the host machine's default port is 22 too. To work around this, specify --net=host for your host machine to a different port than 22.

For ROS 1, it requires Ubuntu Linux and for ROS 2, while it allows Mac, Windows and others, the underlying libraries are still not available on all architectures and setup is complex. By using Docker, where the setup can be frozen and reproducible, you can boot a ROS environment in a second.

Below is a simple docker setup allowing you to do ROS 1 or 2 development on a Mac and PC using your standard code editors out of the box on your normal hard drive with a ROS docker image, rather than needing to build and keep an Ubuntu computer or VM running.

1. First, download and run the core docker image

At its core is a docker image of Ubuntu 18.04, ROS 1, ROS 2, general apt development packages and example ROS 1 and 2 workspaces at ~/code/ros*.

docker pull frdmrobotics/playground

docker run -it frdmrobotics/playground

You are now in a fully running Ubuntu console with ROS installed. You can ctrl+c to exit the console and go back to your dev computer. When you do, the container will exit.


Bring your own Docker image

You can use any docker image you like, such as ros:melodic or a custom one for your development. the frdmrobotics/playground image is a good starting point as it has most of your dependencies for development already incorporated.

2. Keep it alive after we close the terminal

We actually want the container to stay around for many days as we develop - where we can connect to it with multiple terminals. Therefore, we should start it in detached mode and give it a known name of robot_env.

docker run -dt --name robot_env --restart unless-stopped frdmrobotics/playground

This will let us connect and reconnect to it with:

docker exec -it robot_env bash

On multiple terminals and even shut them all down then boot a new one and our environment will still be there. You can try executing the above in 2 different terminals and you will be logged into the container twice. This is exceedingly useful for multi-terminal usage with ROS. (Note, you can also use tmux and screen for this in one terminal.

Now, let's shut down this version of the container so we can create a better one.

docker stop robot_env && docker rm robot_env

3. Mount your development directory

To have all our code live, we need to mount our live code directory into the docker (Not copy it). We do this by adding -v then the current directory and the location we want to mount it. Remember to CD into your code directory first. We are going to put them in /root/workspace, but you can change it to /root/catkin_ws or another directory.

cd my_workspace_directory

docker run -dt --name robot_env --restart unless-stopped -v `pwd`:/root/workspace frdmrobotics/playground 

If you are using Windows, please replace pwd with %cd% in the above command.

4. Now, log in and start editing!

Ok, now you are ready to start coding! Execute the command to launch a terminal session in your robot_env.

docker exec -it robot_env bash

Now that you are in, go to your code work space, source ROS and install any dependency packages you will need for your projects.

cd /root/workspace

You will see all of your code.

Now go to your editor of choice and edit a file, cat the file and you will see the changes immediately, as all your code is directly mounted as files in the docker.


Because you have mounted your code directory into the container, your files will immediately update in the container and can be used immediately

You can then source ROS, compile your workspace and run your project.

cd /root/workspace

source /opt/ros/melodic/setup.bash

rosdep install --from-paths src --ignore-src -r -y


source devel/setup.bash

roslaunch mypackage file.launch

5. Install the Freedom Agent

Now that you have your docker running, you can curl down the install script for a device on the Freedom platform and it will install any final dependencies and then appear in the Freedom console. You will have the ability to do remote SSH and every other feature of Freedom.

When you create a new container and reset things, just remember to reinstall your agent and you are good to go.

6. Reuse my last container

If the container you were using is no longer running (because it was manually stopped, docker was restarted or the computer rebooted), you can always start it back again:

docker start robot_env

Some other helpful commands to check if the container exists or is alive:

docker container ls -a
docker ps

7. Reset the container to start over

If you ever want to wipe your container and start over, all you have to do is remove the old one and re-launch. All your code in the code directory is safe.

# Shut down and remove your old docker container
docker stop robot_env && docker rm robot_env

# Now, just rerun to create a new docker container of the same name
docker run -d -t --name robot_env --restart unless-stopped -v `pwd`:/root/workspace frdmrobotics/playground 

8. Always create setup script

Whenever you have a new repo, module, package, etc you should create a setup script for your ROS, python, UDEV and other dependencies so you can run one repeatable command and it will work. It takes a bit of time to tune this and account for the differences in device availability on Mac/Windows/Linux, but really helps when bringing a new person into the project.

Wrap up and code!

The biggest recommendation we can give is to build an easily repeatable and stable bring-up of your full robot both in the real world and in a “decently accurate” simulator which allows you and your team to do development efficiently.

There are many extensions of this capability.

  • Use Gazebo with GZWeb through your browser in docker
  • Wrap you final code in a docker image for deployment
  • Share your environments across the team easily

Once you get your system up and working, I would definitely recommend checking out Freedom’s ROS integrations - you can download and try them for free - which give you cloud logging, remote control and teleop, ssh, remote ROS launch/shutdown and many other tools to help accelerate your development.