Run MsPASS with Docker#

This page expands the desktop quick start for users who want to run MsPASS from a terminal. The standard image starts JupyterLab, MongoDB, a Dask scheduler, and a Dask worker together in one container.

Prerequisites#

Install Docker Desktop on Windows or macOS, or Docker Desktop or Docker Engine on Linux. The Docker installation guide has instructions for each platform. Start Docker before running the commands below.

Download the MsPASS image#

The MsPASS image is hosted on Docker Hub. Download it with:

docker pull mspass/mspass

The first download can take a few minutes. Docker stores the image in its own data area, so no files appear in the directory where you run this command. The download therefore consumes space in Docker’s image store rather than in your project directory. Use Docker Desktop’s image view or docker image ls to inspect downloaded images and their sizes. The image is also available from the GitHub Container Registry.

Run MsPASS#

Create a project directory, change to that directory in a Linux or macOS terminal, and run:

docker run -p 8888:8888 --mount src=`pwd`,target=/home,type=bind mspass/mspass

The host computer and the container have separate filesystem namespaces. A path on the host does not automatically exist at the same path inside the container. The mount option explicitly connects the host project directory to the container’s /home directory.

The two important options are:

-p 8888:8888

Makes the JupyterLab server available on port 8888 of your computer.

--mount src=`pwd`,target=/home,type=bind

Maps the current project directory to /home in the container. Files written under /home remain in the project directory after the container stops.

Keep the terminal open while using MsPASS. Startup messages appear there as MongoDB, Dask, and JupyterLab become ready.

Connect to JupyterLab#

Near the end of the startup output, JupyterLab prints a URL containing an access token. Copy the URL beginning with http://127.0.0.1:8888/ into a browser on the same computer. Do not share the token-bearing URL.

The exact messages and token change from run to run, but the useful portion looks similar to this:

Jupyter Server is running at:
http://127.0.0.1:8888/lab?token=ced2d40475df...
Use Control-C to stop this server and shut down all kernels.

Wait for this message before trying to connect. The earlier MongoDB and Dask messages show that startup is progressing, but do not mean the web interface is ready.

JupyterLab’s file browser shows the contents of /home, which is the project directory you mounted. You can open an existing notebook or create a new notebook, console, or terminal. See the JupyterLab interface guide if the interface is unfamiliar.

The first run creates three service directories in the project directory:

db/

MongoDB database files.

logs/

Logs from MongoDB, the scheduler, and the worker.

work/

Temporary space used by Dask or Spark workers.

Do not omit the mount option for normal work. Without it, notebooks, database files, and other results remain only inside the container and can be lost when the container is removed.

Use a terminal inside JupyterLab#

The JupyterLab launcher includes a Terminal option as well as notebook and console options. It opens a shell inside the MsPASS container with /home as the project area. This can be useful for running a Python script, examining files, or monitoring CPU and memory with tools such as top. Type bash if the initial shell lacks familiar line editing or other interactive features.

The shell normally runs as root inside the container. That is not the same as being root on the host, but the shell can still modify or delete host files through the read-write /home bind mount. Use administrative and file-removal commands carefully. Software installed or files created outside the mounted directory are container-local and may be lost when the container is removed.

Stop MsPASS#

Save and close active notebooks, then press Ctrl-C in the terminal that is running the container. Allow the shutdown messages to finish so MongoDB and the worker processes can stop cleanly. Files in the mounted project directory remain available for the next run. Jupyter may ask you to press Ctrl-C a second time to confirm shutdown.

Other host shells#

The pwd form above is for Linux and macOS shells. In Windows PowerShell, run the following command from the project directory:

docker run -p 8888:8888 --mount "src=$($PWD.Path),target=/home,type=bind" mspass/mspass

For any shell, you can replace the current-directory expression with the absolute path to an existing project directory. Quote the full mount value when the path contains spaces. For example:

--mount "src=/absolute/path/to/project,target=/home,type=bind"

Optional settings#

Use another host port#

If port 8888 is already in use, change the first port number. For example:

docker run -p 9999:8888 --mount src=`pwd`,target=/home,type=bind mspass/mspass

In this case, replace port 8888 with 9999 in the JupyterLab URL.

Tune Dask workers#

Python-heavy processing can benefit from multiple single-threaded Dask worker processes because Python threads are limited by the Global Interpreter Lock. To request four workers with one thread each, use:

docker run -p 8888:8888 -e MSPASS_WORKER_ARG="--nworkers 4 --nthreads 1" --mount src=`pwd`,target=/home,type=bind mspass/mspass

Choose a worker count that fits the CPUs and memory available to Docker, while leaving resources for MongoDB, JupyterLab, and the operating system. More workers are not always faster.

Troubleshooting#

Docker cannot connect#

Start Docker Desktop, or start the Docker Engine service on Linux. Running docker version should display both Client and Server sections. A permission error on Linux usually means the account has not been configured to use the Docker service.

The project directory is missing#

Make sure the mount source is an existing directory and that your account can read and write it. Docker Desktop may also ask for permission to share a host directory or drive.

JupyterLab does not appear#

Read the startup messages in the terminal first. Common causes are a port conflict, a missing mount directory, insufficient memory, or Docker not running. Wait for the token-bearing JupyterLab URL before opening the browser.

The machine becomes slow#

Reduce the Dask worker count, stop other memory-intensive applications, or increase the CPU and memory assigned to Docker Desktop when the computer has capacity. Worker and scheduler details are recorded under logs/.

Next steps#