# Using [Docker](https://docs.docker.com/install/)
*nshmp-haz* is available as a public image from
[Docker hub](https://hub.docker.com/r/usgs/nshmp-haz) 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](https://code.usgs.gov/ghsc/nshmp/nshmp-haz/-/tree/main) branch
* `production-latest`: Latest stable release associated with the
[production](https://code.usgs.gov/ghsc/nshmp/nshmp-haz/-/tree/production) branch
To ensure you have the latest *nshmp-haz* update associated with a specific tag,
always first pull the image from Docker:
```bash
docker pull usgs/nshmp-haz:<tag>
```
> Replace `<tag>` with one of the above tags.
Example:
```bash
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](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 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](../../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 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`](../../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 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`](../../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 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):
```bash
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](../../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 [Docker hub](https://hub.docker.com/r/usgs/nshmp-haz-ws).
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](https://code.usgs.gov/ghsc/nshmp/nshmp-haz/-/tree/main) branch and is the latest updates
* `production-latest`: Refers to the
[production](https://code.usgs.gov/ghsc/nshmp/nshmp-haz/-/tree/production) branch and is stable
```bash
# 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/](http://localhost:8080/)
The hazard model is read in via Docker volumes.
#### Container Registry Example with NSHM
```bash
# 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/](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)
---
 [U.S. Geological Survey](https://www.usgs.gov)
National Seismic Hazard Mapping Project ([NSHMP](https://earthquake.usgs.gov/hazards/))