docker desktop instructions rough done

Author: trevorcampbell

img/setup/docker-1.png

@@ -80,55 +80,77 @@ image_read("img/setup/ubuntu-docker.png") |>
 More information on installing and running Docker on Ubuntu, as well as troubleshooting tips, can be found
 [in the online Docker documetation](https://docs.docker.com/engine/install/ubuntu/).
 
-### Windows
-
-https://docs.docker.com/desktop/install/windows-install/
-use WSL 2 backend instructions
-run wsl --update in cmd.exe
-
-Install Docker Desktop on Windows
-Install interactively
-Double-click Docker Desktop Installer.exe to run the installer.
-
-If you haven’t already downloaded the installer (Docker Desktop Installer.exe), you can get it from Docker Hub. It typically downloads to your Downloads folder, or you can run it from the recent downloads bar at the bottom of your web browser.
-
-When prompted, ensure the Use WSL 2 instead of Hyper-V option on the Configuration page is selected or not depending on your choice of backend.
-
-If your system only supports one of the two options, you will not be able to select which backend to use.
-
-Follow the instructions on the installation wizard to authorize the installer and proceed with the install.
+### MacOS
 
-When the installation is successful, click Close to complete the installation process.
+To install Docker on MacOS, visit [the online Docker
+documentation](https://docs.docker.com/desktop/install/mac-install/), and
+download the `Docker.dmg` installation file that is appropriate for your
+computer (you need to know whether your computer has an Intel processor an
+Apple processor). Double-click the file to open the installer, then drag
+the Docker icon to the Applications folder.  Double-click Docker.app in the
+Applications folder to start Docker. In the installation window, use the
+recommended settings.
+
+Once Docker is installed and running, follow the instructions below in the Windows section
+for finding and running the virtual machine we have made available for this book.
+More information on installing and running
+Docker on MacOS, as well as troubleshooting tips, can be found [in the online
+Docker documetation](https://docs.docker.com/desktop/install/mac-install/).
 
-If your admin account is different to your user account, you must add the user to the docker-users group. Run Computer Management as an administrator and navigate to Local Users and Groups > Groups > docker-users. Right-click to add the user to the group. Log out and log back in for the changes to take effect.
+### Windows
 
+To install Docker on Windows, visit [the online Docker documentation](https://docs.docker.com/desktop/install/windows-install/),
+and download the `Docker Desktop Installer.exe` file. Double-click the file to open the installer
+and follow the instructions on the installation wizard, choosing **WSL-2** instead of **Hyper-V** when prompted.
 
-### MacOS
+Occasionally, when you first run Docker on Windows, you will encounter an error message. Some common errors and
+- If it complains that you need to update WSL, open `cmd.exe` and type `wsl --update`.
+- If it complains that you need to enable virtualization, reboot your computer, look in your bios for CPU flags.
+- If the admin account on your computer is different to your user account, you must add the user to the docker-users group. 
+  Run Computer Management as an administrator and navigate to Local Users and Groups > Groups > docker-users. Right-click to 
+  add the user to the group. Log out and log back in for the changes to take effect.
+More information on installing and running
+Docker on Windows, as well as troubleshooting tips, can be found [in the online
+Docker documetation](https://docs.docker.com/desktop/install/windows-install/).
 
-https://docs.docker.com/desktop/install/mac-install/
 
-Double-click Docker.dmg to open the installer, then drag the Docker icon to the Applications folder.
+Once Docker is running (in either Windows or MacOS), you need to download and run the virtual machine that we have made available
+for the worksheets. In the search bar, enter `ubcdsci/r-dsci-100`, as this is the name of the virtual machine image. You will be presented
+with a few options (\@ref(fig:docker-desktop-search)). In the "Tag" drop down menu, click the tag `20230724142640d8f06f` to select the 
+correct version of the image. Then click the "Pull" button to download the image.
 
-Double-click Docker.app in the Applications folder to start Docker.
+```{r docker-desktop-search, echo = FALSE, fig.cap = "The Docker Desktop search window. Make sure to click the Tag drop down menu and find the right version of the image before clicking the Pull button to download it.", fig.retina = 2, out.width="100%"}
+image_read("img/setup/docker-1.png") |> 
+  image_crop("3632x2000")
+```
 
-The Docker menu (whale menu) displays the Docker Subscription Service Agreement window.
+Once the image is done downloading, click the "Images" button on the left side of the Docker Desktop window (\@ref(fig:docker-desktop-images)). You
+will see the recently downloaded image listed there under the "Local" tab.
 
-Here’s a summary of the key points:
+```{r docker-desktop-images, echo = FALSE, fig.cap = "The Docker Desktop images tab.", fig.retina = 2, out.width="100%"}
+image_read("img/setup/docker-2.png") |> 
+  image_crop("3632x2000")
+```
 
-Docker Desktop is free for small businesses (fewer than 250 employees AND less than $10 million in annual revenue), personal use, education, and non-commercial open source projects.
-Otherwise, it requires a paid subscription for professional use.
-Paid subscriptions are also required for government entities.
-The Docker Pro, Team, and Business subscriptions include commercial use of Docker Desktop.
-Select Accept to continue.
+To run the virtual machine, click the play button beside the image. This will open the run configuration menu (\@ref(fig:docker-desktop-runconfig)).
+In the "Host port" textbox, enter `8888`. In the "Volumes" section, click the "Host path" box and navigate to the folder where your Jupyter worksheets
+are stored. In the "Container path" text box, enter `/home/jovyan/work`. Then click the "Run" button to start the container.
 
-Note that Docker Desktop will not run if you do not agree to the terms. You can choose to accept the terms at a later date by opening Docker Desktop.
+```{r docker-desktop-runconfig, echo = FALSE, fig.cap = "The Docker Desktop container run configuration menu.", fig.retina = 2, out.width="100%"}
+image_read("img/setup/docker-3.png") |> 
+  image_crop("3632x2000")
+```
 
-For more information, see Docker Desktop Subscription Service Agreement. We recommend that you also read the FAQs.
+After clicking the "Run" button, you will see a terminal. The terminal will then print 
+some text as the Docker container starts. Once the text stops scrolling, find the 
+URL in the terminal that starts 
+with `http://127.0.0.1:8888` (highlighted by the red box Figure \@ref(fig:ubuntu-docker-terminal)), and paste it 
+into your browser to start JupyterLab.
 
-From the installation window, select either:
-Use recommended settings (Requires password). This let’s Docker Desktop automatically set the necessary configuration settings.
-Use advanced settings. You can then set the location of the Docker CLI tools either in the system or user directory, enable the default Docker socket, and enable privileged port mapping. See Settings, for more information and how to set the location of the Docker CLI tools.
-Select Finish. If you have applied any of the above configurations that require a password in step 5, you are asked to enter your password to confirm.
+```{r docker-desktop-url, echo = FALSE, fig.cap = "The terminal text after running the Docker container in Ubuntu. The red box indicates the URL that you should paste into your browser to open JupyterLab.", fig.retina = 2, out.width="100%"}
+image_read("img/setup/docker-4.png") |> 
+  image_crop("3632x2000")
+```
 
 ## Working with JupyterLab Desktop
 
@@ -155,7 +177,7 @@ sudo apt update
 sudo apt install git
 ```
 
-Next, visit the [Installation section of the JupyterLab Desktop homepage](https://github.com/jupyterlab/jupyterlab-desktop#installation).
+Next, visit the ["Installation" section of the JupyterLab Desktop homepage](https://github.com/jupyterlab/jupyterlab-desktop#installation).
 Download and run the installer for Ubuntu/Debian.
 To install the JupyterLab Git extension, run JupyterLab Desktop, 
 open a notebook, and run the following code in a cell:
@@ -230,7 +252,7 @@ so that they are compatible with the exercise worksheets that accompany the book
 ## Finishing up installation
 
 It is good practice to restart all the programs you used when installing this
-software stack before you proceed to doing your data analysis.
+software before you proceed to doing your data analysis.
 This includes restarting JupyterLab as well as the terminal (MacOS and Ubuntu) 
 or the Anaconda Prompt (Windows).
 This will ensure all the software and settings you put in place are