jllovell/sandpyper repository overview

⁠Size

The image will occupy 5.29GB of space when pulled.

⁠Description

This image aims to make the Python package sandpyper reproducible and usable on any machine, independently of local operating system, versions of conda and python dependencies. You can use this image to create a Docker container that comes pre-installed with a Linux OS, Jupyter Lab, a sandpyper repository, and a functional instance of the sandpyper package with all its dependencies in a conda/mamba virtual environment named sandp_py39.

⁠Contents

This image has the base image: jupyter/minimal-notebook.
In addition, it clones the GitHub repository: https://github.com/jllovell/sandpyper_fork⁠, which is a fork of Nicolas Pucino's repository: https://github.com/npucino/sandpyper⁠.
The modifications in the main branch of the fork Vs the original sandpyper repo consist only of a BugFix of the deprecated function .to_wkt() in the source code, and of filepaths in the notebooks that make them immediately usable for the test data within the docker container. The image also creates a virtual environment with mamba (faster than conda + less RAM) to install the necessary dependencies for sandpyper from a .yml file, and installs sandpyper in editable mode with pip from the repo. This allows immediate use of the sandpyper beach dynamics analysis pipeline as well as custom modifications to the source code.

To use this docker image and work with sandpyper in a reproducible environment:

⁠1. Install Docker (if you don't have it already)

Download Docker Desktop from https://www.docker.com⁠.

Run the downloaded installer and follow the instructions. Restart your computer if prompted.

FOR WINDOWS USERS ONLY:
Docker Desktop requires Windows Subsystem for Linux (WSL 2).
Install WSL from either Windows Powershell or Command Prompt as an admin user with wsl --install.
Enable WSL in Docker Desktop:
a) Open Docker Desktop.
b) Go to Settings > General.
c) Enable “Use the WSL 2 based engine”.
d) Click Apply & Restart.

Check the installation was successful by opening a terminal (Command Line Interface, CLI) - for Windows: Powershell or Command prompt - and type:
docker --version

⁠2. Create the container from the image

Pull the image from DockerHub:
docker pull jllovell/sandpyper

Navigate to the directory on your computer where you have the data you want to work with and will store the results of using sandpyper:
cd /Path/To/Folder/With/Data or on Windows: cd C:\Path\To\Folder\With\Data

Create the container from the image, mounting your local working directory inside the container under the /jovyan/work directory, and exposing port 8888 for jupyter:
docker run -p 8888:8888 -v $(pwd):/home/jovyan/work --platform linux/amd64 -it jllovell/sandpyper
on Windows powershell, use:
docker run -p 8888:8888 -v ${PWD}:/home/jovyan/work --platform linux/amd64 -it jllovell/sandpyper
on Windows command prompt, use:
docker run -p 8888:8888 -v %cd%:/home/jovyan/work --platform linux/amd64 -it jllovell/sandpyper

💡 Tip: Always store your work inside /home/jovyan/work, as this is linked to your local folder. Any files saved elsewhere in the container will be lost when it is removed.

⁠3. Inside the container

Once the container is running, Jupyter should print a URL like [http://127.0.0.1:8888/?token=some_long_token⁠]. Open this in a browser on your computer to access Jupyter Lab inside the Docker container. Save this link to re-access Jupyter when reusing this container.

⁠Inside Jupyter Lab

Navigate to the "sandpyper_fork/examples/" folder to find the notebooks for using the sandpyper tool. When opening sandpyper notebooks, make sure to select the kernel for the sandp_py39 virtual environment, or it will not work.

⁠Editing sandpyper source code

The Sandpyper library is installed in editable mode from the cloned GitHub repository, so any modifications to its source code (found in "sandpyper_fork/sandpyper") will take effect immediately after you refresh the notebook kernel.

⁠Saving changes in the container

WARNING: Any modifications to code and notebooks exist only inside the container and will be lost if the container is deleted. Only files that you save to /home/jovyan/work will be saved on your computer and become independent of the container.

⁠Contributing to sandpyper

If you make improvements to the source code, you can share these with the open-source community by going to Github and fork https://github.com/npucino/sandpyper⁠, repeat your changes in your forked repo and initiate a pull request.
Bear in mind that sandpyper is distributed under the MIT License.

⁠4. Exiting and re-using the container

To close down the container, in the Jupyter Lab menu bar select Files >> Shut down. Alternatively press CTRL+C on your keyboard in the unix shell.

To check the name or ID of your container so you can continue to work with it, either look for it on the Docker Desktop app or type docker ps -a in your terminal.

You can also stop the container from the Unix command line with docker stop container_name_or_ID.

To start it again, use docker start container_name_or_ID , then go to your browser and paste the saved URL to open the same instance of Jupyter Lab and continue working where you stopped, without losing your progress.

If you have lost the URL, here are 2 options to find it:
a) Before restarting the container, type docker logs container_name_or_ID | grep -i "http://" to find the URL again.
In Windows Powershell, use docker logs container_name_or_ID | Select-String "http://".
In Windows Command Prompt use docker logs container_name_or_ID | findstr "http://".
b) Start the container with docker start container_name_or_ID , execute it in interactive mode with docker exec -it container_name_or_ID bash, then type jupyter notebook list. If the output shows a URL in the form [http://<container_id>:8888/?token=your_token_here], just replace the container ID with "127.0.0.1" and you will have the URL that you can paste in your browser to open Jupyter Lab. You can exit the interactive docker container by typing exit.

To delete the container for good, use docker rm container_name_or_ID .