<html><head><meta name="color-scheme" content="light dark"></head><body><pre style="word-wrap: break-word; white-space: pre-wrap;">\documentclass[onecolumn,letterpaper,11pt]{article}

%===================================================================
\input{common_latex/common_latex_packages}
\input{common_latex/common_latex_definitions}
\input{common_latex/common_latex_memo_format}
%===================================================================

\begin{document}

\begin{labcover}
\labtitle{Using MOOS-IvP with Docker}
\vspace{0.1in}
\labdate{Winter 2019}
\vspace{0.1in}
\labauth{Conlan Cesar, conlanc@csail.mit.edu}
\labauth{Department of Mechanical Engineering}
\labauth{MIT, Cambridge MA 02139}
\labtoc{small}
\end{labcover}

\wikidoc{file=Memo.Docker}
\wikidoc{auth=conlanc@csail.mit.edu}

%====================================================================
\section{Preface}
%====================================================================

All of the below should be considered a WIP. The Docker image project is
under developement, and breaking changes may happen at any time. To
avoid calamity, we recommend you avoid the trunk tagged image on DockerHub,
and instead use a specific revision. Keep a close eye here, on the MOOS-IvP
mailing lists, and on the Docker Hub / GitLab logs for changes.

%====================================================================
\section{Docker Overview}
%====================================================================

