<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}

%===================================================================
% Include common packages, environments, counters etc
\input{common_latex/common_latex_packages}
\input{common_latex/common_latex_lab_format}
\input{common_latex/common_latex_definitions}
%===================================================================
\setcounter{tocdepth}{2}
%===================================================================

\begin{document}
\wikidoc{file=Lab.DockerSetup}
\wikidoc{auth=mikerb@mit.edu}
\helplevelsubsec

%===================================================================
% Build the Cover Page in an environment style easy for wiki parsing
\begin{labcover}
\labtitle{Docker Lab 1 - Overview and Setup}
\vspace{0.2in}
\labcourse{Pavlab: Getting Started with Docker Containers}
\vspace{0.5in}
\labpng{0.25}{figures/docker_icon.png}
\vspace{0.25in}
\labdate{May 17th , 2020}
\vspace{0.23in}
\labauth{Michael Benjamin, mikerb@mit.edu}
\labauth{Department of Mechanical Engineering}
\labauth{MIT, Cambridge MA 02139}
\labtoc{small}
\labtocdepth{2}
\end{labcover}

%===================================================================
% Add a blank page so first body page is on the right when doubleside
\blankpage

%===================================================================
% Begin the body of the text
%===================================================================
\section{Overview and Objectives}
%===================================================================

\begin{labinfo}
%\labinfoheader{Topics:}
\begin{packed_itemize}[2]
\item Goal - Get Docker installed on your local computer
\item Goal - Review the notions of Images and Containers
\item Goal - Obtain your first Docker images
\item Goal - Start your first Docker containers
\item Goal - Become comfortable knowing the state of local images and containers
\end{packed_itemize}
\end{labinfo}

%=======================================================================
\section{Get Docker on Your Local Computer}
%=======================================================================

The first step is to dowload and install Docker on your local computer. For now
our steps will be from the perspective of a MacOS user. The software is obtained
directly from the \var{docker.com} website, not the Mac App Store. You can do a
web search on \var{"mac os docker"}, or use the URL that I came to  with my search:

