Home

The scripts in this repo are used to build docker images from the bbp distribution.

Motivation for Creating a BBP Docker Image

We are using Docker to help distribute our scientific software. Users that retrieve SCEC software from Dockerhub can install and run it on a wide variety of computers and operating systems. SCEC software is designed for use on Linux computer environments, becauses most academic HPC clusters are Linux-based systems. The Docker version of BBP will run on Linux, but also on Mac and Windows computers.

Preparing to Run BBP Docker

Here we describe a typical installation for BBP Docker. Assume the user has a Mac computer and they want to run BBP. The user should install Docker on their Computer. The user should create a Dockerhub account. The User should select a directory on their Mac, where they want the BBP simulation results to be saved. We will call this the "bbp home" directory. Within the home directory, the user creates a subdirectory, called "target". As an example, on my Mac, my bbp home directory is /Users/maechlin/bbp_docker, and my bbp data directory is /Users/maechlin/bbp_docker/target.

A key issue is how files are shared between the Docker image, and the users computer. Files are shared in the "target" directory mentioned above. Look at the run_bbp.sh script in this repo to see how to invoke BBP and how to mount the right directories.

Once the BBP docker image is available from Dockerhub, users run the image from a terminal window on their computer. The Docker daemon must be running. When the user issues the docker run command, the image starts and creates a container. When the container is running, the terminal windown changes. It shows the users logged into a centos linux computer, as user bbp, in a directory /app/target.

The files in the /app/target are the same files in their local computer at /Users/maechlin/bbp_docker/target directory.

Building the BBP Docker Image

The scripts in this directory are used to build the BBP Docker image. Start the process, by selecting a working directory on your development computer (a Mac for example), then cloning the bbp_docker git repo to retrieve scripts used in docker build.

On Mac:

$cd /Users/maechlin
$git clone https://github.com/sceccode/bbp_docker.git

cd into new directory

$cd bbp_docker

Retrieve the git repo of the bbp distribution that you want to install in the docker image: Syntax for single branch clone

$git clone --single-branch --branch <branchname> <remote-repo>
$git clone --single-branch --branch dev https://github.com/sceccode/bbp.git

Define Regions of Interest

The BBP platform supports earthquake simulations for multiple regions. Each supported region uses region specific, and method specific, greens functions. During our Docker evaluation, we are working with a minimum installation of BBP. This will include GF for southern California regions, and three validation events, Whittier Narrrows, Northridge, and Chino Hills. If this minimun configuration proves useful, we can configure other regions, or potentially more regions in each image. More regions will increase the size of the Docker image. Current, we expect Docker images of 50GB range, which is substantial. Pulling this image from Dockerhub can take up to one hour.

Retrieve large files

To reduce the Docker build time, we stage several large files in the bbp_docker/ build directory. By staging these files before we run the Docker build, these file are copied into the image during the Docker build process, instead of downloaded over the network.

the staged larges files include:

Anaconda3-2021.05-Linux-x86_64.sh
labasin500-velocity-model-19.4.0.tar.gz
curl -O http://hypocenter.usc.edu/research/bbp/versions/19.4.0/nr-validation-19.4.0.tar.gz
curl -O http://hypocenter.usc.edu/research/bbp/versions/19.4.0/whittier-validation-19.4.0.tar.gz
curl -O http://hypocenter.usc.edu/research/bbp/versions/19.4.0/chino-hills-validation-19.4.0.tar.gz

Start the Docker Build

In this repo, there is a build_bbp.sh script. This invokes the docker build command. This script gives the output image a name (a tag). The current tag convention is bbp_19_4:MMDDHHMM with the assumption that "later" docker images are prefered over earlier ones. This naming convention should be updated to identify what regions and validation events are included in the image.

$build_bbp.sh

This starts the docker build process. The process completes it will create a new image and write it to the docker repo on the current computer.

Push the Image to Dockerhub

On the development computer,

$ docker tag -t sceccode/bbp_19_4:MMDDHHMM
$docker push sceccode/bbp_19_4:MMDDHHMM

Setting the Stack Size

The Docker run command requires a parameter to increase the stack size. This is now included in the run_bbp.sh. Two keys were: correct abbreaivation for "stack size". Also, using size=-1 (which is equivalent to unlimited), since the command line doesn't accept the "unlimited" as text. Once the image starts, you can confirm the updated limits with: $ulimit -a

Using the Image

This directory contains a script that will run the docker bbp image:

$run_bbp.sh

When the image starts, the user is presented with the commnand line in terminal window on a centos-8 system that has BBP installed. The user name is bbp. The working directory is /app/target.

In the /app/target, the configuration and output directories for BBP. The files in /app/target/outdata are bbp simulation results. Users can run $ run_bbp.py and the bbp software will ask them a series of questions, setup and run a bbp simulation, and the results will be saved to the /app/target/outdata directory.

When users is completed running bbp simulations, then can exit the container. The output files produced by the container will be preserved on their local computer in their "target" directory, like the example /Users/maechlin/bbp_docker/target.