MOOS-IvP now has a pre-packaged \urlxx{Docker}{https://www.docker.com/why-docker}
image avaliable for the public. Docker is a container platform which allows
users to build, distribute, and run packaged applications in their own identical
runtime environment with all dependencies and configuration included. 
We regularly build and push Docker images to \urlxx{DockerHub}{https://hub.docker.com/r/moosivp/moos-ivp}
for public consumption. Details on how to use these images are below.

\pskip

We package images nightly on a public Git / CI service GitLab,
you can see the latest build's status \urlxx{here}{https://gitlab.com/moos-ivp/moosdocker/pipelines/latest}.
If the build succeeds and tests pass, it will deploy the generated image to DockerHub.
Should you be interested in the details of the process, all of the Dockerfile(s) and CI steps
are avaliable online at \urlx{https://gitlab.com/moos-ivp/moosdocker}.

%\mvar- moos var green \bvar - behavior parameter \cmd linux stuff \pvar

%=====================================================================
%\subsection{Motivation}

%=====================================================================
\section{Using Docker and MOOS}

%=====================================================================
\subsection{Installing Docker}

The process to install Docker is dependent on which system you run it on. However, 
we've included some steps to get you started.

\pskip

On Linux systems (Ubuntu, Raspbian, Fedora, etc) you should install Docker CE. The instructions for
Ubuntu are \urlxx{here}{https://docs.docker.com/install/linux/docker-ce/ubuntu/}, and
other OSes are in the sidebar on that page. If your workplace has a Docker EE subscription
you can use that as well, however it is not necessary, and we do not use it ourselves.

\pskip

On MacOS and Windows, you should install Docker Desktop. The official instructions for Docker Desktop
are \urlxx{here}{https://www.docker.com/products/docker-desktop}. It may ask you to make an account,
though this is not necessary. Direct download links are below:

\begin{packed_itemize}
  \item MacOS DMG: \urlx{https://download.docker.com/mac/stable/Docker.dmg}
  \item Windows: \urlx{https://download.docker.com/win/stable/Docker Desktop Installer.exe}
\end{packed_itemize}

Once you have installed Docker, you can test to make sure it is working by running the below command.
If running the command results in an error, fix that before proceeding below.

\vspace{0.1in}
\begin{consoleverb}
  $ docker ps
  CONTAINER ID   IMAGE       COMMAND     CREATED     STATUS      PORTS      NAMES
\end{consoleverb}
\vspace{0.1in}

%=====================================================================
\subsection{Running an Alpha Mission}

Currently, any mission that can be run outside docker can be run inside. In this example,
we will run a simple alpha mission, \mvar{s1-alpha-auto}. We use this mission because
(without extra configuration), GUI applications can not be run inside containers (this means no pMarineViewer).
The mission will simulate a vehicle, and after two seconds, deploy it in the same manor as \mvar{s1-alpha}.

\pskip

The first step is to pull the MOOS image from DockerHub. 
You can find the latest avaliable tag from this page \urlxx{tag}{https://hub.docker.com/r/moosivp/moos-ivp/tags}, 
which as of the writing of this document is r8910, but will likely be
different when you start using docker.
%Let's use that tag for our testing (though you should be able to use any older or newer tag if you'd like). 

\vspace{0.1in}
\begin{consoleverb}
  $ docker pull moosivp/moos-ivp:r8910
  r8910: Pulling from moos-ivp/moosivp
  871f7f65f017: Downloading
  1dd50c4b99cb: Download Complete
  5bcbdf508448: Waiting
    etc...
\end{consoleverb}
\vspace{0.1in}

\pskip

Now that the local image is on your computer, you can run a mission from it. This example will run the \mvar{s1-alpha-auto} mission be will 
run until you tell it to stop like any other mission. Then the instance you ran will be deleted, leaving the logs on your local system. 
Should you not want the logs, omit the \cmd{--mount} flag and its arguments.

\begin{packed_itemize}
  \item `--rm` removes the instance after it has finished running (once you press 'q' to end the mission)
  \item `-it` means [i]nteractive [t]ty, allowing you to interact with the mission window
  \item `--name` allows you to more easily refer to the instance from elsewhere (scripts, other terminals, etc.)
  \item `--mount` binds the local folder into the container, allowing you to keep the logs after the instance is ended
\end{packed_itemize}

\vspace{0.1in}
\begin{consoleverb}
  $ docker run --rm -it --name=optional-instance-name-here \
    --mount source="$(pwd)/logs",target=/home/moos/moos-ivp/ivp/missions/s1_alpha_auto/logs,type=bind \
     moosivp/moos-ivp:r8910 moos-ivp/ivp/missions/s1_alpha_auto/launch.sh --nogui

  Launching alpha MOOS Community. WARP is 1
  uMAC launching as uMAC_1728

  uMAC_1728 thread spawned
  starting uMAC_1728 thread
  1575674613.9657 140590251505408-                           disabling nagle

  -------------- moos connect ----------------------
    contacting a MOOS server localhost:9005 -  try 00001
    Handshaking as uMAC_1728              [ok]
    DB reports async support is           [on]
    DB is running on                      2d95d6368ea3
    Timing skew estimation is             [off] (not needed)
  --------------------------------------------------

  uMAC_1728 is Running:
   |-Baseline AppTick   @ 5.0 Hz
   |--Comms is Full Duplex and Asynchronous
   -Iterate Mode 0 :
     |-Regular iterate and message delivery at 5 Hz

  etc...

\end{consoleverb}
\vspace{0.1in}

\pskip

\subsection{Attaching your mission to the Outside World}

If you'd like to view a graphical representation of the vehicle, there are
several methods. One is X11 forwarding, which works on any system with an
X11 Server running (ie. Most Linux Distros, MacOS with XQuarts). However,
the instructions heavily depend on the system you're running. If you don't
have pMarineViewer or the mission you are running on your local machine, 
this is the avenue you should take. You can Google how to set up
Docker with X11 forwarding, and using the moos-ivp GUI tag you shouldn't
have difficulty viewing any GUI apps running inside your container.

\pskip

Another way to attach to the inside is by having pMarnineViewer running on
your host system, attached to a MOOS community inside a docker container.
You will however need the mission files on your host system.
To do this, spin up a mission like above, except run add the argument
\cmd{-p9000:9000}. This makes the MOOSDB avaliable to your host computer. 
Then, run pMarineViewer, and point it to your .moos file.

\pskip

To run the alpha mission, run this command anywhere:

\vspace{0.1in}
\begin{consoleverb}
  $ docker run --rm -it --name=my-auto-alpha-mission -p9000:9000 \
     moosivp/moos-ivp:8910 moos-ivp/ivp/missions/s1_alpha_auto/launch.sh --nogui
\end{consoleverb}
\vspace{0.1in}

Then in another terminal window, cd into the mission directory and run
\cmd{`pMarineViewer alpha.moos`}. pMarineViewer will then appear and 
show the mission running inside your container.

\pskip

There you have it! You have run your very first docker mission inside of moos. 
There is lots more you can do with moos-in-docker, such as connecting together multiple
images / vehicles, or running many containers in the background, but once you get more
familiar with using Docker you will find that isn't too hard a task.


%=====================================================================
%\subsection{Using your own Tree}


\end{document}

</pre></body></html>