README.md

# nshmp-ws

*nshmp-ws* provides web service access to ground motion models (GMMs) used in USGS National Seismic
Hazard Models (NSHMs).

[TOC]

## Running the Services

### Gradle

To run the services with Gradle:

```bash
./gradlew run
# or './gradlew run -t' to recompile and relaunch when code changes
```

Alternatively, the services can be run from the JAR file:

```bash
./gradlew assemble
java -jar build/libs/nshmp-ws-all.jar
```

After startup, web services and documentation are available at <http://localhost:8080/>.

#### Customizing Code

Whereas *nshmp-ws* contains code to run web services, ground motion model (GMM) calculations
are handled in the dependent library [*nshmp-lib*](https://code.usgs.gov/ghsc/nshmp/nshmp-lib).
To use a local, modified version of *nshmp-lib*, set an environment variable
`NSHMP_LIB_LOCAL=true` and *nshmp-ws* will look for *nshmp-lib* in a directory adjacent to
*nshmp-ws*. If *nshmp-lib* is located somewhere else, modify the path specified in
[`gradle/dependencies.gradle`](../../gradle/dependencies.gradle). When using a local version
of *nshmp-lib*, first build the *nshmp-lib* project using `./gradlew fatJar` so that
required dependencies are included.

Summary of steps to check out and start running code for local development:

```bash
# --> Set a NSHMP_LIB_LOCAL=true environment variable on your system
cd yourProjectDirectory
git clone https://code.usgs.gov/ghsc/nshmp/nshmp-lib.git
cd nshmp-lib
./gradlew fatJar
cd ..
git clone https://code.usgs.gov/ghsc/nshmp/nshmp-ws.git
cd nshmp-ws
./gradlew run
```

### Docker

#### Run from GitLab Registry

The nshmp-ws application may be run as a Docker container.

```bash
docker pull code.usgs.gov:5001/ghsc/nshmp/images/nshmp-ws
docker run \
    -p <PORT>:8080 \
    code.usgs.gov:5001/ghsc/nshmp/images/nshmp-ws

# Example
docker run \
    -p 8080:8080 \
    code.usgs.gov:5001/ghsc/nshmp/images/nshmp-ws
```

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

```bash
http://localhost:PORT/nshmp/data

# Example
http://localhost:8080/nshmp/data
```

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

#### Build Docker Locally

A Docker image can also be created locally:

```bash
docker build -t <tag name> .
```