\vspace{0.2in}
\urlx{https://hub.docker.com/editions/community/docker-ce-desktop-mac}
\vspace{0.2in}

\noindent
This should bring you to a page that looks something like the one
below. Just click on the Get Docker button and the download should
begin immediately to your Downloads folder.

\vspace{0.15in}
\begin{figure}[H]
  \centering 
  \includegraphics[width=0.75\textwidth]{figures/get_docker.png}
  \caption{{\bf Getting Docker:} The first page for getting Docker on the
    Mac should looking something like this (as it looks May 2020).}
\label{fig_get_docker}
\end{figure}
\vspace{0.1in}

\noindent
The downloaded file should be called \var{Docker.dmg} in your
\var{~/Downloads} folder.  Just click on it or type \var{"open
  Docker.dmg"} on the command line from within the folder. After a few
seconds it will prompt you to install Docker. Move the created
Docker application into the sytem Applications folder, by dragging and
dropping the Docker icon in a window like:

\vspace{0.15in}
\begin{figure}[H]
  \centering 
  \includegraphics[width=0.45\textwidth]{figures/docker_install.png}
  \caption{{\bf Installing Docker:} The installation of Docker is done in
    the familiar pattern of dragging and dropping the Docker icon into the
    Applications folder.}
\label{fig_install_docker}
\end{figure}
\vspace{0.1in}

\noindent
Since this move is a change to the system Applications folder
typically, it requires system Admin privileges and you should see the
below dialog window informing you that you need to enter your
password. Click OK, and then enter your password.

\vspace{0.15in}
\begin{figure}[H]
  \centering 
  \includegraphics[width=0.45\textwidth]{figures/docker_permissions.png}
  \caption{{\bf Install permission:} You will be informed that you need to
    enter your password to approve the addition of the Docker application to
    the folder of system Applications.}
\label{fig_docker_permissions}
\end{figure}
\vspace{0.1in}

\noindent
Once this is done, Docker is installed. The executable is located at
\var{/Applications/Docker.app/}. It can be launched by opening that folder and
double-clicking it. In addition to the starting splash which looks something
like Figure \ref{fig_docker_start}, a small Docker icon will appear in the top
of your menu bar. It is the leftmost icon in the example below:

\vspace{0.15in}
\begin{figure}[H]
  \centering 
  \includegraphics[width=0.35\textwidth]{figures/docker_header.png}
  \caption{{\bf Docker Menu Icon:} When Docker is running, the icon can
    be seen in the top of Mac menu bar.}
  \label{fig_docker_icon}
\end{figure}
\vspace{0.15in}

\noindent
The above icon will be present as long as Docker is running. Docker,
by default, is configured to start automatically upon login. So you
should expect to see this icon on your top menu bar hereafter. The
very first time you launch Docker, it will present you with the
typical Mac dialog box that informs you that Docker is "an application
downloaded from the Internet. Are you sure you want to open it?"
After you click "Open", you will see a screen similar the one
below.


\vspace{0.15in}
\begin{figure}[H]
  \centering 
  \includegraphics[width=0.45\textwidth]{figures/docker_first_launch.png}
  \caption{{\bf Launching Docker:} The first page for getting Docker on the
    Mac should looking something like this (as it looks May 2020).}
\label{fig_docker_start}
\end{figure}
\vspace{0.15in}

\noindent
This screen offers a short tuturial in getting your first Docker image
and running your first container. Go ahead and go through it if you'd
like. At this point you can consider Docker to be installed. If at any
point you wish to continue training yourself on Docker, the Docker
icon at the top of your window (Figure \ref{fig_docker_icon}) is a
pull-down menu, and by selecting \var{Learn} you will come back to the
above tutorial, or you can select \var{Documentation} and find another
entry point for learning.

\vspace{0.15in}
\begin{figure}[H]
  \centering 
  \includegraphics[width=0.20\textwidth]{figures/docker_documentation.png}
  \caption{{\bf Docker Training:} The Docker icon is a pull-down menu with
    options for training yourself. Select \vvar{Learn} or \vvar{Documentation}.}
\label{fig_docker_learn}
\end{figure}
\vspace{0.15in}


\noindent
As we discuss images and containers in the next section, we will borrow from
some of the steps found in the \var{Documentation} link in the above pull-down
menu. 


%=======================================================================
\newpage \section{Images and Containers}
%=======================================================================

The two immediately key notions to consider and differentiate between is the
notion of an {\em image} and a {\em container}. The primary two things to
keep in mind are:

\vspace{0.1in}
\begin{packed_itemize}
\item An {\em image}, once created, is immmutable, read-only.
\item A {\em container} is an instance of an image and has a writable component.
\end{packed_itemize}
\vspace{0.15in}

\noindent
A container, once it has been created, i.e., instantiated from an image, may be
in either the {\em running} or {\em stopped state}. Several containers can be
created from the same initial image:

\vspace{0.15in}
\begin{figure}[H]
  \centering 
  \includegraphics[width=0.75\textwidth]{figures/imgcon.png}
  \caption{{\bf Images and Containers:} An unlimited number of containers
    can be instantiated from the same image. Created containers may be either
    in the {\em stopped} or {\em running} state. }
\label{fig_imgcon}
\end{figure}




%=======================================================================
\newpage \section{Obtaining and Launching a First Image and Container}
%=======================================================================

The Docker installation includes a command line interface (CLI) tool, accessible
from the terminal window:

\vspace{0.15in}
\begin{consoleverb}
$ which docker
/usr/local/bin/docker  
\end{consoleverb}
\vspace{0.15in}

\noindent
If you do not see the above result, check your shell path to ensure it
includes \var{/usr/local/bin/}. This is a common component of most
bash shell path environments. Assuming you have the \cmd{docker} command,
remember you can always quickly see a lot of information about this command
by running \cmd{docker --help}.


\vspace{0.15in}

\noindent
Next we'll use the simple example used on the Docker Documentation page to
retrieve our first Image and run our first container.

\vspace{0.15in}
\begin{consoleverb}
$ docker run hello-world
\end{consoleverb}
\vspace{0.15in}

\noindent
Take a moment to read the output of this command as it outputs more to the
screen than just the \var{"hello world"} message. The image that is being
instantiated here is called \var{hello-world}. Prior to invoking the above
command, this image is not on your system. The \cmd{docker run} command expects
an image name to be passed as an argument, and if it does not find this image
on your local computer, it will try to download it directly from Docker Hub.
More to be said about Docker Hub later, but for now just consider it to be
a public repository of published images that can be downloaded.

%=======================================================================
\subsection{Containers and Images on Your Local Computer}

In the simple example above, the hello-world image was downloaded to your local
computer prior to launching the container. The list of images on your local
computer can be viewed with the \cmd{docker images} command:

\vspace{0.1in}
\begin{consoleverb}
$ docker images
REPOSITORY          TAG         IMAGE ID         CREATED         SIZE
hello-world         latest      bf756fb1ae65     2 minutes ago   13.3kB
\end{consoleverb}
\vspace{0.1in}

\noindent
Note that each image has a unique ID. This 12 character ID is actually an abbreviated
version of the full 64 character (128 bit) ID. This ID is known as a "Universally
Unique Identifier or UUID, [4]. If you were to use the \cmd{--no-trunc} option with
the above \cmd{docker images} command, the full 128 character ID would be given,
and you can see that the shortened version is just the first 12 characters:

\vspace{0.1in}
\begin{consoleverb}
 sha256:bf756fb1ae65adf866bd8c456593cd24beb6a0a061dedf42b26a993176745f6b
\end{consoleverb}
\vspace{0.1in}


\noindent
Likewise the list of containers on your local computer can be viewed
with the \cmd{docker container ls -a} command: 

\vspace{0.1in}
\begin{consoleverb}
$ docker container ls -a
CONTAINER ID     IMAGE         COMMAND    CREATED         STATUS                 NAMES
eeaafc19c3f3     hello-world   "/hello"   2 minutes ago   Exited (0) 2 mins ago  hardcore_jake
\end{consoleverb}
\vspace{0.1in}

\noindent
Notice containers also have a unique ID. This ID is of course different from the
image ID from which it came, since an unlimited of containers can be created from
a single image. 

\vspace{0.15in}
\noindent
Notice the container "name" seems rather random,
"hardcore\_jake". When the container is created, all transactions on
the container can be done by referencing the Container ID,
\var{eeaafc19c3f3} in this case. Docker creates a randomly generated
more human-readble name in addition to the unique Container ID. You can instead
choose the name when the container is created. Try the following run command instead:

\vspace{0.15in}
\begin{consoleverb}
$ docker run --name testing123 hello-world
\end{consoleverb}
\vspace{0.15in}

\noindent
Then notice the additional container:

\vspace{0.1in}
\begin{consoleverb}
$ docker container ls -a
CONTAINER ID     IMAGE         COMMAND    CREATED         STATUS                 NAMES
eeaafc19c3f3     hello-world   "/hello"   2 minutes ago   Exited (0) 2 mins ago  hardcore_jake
4425c361b098     hello-world   "/hello"   3 seconds ago   Exited (0) 2 secs ago  testing123
\end{consoleverb}


%=======================================================================
\subsection{Where are Containers and Images on Your Local Hard Drive}

From the example above, clearly at least two containers and one image have been loaded
onto your local hard drive. The image, \var{hello-world}, was downloaded automatically from
Docker Hub as part of the \cmd{docker run} command. And the two containers were created
from the image on each successive call to \cmd{docker run}. How do these objects map to
file(s) on your local hard drive?

\vspace{0.1in}
\noindent
Docker keeps all images and containers in one single file called \var{Docker.raw}. On the Mac,
this is in the folder \var{~/Library/Containers/com.docker.docker/Data/vms/0/data}. Note that if you
perform an \cmd{ls -hl} on this file, it appears to be very large. For example it shows as
\var{60GB} on my system. However, runing \cmd{ls -ks}, which shows the size actually used,
this file is much smaller, about \var{4GB} on my system for example.

\vspace{0.1in}
\noindent
To remove containers or images, there are separate \cmd{docker} tools for this, and discussed
next.

%=======================================================================
\subsection{Removing Containers and Images}

I often find it comforting to know how to return to my starting state. Now that an image
has been downloaded to my computer and a couple containers have been created, how can they
be removed? One thing to note right away is that Docker tries to prevent you from deleting
images from which there are currently existing containers. We'll get back to that in a
moment. First, let's delete the two containers on our system. The \cmd{docker container rm}
command takes one argument, the Container ID.

\vspace{0.1in}
\begin{consoleverb}
$ docker container ls -a
CONTAINER ID     IMAGE         COMMAND    CREATED         STATUS                 NAMES
eeaafc19c3f3     hello-world   "/hello"   2 minutes ago   Exited (0) 2 mins ago  hardcore_jake
4425c361b098     hello-world   "/hello"   3 seconds ago   Exited (0) 2 secs ago  testing123

$ docker container rm eeaafc19c3f3
$ docker container ls -a
CONTAINER ID     IMAGE         COMMAND    CREATED         STATUS                 NAMES
4425c361b098     hello-world   "/hello"   3 seconds ago   Exited (0) 2 secs ago  testing123

$ docker container rm 4425c361b098
$ docker container ls -a
CONTAINER ID     IMAGE         COMMAND    CREATED         STATUS                 NAMES
\end{consoleverb}
\vspace{0.1in}

\noindent
Removing images is similar, and is done with the \cmd{docker image rm} command, passing
it the Image ID:

\vspace{0.1in}
\begin{consoleverb}
$ docker images
REPOSITORY           TAG       IMAGE ID          CREATED          SIZE
hello-world          latest    bf756fb1ae65      2 days ago       13.3kB

$ docker image rm bf756fb1ae65 
$ docker images
REPOSITORY           TAG       IMAGE ID          CREATED          SIZE
\end{consoleverb}
\vspace{0.1in}


\large

\noindent
{\bf URL References}
\footnotesize

\noindent
[1] \urlx{https://www.instructables.com/id/Add-text-to-images-with-Linux-convert-command}

\noindent
[2] \urlx{https://medium.com/@sh.tsang/docker-tutorial-2-pulling-image-b58326448717}

\noindent
[3] \urlx{https://stackify.com/docker-build-a-beginners-guide-to-building-docker-images}

\noindent
[4] \urlx{https://en.wikipedia.org/wiki/Universally\_unique\_identifier}

\end{document}

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