Instructions for setting up and running Docker

Prerequisites

• GitHub account. Sign up here.
• Windows/Mac with git installed. See Instructions on how to install Git.
• Docker Desktop. Go to Docker and download Docker Desktop.

Instructions

1. Download and install Docker Desktop. Go to Docker and download Docker Desktop. Make sure you download the correct version based on your computer’s operating system and architecture. Follow the instructions to install Docker Desktop.
2. Launch Docker Desktop. The application should be running while you do the next steps. (You might need to create a Docker account and sign in if you don’t already have one.)
3. Download Docker image. Start a new terminal session (outside Docker). For example, open the Powershell on Windows or the Terminal on Mac. Copy and paste the following command into the terminal/PowerShell:

docker pull pshuai/jupyter-pflotran-multiplatform:latest

This will start downloading the docker image (~2G).

4. Create a working folder (e.g., work) on your system. This is where you will store your course material and class exercises.

5. Launch Docker. Replace PATH/TO/WORKING_FOLDER with the actual path to your working folder on your system, e.g., C:\Users\USERNAME\work (where USERNAME is your Windows username) or /Users/shuai/work (on Mac). Run the following command in your terminal/PowerShell.

# launch docker. Replace the PATH/TO/WORKING_FOLDER!
docker run -it --rm -p 8888:8888  -v PATH/TO/WORKING_FOLDER:/home/aggie/work pshuai/jupyter-pflotran-multiplatform:latest jupyter lab --ip=0.0.0.0 --allow-root --NotebookApp.token=''

6. Connect to the JupyterLab. If the above command is successful, you will see output like the following at the bottom of the screen.

[I 2025-01-22 05:49:28.562 ServerApp] Jupyter Server 2.15.0 is running at:
[I 2025-01-22 05:49:28.562 ServerApp] http://2f1be613bce1:8888/lab
[I 2025-01-22 05:49:28.562 ServerApp]     http://127.0.0.1:8888/lab
[I 2025-01-22 05:49:28.562 ServerApp] Use Control-C to stop this server and shut down all kernels (twice to skip confirmation).

Copy and paste the URL: http://127.0.0.1:8888/lab into your browser and you should see the JupyterLab interface below.

7. Download the course material. Click on the Terminal application (first to the left under the Other tab) to start a terminal session inside the container. Run the following command

git clone https://github.com/hydroaggie/hydrologic-modeling-course-2024.git 

The course folder hydrologic-modeling-course-2024 will appear on the left panel.

8. Congratulations! You are all set!

Troubleshoot

• If your Docker is running out of space, you might need to use docker system prune with the appropriate options to clear out old containers and make space for the new one.

$ docker system prune