-
Notifications
You must be signed in to change notification settings - Fork 11
Using MsPASS with Docker
This wiki page is intended to be used as a quick reference for running docker on a desktop system. It assume you have read the section of the documentation on this topic found here.
There are good online instructions for installing docker on docker's web site. Follow one of the following links base on the operating system your desktop is running:
Windows,
MacOS, and
Linux.
You will need admin (root) privileges on the machine to install docker.
On Macs Docker is a normal package available for download here. It is installed in the standard manner most Mac user's will be familiar with. It is installed in the Applications folder. To launch the docker daemon simply double click the application icon in the usual Mac way. It will create an icon on the task bar that can be used to terminate the daemon and a few other tasks that are described in the documentation for the software.
For linux system docker would normally be installed through the package manager used by that flavor of unix. For example, here is a useful source for ubuntu. There is one trick not in the standard install instruction you should be aware of. By default Docker can only be run with a sudo command. That means each "docker" call below would need to be change to "sudo docker". You can do that, but it can get annoying. To avoid this you need to manipulate groups to get your user name in the same group as docker. There are variants in Unix about how groups are handled. Follow this link for instructions on Ubuntu. You also may find it necessary to restart your machine to get the revised groups to be recognized.
To proceed from here we assume Docker has been installed and the docker daemon is running in the background.
Once you have docker setup properly, use the following command in a terminal to pull the docker image from Docker Hub to your local machine:
docker pull mspass/mspass
Alternatively, or in addition you may want to fetch the development container that has a set of standard debugging tools installed for use within the container:
docker pull mspass/mspass:dev
Be patient as this can take a few minutes. Note you can run this command from anywhere. It loads data only in the virtual machine data space so you will not see anything happen in the directory where you run this command but it will eat of a few hundred megabytes on your disk. Any data created and stored inside the container will be opaque from the local system (outside) except for the ones in the directories that are mounted to the container.
To run mspass via docker we assume you have an version of a terminal window open with a unix shell. Use the cd command to make the working directory for you data the current directory. The most common way to launch docker is as follows:
docker run -p 8888:8888 -p 8787:8787 --mount src=`pwd`,target=/home,type=bind mspass/mspass
For development it can be useful to use the container only for running MongoDB. The most common reason is that at present it is hard to run an IDE like spyder to debug a new processing function. Our experience is that debugging a new processing function is best done in a serial mode using this procedure. Test the function in serial mode on a small data set, convert the test script to dask or spark, and then verify the function produces the same answer and works in a parallel version of the same processing steps.
First, we assume you already did a pull for the current container. Either the production or dev container should work, but for this application the smaller, regular container is usually preferable.
You should make sure you have a current copy of the mspass source code from github. If you have done that previously, cd to the top level directory for mspass. Are use the standard github refresh line:
git pull git@github.com:mspass-team/mspass.git
If this is the first time you are doing this, select a directory where you want to put the source code tree and cd to that directory, and use the following github command to fetch the repository:
git clone git@github.com:mspass-team/mspass.git
Assuming you have a compiler setup (following this guide to set up) enable you can compile build a local copy of mspass with the following standard python install line:
pip3 install --user ./
Noting this will only install a private copy of mspass for your account only. pip install that package in under ~/.local. If you omit the --user flag you will need root access to install the package in the (default) directory of /usr/local. Unless there are multiple people using mspass for development on the same system, we strongly recommend the --user option to reduce mysterious behavior from package collisions.
The final step is to select a directory where you have your test data. cd to that directory and launch mspass with the following docker run variant:
docker run --name MsPASS -d -p 27017:27017 --mount src=`pwd`,target=/home,type=bind mspass/mspass
Noting a few key point:
- The -d option launches the container in "daemon" mode meaning it will run in the background. You will notice this because
unlike a normal run the command will return control to your shell after the container starts. The corollary to this is you
may need to kill the container (see docker stop) as a cleanup step. - The -p option here is to map the MongoDB port to allow you to communicate with MongoDB from a local script. If there is a firewall problem with 27017 you may need to map to different port. See online sources if you face this (unusual) issue.
- The file system mapping is the same as above. A point worth emphasizing here is that this incantation maps the current directory (.) to be referenced as /home inside the container. Files you need to access for test must then be present in the current directory or some directory below the current directory.
You should now be able to run your favorite IDE on local python code. The only thing to be aware is that files referenced by MongoDB will map "." to "/home".