Using-Docker.md

Using Docker

nshmp-haz is available as a public image from Docker hub with tags:

• latest: Refers to the latest updates from the main or production branch
• development-latest: Refers to forks of the repository.
• staging-latest: Latest updates associated with the main branch
• production-latest: Latest stable release associated with the production branch

To ensure you have the latest nshmp-haz update associated with a specific tag, always first pull the image from Docker:

docker pull usgs/nshmp-haz:<tag>

Replace <tag> with one of the above tags.

Example:

docker pull usgs/nshmp-haz:production-latest

Docker Memory on Mac

By default, Docker Desktop for Mac is set to use 2 GB runtime memory. To run nshmp-haz, the memory available to Docker must be increased to a minimum of 4 GB.

Run nshmp-haz in Docker

# Pull docker image
docker pull usgs/nshmp-haz:latest 

# Run docker image
docker run \
    --env CLASS_NAME=<DisaggCalc | HazardCalc | RateCalc> \
    --env IML=<NUMBER> \
    --env RETURN_PERIOD=<NUMBER> \
    --volume /absolute/path/to/sites/file:/app/sites.<geojson | csv> \
    --volume /absolute/path/to/config/file:/app/config.json \
    --volume /absolute/path/to/output:/app/output \
    usgs/nshmp-haz

Where:

• CLASS_NAME is the nshmp-haz class to run:
  • DisaggCalc
  • HazardCalc
  • RateCalc
• Other arguments (local files mapped to files within the Docker container with :/app/...):
  • (required) The absolute path to a USGS model (NSHM)
    • Example: $(pwd)/nshm-hawaii:/app/model
  • (required) The absolute path to a GeoJSON or CSV site(s) file
    • CSV example: $(pwd)/my-csv-sites.csv:/app/sites.csv
    • GeoJSON example: $(pwd)/my-geojson-sites.geojson:/app/sites.geojson
  • (required) The absolute path to an output directory
    • Example: $(pwd)/my-hazard-output:/app/output
  • (optional) The absolute path to a configuration file
    • Example: $(pwd)/my-custom-config.json:/app/config.json

Examples

HazardCalc Example

The following example runs the HazardCalc program in nshmp-haz with the nshm-hawaii model and the assumption a GeoJSON site file exists named sites.geojson.

# Download Hawaii NSHM
git clone https://code.usgs.gov/ghsc/nshmp/nshms/nshm-hawaii.git

# Pull image
docker pull usgs/nshmp-haz:latest 

# Run nshmp-haz HazardCalc
docker run \
    --env CLASS_NAME="HazardCalc" \
    --volume "$(pwd)/nshm-hawaii:/app/model" \
    --volume "$(pwd)/sites.geojson:/app/sites.geojson" \
    --volume "$(pwd)/hawaii-hazard-output:/app/output" \
    usgs/nshmp-haz

DisaggCalc Example

The following example runs the DisaggCalc program in nshmp-haz with the nshm-hawaii model and the assumption a GeoJSON site file exists named sites.geojson.

# Download Hawaii NSHM
git clone https://code.usgs.gov/ghsc/nshmp/nshms/nshm-hawaii.git

# Pull image
docker pull usgs/nshmp-haz:latest 

# Run nshmp-haz DisaggCalc
docker run \
    --env CLASS_NAME="DisaggCalc" \
    --env RETURN_PERIOD=475 \
    --volume "$(pwd)/nshm-hawaii:/app/model" \
    --volume "$(pwd)/sites.geojson:/app/sites.geojson" \
    --volume "$(pwd)/hawaii-disagg-output:/app/output" \
    usgs/nshmp-haz:latest

RateCalc Example

The following example runs the RateCalc program in nshmp-haz with the nshm-hawaii model and the assumption a GeoJSON site file exists named sites.geojson.

# Download Hawaii NSHM
git clone https://code.usgs.gov/ghsc/nshmp/nshms/nshm-hawaii.git

# Pull image
docker pull usgs/nshmp-haz:latest 

# Run nshmp-haz RateCalc
docker run \
    --env CLASS_NAME="RateCalc" \
    --volume "$(pwd)/nshm-hawaii:/app/model" \
    --volume "$(pwd)/sites.geojson:/app/sites.geojson" \
    --volume "$(pwd)/hawaii-rate-output:/app/output" \
    usgs/nshmp-haz

Run Customization

When running nshmp-haz with Docker the maximum JVM memory size can be set with the environment flag (-e, -env):

docker run \
    --env JAVA_MEMORY=<MEMORY> \
    ...
    usgs/nshmp-haz

# Example
docker run \
    --env JAVA_MEMORY="12g" \
    ...
    usgs/nshmp-haz

Where:

• JAVA_MEMORY is the maximum memory for the JVM (default: 8g)

Run nshmp-haz web services in Docker

Build and Run Docker Locally

The Docker image may be built with the provided web service Dockerfile.

cd /path/to/nshmp-haz

# Build docker image
docker build -f ws.Dockerfile -t nshmp-haz-ws .

# Run Docker image
docker run -p 8080:8080 -v "path/to/model:/model" nshmp-haz-ws

Web service runs on http://localhost:8080/

The hazard model is read in via Docker volumes.

Local Docker Example with NSHM

# Build docker image
cd /path/to/nshmp-haz
docker build -f ws.Dockerfile -t nshmp-haz-ws .

# Download NSHM CONUS
cd ..
git clone https://code.usgs.gov/ghsc/nshmp/nshms/nshm-conus

# Run web services
docker run -p 8080:8080 -v "$(pwd):/model" nshmp-haz-ws

Open browser to http://localhost:8080/.

Run from Container Registry

A public Docker image is avaialable from Docker hub.

There are 4 main tags:

• latest: Refers to the latest updates from the main or production branch
• development-latest: Refers to forks of the repository.
• staging-latest: Refers to the main branch and is the latest updates
• production-latest: Refers to the production branch and is stable

# Pull image
docker pull usgs/nshmp-haz-ws:latest 

# Run
docker run -p 8080:8080 -v "/path/to/model:/model" usgs/nshmp-haz-ws

Web service runs on http://localhost:8080/

The hazard model is read in via Docker volumes.

Container Registry Example with NSHM

# Pull image
docker pull usgs/nshmp-haz-ws:latest 

# Download NSHM CONUS
cd ..
git clone https://code.usgs.gov/ghsc/nshmp/nshms/nshm-conus

# Run web services
docker run -p 8080:8080 -v "$(pwd):/model" usgs/nshmp-haz-ws

Open browser to http://localhost:8080/.

Java Memory

When running nshmp-haz web services with Docker the initial (Xms) and maximum (Xmx) JVM memory sizes can be set with the environment flag (-e, -env):

docker run -p <PORT>:8080 -e JAVA_OPTS="-Xms<INITIAL> -Xmx<MAX>" -d usgs/nshmp-haz-ws

# Example
docker run -p 8080:8080 -e JAVA_OPTS="-Xms1g -Xmx8g" -d usgs/nshmp-haz-ws

Where <INITIAL> and <MAX >should be set to the desired initial and maximum memory sizes, respectively.

---

Related Pages

• Building & Running
  • Developer Basics
  • Calculation Configuration
  • Site Specification
  • Using Docker
  • See also the examples directory
• Documentation Index

---

 U.S. Geological Survey National Seismic Hazard Mapping Project (NSHMP)