Building & Running

Overview

• Build and Run Locally
• Run with Docker

Build and Run Locally

Build requirements:

• Java 8 JDK: Oracle or OpenJDK
• Projects needed in adjacent directories:
  • nshmp-haz
  • nshmp-haz-ws (this project)
  • 2014 NSHM for the Conterminous U.S.
  • 2008 NSHM for the Conterminous U.S.
  • 2007 NSHM for Alaska
• Dependencies (managed by Gradle):
  • Java servlet support (e.g. Apache Tomcat 8)
  • Guava
  • Gson

Running:

Running nshmp-haz-ws services locally requires installation of a Java Servlet 3.1 container (e.g. Apache Tomcat 8). Once configured, executing:

cd /path/to/nshmp-haz-ws
./gradlew war

... creates a deployable WAR file in nshmp-haz-ws/build/libs.

To build, run, and test web applications using Eclipse, install:

• Eclipse IDE for Java EE Developers
• Apache Tomcat 8.0

Please see build.gradle for additional details on configuring paths to model directories.

Eclipse configuration and execution:

• Set the Java 8 JDK installation as the default: Preferences > Java > Installed JREs
• Set up a Tomcat server: Preferences > Server > Runtime Environments > Add...
• Import nshmp-haz: File > Import > Gradle > Existing Gradle Project
• Import nshmp-haz-ws, also as a Gradle project.
• Window > Perspective > Open Perspective > Java Browsing
• Select nshmp-haz-ws in the Package Explorer tab.
• Run > Run As > Run on Server

Run with Docker

Build requirements:

• Docker

Getting Latest Docker Image

To ensure you are on the latest nshmp-haz-ws update, pull the image from Docker:

docker pull usgs/nshmp-haz-ws-legacy

Docker Memory on Mac

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

Running

The nshmp-haz-ws application may be run as a Docker container. A public image is available on Docker Hub at https://hub.docker.com/r/usgs/nshmp-haz-ws-legacy which can be run with:

docker run -p <PORT>:8080 -d usgs/nshmp-haz-ws-legacy

# Example
docker run -p 8080:8080 -d usgs/nshmp-haz-ws-legacy

<PORT> should be replaced with an available port that is not in use. The application can then be accessed from:

http://localhost:<PORT>/nshmp-haz-ws

# Example
http://localhost:8080/nshmp-haz-ws

The <PORT> should be replaced with the same value to start the container.

Running Customization

Java Memory

When running nshmp-haz-ws 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-legacy

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

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

Repository Versions

When running the Docker image the version, branch, or commit may be supplied as arguments for nshmp-haz and the models:

docker run -p <PORT>:8080 \
  -e NSHMP_HAZ_VERSION=some-version-or-branch-or-commit \
  -e NSHM_AK_2007_VERSION=some-version-or-branch-or-commit \
  -e NSHM_COUS_2008_VERSION=some-version-or-branch-or-commit \
  -e NSHM_COUS_2014_VERSION=some-version-or-branch-or-commit \
  -e NSHM_COUS_2018_VERSION=some-version-or-branch-or-commit \
  usgs/nshmp-haz-ws-legacy

# Example
docker run -p 8080:8080 \
  -e NSHMP_HAZ_VERSION=v1.2.0 \
  -e NSHM_AK_2007_VERSION=master \
  -e NSHM_COUS_2008_VERSION=master \
  -e NSHM_COUS_2014_VERSION=v4.1.4 \
  -e NSHM_COUS_2018_VERSION=master \
  usgs/nshmp-haz-ws-legacy

To exclude a model from deploying set the version to null.

Default Repository Versions

• nshmp-haz: master
• nshm-ak-2007: master
• nshm-cous-2008: master
• nshm-cous-2014: v4.1.4
• nshm-cous-2014b: master
• nshm-cous-2018: master

Building

A Docker image may additionaly be built from the source using the accompanying Dockerfile:

docker build -t <IMAGE_NAME>:<IAMGE_TAG> .

# Example
docker build -t nshmp-haz-ws:latest . 

Development

Docker Compose can be used for development:

# Look for changes and rebuild WAR file
./gradlew assemble --continuous

# Run docker-compose.yaml file
docker-compose up -d

./gradlew assemble --continuous looks for any changes in the source code and rebuilds the WAR file. Docker Compose looks for any changes to the WAR file and redeploys.

Models

Models load as requested. While all supported models are available, requesting them all will eventually result in an OutOfMemoryError. Increase -Xmx to -Xmx16g or -Xmx24g, if available (See running customization).