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

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/usgsnshmp/nshmp-haz-ws which can be run with:

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

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

<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

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 usgsnshmp/nshmp-haz-ws

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

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

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 . 

Building Customization

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

docker build \
--build-arg NSHMP_HAZ_VERSION=some-version-or-branch-or-commit \
--build-arg NSHM_AK_2007_VERSION=some-version-or-branch-or-commit \
--build-arg NSHM_COUS_2008_VERSION=some-version-or-branch-or-commit \
--build-arg NSHM_COUS_2014_VERSION=some-version-or-branch-or-commit \
--build-arg NSHM_COUS_2018_VERSION=some-version-or-branch-or-commit \
-t IMAGE_NAME:IMAGE_TAG .

# Example
docker build \
--build-arg NSHMP_HAZ_VERSION=master \
--build-arg NSHM_AK_2007_VERSION=master \
--build-arg NSHM_COUS_2008_VERSION=master \
--build-arg NSHM_COUS_2014_VERSION=master \
--build-arg NSHM_COUS_2018_VERSION=master \
-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).