Using-Docker.md

# Using [Docker](https://docs.docker.com/install/)

*nshmp-haz* is available as a public image from the
[GitLab registry](https://code.usgs.gov/ghsc/nshmp/nshmp-haz/container_registry/69) with tags:

* `latest`,`staging-latest`: Latest updates associated with the
[main](https://code.usgs.gov/ghsc/nshmp/nshmp-haz/-/tree/main) branch
* `production-latest`: Latest stable release associated with a
[tag](https://code.usgs.gov/ghsc/nshmp/nshmp-haz/-/tags)

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

```bash
docker pull code.usgs.gov:5001/ghsc/nshmp/nshmp-haz/nshmp-haz:<tag>
```

> Replace `<tag>` with one of the above tags.

Example:

```bash
docker pull code.usgs.gov:5001/ghsc/nshmp/nshmp-haz/nshmp-haz: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](https://docs.docker.com/docker-for-mac/#advanced)
to a minimum of 4 GB.

## Run *nshmp-haz* in Docker

```bash
# Pull docker image
docker pull code.usgs.gov:5001/ghsc/nshmp/nshmp-haz/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 \
    code.usgs.gov:5001/ghsc/nshmp/nshmp-haz/nshmp-haz
```

Where:

* `CLASS_NAME` is the nshmp-haz class to run:
  * [DisaggCalc](../../src/main/java/gov/usgs/earthquake/nshmp/DisaggCalc.java)
  * [HazardCalc](../../src/main/java/gov/usgs/earthquake/nshmp/HazardCalc.java)
  * [RateCalc](../../src/main/java/gov/usgs/earthquake/nshmp/RateCalc.java)
* Other arguments (local files mapped to files within the Docker container with `:/app/...`):
  * (required) The absolute path to a [USGS model (NSHM)](./USGS-Models.md)
    * Example: `$(pwd)/nshm-hawaii:/app/model`
  * (required) The absolute path to a GeoJSON or CSV [site(s)](./Site-Specification.md) 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](./Calculation-Configuration.md) file
    * Example: `$(pwd)/my-custom-config.json:/app/config.json`

## Examples

### [`HazardCalc`](../../src/main/java/gov/usgs/earthquake/nshmp/HazardCalc.java) Example

The following example runs the `HazardCalc` program in nshmp-haz with the
[nshm-hawaii](https://code.usgs.gov/ghsc/nshmp/nshms/nshm-hawaii.git) model and the
assumption a GeoJSON [site](./Site-Specification.md) file exists named `sites.geojson`.

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

# Pull image
docker pull code.usgs.gov:5001/ghsc/nshmp/nshmp-haz/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" \
    code.usgs.gov:5001/ghsc/nshmp/nshmp-haz/nshmp-haz
```

### [`DisaggCalc`](../../src/main/java/gov/usgs/earthquake/nshmp/DisaggCalc.java) Example

The following example runs the `DisaggCalc` program in nshmp-haz with the
[nshm-hawaii](https://code.usgs.gov/ghsc/nshmp/nshms/nshm-hawaii.git) model and the
assumption a GeoJSON [site](./Site-Specification.md) file exists named `sites.geojson`.

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

# Pull image
docker pull code.usgs.gov:5001/ghsc/nshmp/nshmp-haz/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" \
    code.usgs.gov:5001/ghsc/nshmp/nshmp-haz/nshmp-haz
```

### [`RateCalc`](../../src/main/java/gov/usgs/earthquake/nshmp/RateCalc.java) Example

The following example runs the `RateCalc` program in nshmp-haz with the
[nshm-hawaii](https://code.usgs.gov/ghsc/nshmp/nshms/nshm-hawaii.git) model and the
assumption a GeoJSON [site](./Site-Specification.md) file exists named `sites.geojson`.

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

# Pull image
docker pull code.usgs.gov:5001/ghsc/nshmp/nshmp-haz/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" \
    code.usgs.gov:5001/ghsc/nshmp/nshmp-haz/nshmp-haz:latest
```

## Run Customization

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

```bash
docker run \
    --env JAVA_MEMORY=<MEMORY> \
    ...
    code.usgs.gov:5001/ghsc/nshmp/nshmp-haz/nshmp-haz

# Example
docker run \
    --env JAVA_MEMORY="12g" \
    ...
    code.usgs.gov:5001/ghsc/nshmp/nshmp-haz/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](../../ws.Dockerfile).

```bash
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/](http://localhost:8080/)

The hazard model is read in via Docker volumes.

#### Local Docker Example with NSHM

```bash
# 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/](http://localhost:8080/).

### Run from Container Registry

A public Docker image is avaialable from the
[Gitlab registry](https://code.usgs.gov/ghsc/nshmp/nshmp-haz/container_registry/68) with tags:

* `latest`,`staging-latest`: Refers to the
[main](https://code.usgs.gov/ghsc/nshmp/nshmp-haz/-/tree/main) branch and is the latest updates
* `production-latest`: Refers to the latest
[tag](https://code.usgs.gov/ghsc/nshmp/nshmp-haz/-/tags) and is stable

```bash
# Pull image
docker pull code.usgs.gov:5001/ghsc/nshmp/nshmp-haz/nshmp-haz-ws:latest

# Run
docker run -p 8080:8080 -v "/path/to/model:/model" code.usgs.gov:5001/ghsc/nshmp/nshmp-haz/nshmp-haz-ws
```

Web service runs on [http://localhost:8080/](http://localhost:8080/)

The hazard model is read in via Docker volumes.

#### Container Registry Example with NSHM

```bash
# Pull image
docker pull code.usgs.gov:5001/ghsc/nshmp/nshmp-haz/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" code.usgs.gov:5001/ghsc/nshmp/nshmp-haz/nshmp-haz-ws
```

Open browser to [http://localhost:8080/](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):

```bash
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](./Building-&-Running.md#building-&-running)
  * [Developer Basics](./Developer-Basics.md#developer-basics)
  * [Calculation Configuration](./Calculation-Configuration.md#calculation-configuration)
  * [Site Specification](./Site-Specification.md#site-specification)
  * [Using Docker](./Using-Docker.md#using-docker)
  * See also the [examples](../../etc/examples) directory
* [**Documentation Index**](../README.md)

---
![USGS logo](./images/usgs-icon.png) &nbsp;[U.S. Geological Survey](https://www.usgs.gov)
National Seismic Hazard Mapping Project ([NSHMP](https://earthquake.usgs.gov/hazards/))