add kitematic instructions and images

Author: Christopher Prener

fig/docker.png

@@ -164,9 +164,13 @@ install.packages(c("dplyr", "ggplot2", "sf", "raster", "rgdal", "rasterVis"))
 
 ## Option B: Docker
 
-[Docker](https://www.docker.com) provides developers with a means for creating "containers" that contain pre-installed software. These containers can be downloaded and used locally, allowing end-users to get software up and running quickly, particularly when a local installation of the software could be complex and time consuming. For `R` users, a Docker image can be used to create a virtual installation of `R` and RStudio that can be run through your web browser.
+[Docker](https://www.docker.com) provides developers with a means for creating interactive [containers](https://docs.docker.com/glossary/?term=container) that contain pre-installed software. A selection of pre-installed software in Docker is called an [image](https://docs.docker.com/glossary/?term=image). An image can be downloaded and used to create a local container, allowing end-users to get software up and running quickly. This is particularly useful when a local installation of the software could be complex and time consuming. For `R` users, a Docker image can be used to create a virtual installation of `R` and RStudio that can be run through your web browser.
 
-Option B involves downloading an Docker image that contains an installation of `R`, RStudio Server, all of the necessary dependencies listed above, and almost all of the `R` packages used in the geospatial lessons. You will need to install the appropriate version of Docker's Community Edition software and then download and open the `rocker/geospatial` Docker image.
+Option B involves downloading an Docker image that contains an installation of `R`, RStudio Server, all of the necessary dependencies listed above, and almost all of the `R` packages used in the geospatial lessons. You will need to install the appropriate version of Docker's Community Edition software and then download and use the `rocker/geospatial` Docker image to create a container that will allow you to use `R`, RStudio, and all the required GIS tools without installing any of them locally.
+
+Once up and running - you'll have full access to RStudio right from your browser:
+
+![](/fig/docker.png)
 
 > ## Downloading and Installing Docker Community Edition
 >
@@ -183,7 +187,7 @@ Option B involves downloading an Docker image that contains an installation of `
 > #### Download and Set-up
 > Once Docker is installed and up and running, you will need to open your computer's command line terminal. We'll use the terminal to download [`rocker/geospatial`](https://github.com/rocker-org/geospatial), a pre-made Docker image that contains an installation of `R`, RStudio Server, all of the necessary dependencies, and all but one of the `R` packages needed for this workshop.
 >
-> To get started, make sure Docker is running and then enter the following command into the terminal to download the `rocker/geospatial` image:
+> You need to have already installed Docker Community Edition (see instructions above) before proceeding. Once you have Docker downloaded and installed, make sure Docker is running and then enter the following command into the terminal to download the `rocker/geospatial` image:
 >
 >~~~
 >$ docker pull rocker/geospatial
@@ -192,14 +196,14 @@ Option B involves downloading an Docker image that contains an installation of `
 >
 > Once the pull command is executed, the image needs to be run to become accessible as a container. In the following example, the image is named `rocker/geospatial` and the container is named `gis`. The [image](https://docs.docker.com/glossary/?term=image) contains the software you've downloaded, and the [container](https://docs.docker.com/glossary/?term=container) is the run-time instance of that image. New Docker users should need only one named container per image.
 >
-> When `docker run` is used, you can specify a folder on your computer to become accessible inside your RStudio Server instance. The following `docker run` command exposes Jane's `GitHub` directory to RStudio Server:
+> When `docker run` is used, you can specify a folder on your computer to become accessible inside your RStudio Server instance. The following `docker run` command exposes Jane's `GitHub` directory to RStudio Server. Enter the file path where your workshop resources and data are stored:
 >
 >~~~
 >$ docker run -d -P --name gis /Users/jane/GitHub:/home/rstudio/GitHub rocker/geospatial
 >~~~
 >{: .bash}
 >
-> When she opens her RStudio instance below, she will see a `GitHub` folder in her file table in the lower righthand corner of the screen. Windows and Linux users will have to adapt the file path above to follow the standards of their operating systems. More details are available on [rocker's Wiki](https://github.com/rocker-org/rocker/wiki/Sharing-files-with-host-machine).
+> When she opens her RStudio instance below, she will see a `GitHub` folder in her file tab in the lower righthand corner of the screen. Windows and Linux users will have to adapt the file path above to follow the standards of their operating systems. More details are available on [rocker's Wiki](https://github.com/rocker-org/rocker/wiki/Sharing-files-with-host-machine).
 >
 > The last step before launching your container in a browser is to identify the port that your Docker container is running in:
 >
@@ -233,6 +237,36 @@ Option B involves downloading an Docker image that contains an installation of `
 >~~~
 >{: .bash}
 >
+> If you are returning to a session after stopping Docker itself, make sure Docker is running again before re-starting your container!
+>
+{: .solution}
+
+> ## Using the `rocker/geospatial` Docker Image via Kitematic
+> #### Download and Install Kitematic
+> [Kitematic](https://github.com/docker/kitematic) is the GUI, currently in beta, that Docker has built for accessing images and containers on Windows, macOS, and Ubuntu. You can download the appropriate installer files from Kitematic's [GitHub release page](https://github.com/docker/kitematic/releases/tag/v0.17.3). You need to have already installed Docker Community Edition (see instructions above) before installing Kitematic!
+>
+> #### Opening a Container with Kitematic
+> Once you have installed Kitematic, make sure the Docker application is running and then open Kitematic. You should not need to create a login to use Kitematic. If prompted for login credentials, there is an option to skip that step. Use the search bar in the main window to find `rocker/geospatial` (pictured below) and click `Create` under that Docker repository.
+>
+> ![](/fig/kitematicSearch.png)
+>
+> After downloading and installing the image, your container should start automatically. Before opening your browser, connect your Docker image to a local folder where you have your workshop resources stored by clicking on the `Settings` tab and then choosing `Volumes`. Click `Change` and then select the directory you would like to connect to.
+>
+> ![](/fig/kitematicLocal.png)
+>
+> When you open RStudio instance below, you will see the contents of the connected folder inside the `kitematic` directory in the file tab located in the lower righthand corner of the screen.
+>
+> When you are ready, copy the `Access URL` from the `Home` tab:
+>
+> ![](/fig/kitematicURL.png)
+>
+> Paste that url into your browser and, if prompted, enter `rstudio` for both the username and the password.
+>
+> #### Stopping and Restarting a Container
+> When you are done with a Docker session, make sure all of your files are saved locally on your computer **before closing your browser and Docker**. Once you have ensured all of your files are available (they should be saved at the file path designated in `docker run` above), you can stop your Docker container by clicking on the `Stop` icon in Kitematic's toolbar.
+>
+> You can restart your container later by clicking the `Restart` button.
+>
 {: .solution}
 
 > ## Managing Docker Containers and Images