## For instruction on writing tutorials
## http://www.ros.org/wiki/WritingTutorials
####################################
##FILL ME IN
####################################
## for a custom note with links:
## note =
## for the canned note of "This tutorial assumes that you have completed the previous tutorials:" just add the links
## note.0=
## descriptive title for the tutorial
## title = Getting started with ROS and Docker
## multi-line description to be displayed in search
## description = This tutorial walks you through installing Docker and spinning up your first ROS container on your computer.
## the next tutorial description (optional)
## next =
## links to next tutorial (optional)
## next.0.link=
## next.1.link=
## what level user is this tutorial for
## level= BeginnerCategory
## keywords = ROS, Docker
####################################
<<IncludeCSTemplate(TutorialCSHeaderTemplate)>>

For reasons you'll come to understand in a bit, a host installation of ROS is not required for most of these tutorials unless otherwise specified. To quickly grasp how this is possible with Docker, it's recommended you [[https://www.docker.com/tryit/|try it]] out with the online tutorial.

<<TableOfContents(4)>>

= Installing Docker =
Before starting this tutorial please complete installation as described in [[https://docs.docker.com/installation/|Docker's installation instructions]]. Installation instructions are available for multiple operating systems including Ubuntu, Mac OS x, Debian, Fedora and even Microsoft Windows.

You may also want add your user to the docker group to avoid having to use sudo permissions when you use the docker command, as also noted further into Docker's installation instructions.

= Using ROS images =

== Pulling ROS images ==
Now that you have Docker installed, pull down a ROS container image:
{{{
docker pull ros
}}}
This will pull the latest tagged LTS image of ROS (that is, the image named "<latest_lts>:ros") from [[https://hub.docker.com/account/signup/|Docker Hub]] onto your local host machine.

Specifically, the image name "ros" is registered with Docker's [[https://registry.hub.docker.com/_/ros/|Official ROS Repo images]]. The repo also has tag names for other versions and/or meta package levels. The tags are built from each other in the same manner as the respective [[https://github.com/ros/metapackages|ROS metapackage]] dependencies interlink, i.e. if you were to pull:
{{{
docker pull ros:noetic-robot
}}}
You would then also then locally posses the "noetic-ros-core" and "noetic-ros-base" tagged images as well.

== Running ROS containers ==
Now that you have the ROS image downloaded, you can spin up a container from it by calling:
{{{
docker run -it ros
}}}
This will move you into an interactive session with the running container. From here, it's basically as if you're in a new bash terminal separate from your host machine. Now run the roscore command and you will see ros master startup.

In a new terminal on the host machine, find the name of your new container, last container started using:
{{{
$ docker ps -l
}}}
Using the name of the container as the ID, in writing this tutorial docker happened to assign the string "nostalgic_morse", we can start additional bash session in the same container by running:
{{{
docker exec -it nostalgic_morse bash
}}}
Once inside, we'll need to setup our environment. The best way to do this is to using the entrypoint script included in the docker image:
{{{
source ros_entrypoint.sh
}}}

If you ran the `docker pull ros` command, you will have a ROS 2 installation (dashing, foxy, etc.) try:
{{{
ros2 topic list
}}}

If you pulled a ROS1 Docker container tag (noetic, kinetic, etc.) try:
{{{
roscore
}}}

== Stopping ROS containers ==
To stop containers, we merely need to stop the original processes run by `docker run` command. We can switch back to the terminal where `roscore` is running and hit ctrl-c to stop the ROS process, and then `exit` to terminate the bash shell. You can also use the docker CLI to tell the docker daemon to stop or remove the running container directly. Check the [[https://docs.docker.com/engine/reference/commandline/stop/|stop]] and [[https://docs.docker.com/engine/reference/commandline/rm/|rm]] docs here for details. 


== Video Demonstration ==

Below video makes you understand how Docker can be utilized for different ROS versions on different Operating systems.

<<Youtube(qWuudNxFGOQ)>>

## AUTOGENERATED DO NOT DELETE
## TutorialCategory
## FILL IN THE STACK TUTORIAL CATEGORY HERE