diff --git a/docs/README.md b/docs/README.md index 6a952c9a80f9eb8e65ade42981d5639c794a3679..fcf5ab4e0f5b0e006ac6ab89dcbb8ab624eae00d 100644 --- a/docs/README.md +++ b/docs/README.md @@ -19,6 +19,7 @@ use *nshmp-haz* as well as underlying model implementation details. * [Calculation Configuration](./pages/Calculation-Configuration.md) * [Site Specification](./pages/Site-Specification.md) * [Examples](../../etc/examples) + * [Web Services](./pages/Web-Services.md) * [Hazard Model](./pages/Hazard-Model.md) * [Model Structure](./pages/Model-Structure.md) * [Model Files](./pages/Model-Files.md) diff --git a/docs/pages/Building-&-Running.md b/docs/pages/Building-&-Running.md index fd91043957d9e256364065d5466269ae8bb5b717..12d1ad33e5483a43a18ecbd7079a50aacdb7e91d 100644 --- a/docs/pages/Building-&-Running.md +++ b/docs/pages/Building-&-Running.md @@ -8,6 +8,7 @@ * [Site Specification](./Site-Specification.md#site-specification) * [Examples](../../etc/examples) (or [on GitLab](https://code.usgs.gov/ghsc/nshmp/nshmp-haz/-/tree/main/etc/examples)) + * [Web Services](./Web-Services.md) ## Build & Run Options diff --git a/docs/pages/Web-Services.md b/docs/pages/Web-Services.md new file mode 100644 index 0000000000000000000000000000000000000000..44b3284a0f803700d545ca4794debe2327e1e1fd --- /dev/null +++ b/docs/pages/Web-Services.md @@ -0,0 +1,165 @@ +# Web Services + +## Related Pages + +* [Building & Running](./Building-&-Running.md#building-&-running) + * [Developer Basics](./Developer-Basics.md#developer-basics) + +## Build & Run Options + +* [Build and run locally](#build-and-run-locally) +* [Run with Docker](#run-with-docker) + +## Build and Run Locally + +Building and running *nshmp-haz* web services requires prior +installation of Git and Java. Please see the [developer basics](./Developer-Basics.md) +page for system configuration guidance. + +### Building + +Navigate to a location on your system where you want *nshmp-haz* code to reside, clone the +repository, and compile: + +```bash +cd /path/to/project/directory +git clone https://code.usgs.gov/ghsc/nshmp/nshmp-haz.git +cd nshmp-haz +./gradlew assemble +``` + +This creates a single file, `build/libs/nshmp-haz.jar` that may be used to run the web services. +`./gradlew` executes the Gradle Wrapper script (there is a `gradlew.bat` equivalent for Windows +users using the native command prompt). This executes any tasks (e.g. `assemble`) after +downloading all required dependencies, including Gradle itself. + +## Running Web Services + +```bash +java -jar path/to/nshmp-haz.jar --model=path/to/model +``` + +Web service runs on [http://localhost:8080/](http://localhost:8080/) + +The `--model` argument should contain the path to a single +hazard source [model](./Hazard-Model.md). + +The [National Seisimic Hazard Models (NSHMs)](https://code.usgs.gov/ghsc/nshmp/nshms) +are available to download. + +### Example with NSHM + +```bash +# Build nshmp-haz +cd /path/to/nshmp-haz +./gradle assemble + +# Download NSHM CONUS +cd .. +git clone https://code.usgs.gov/ghsc/nshmp/nshms/nshm-conus + +# Run web services +cd /path/to/nshmp-haz +java -jar build/libs/nshmp-haz.jar --model=../nshm-conus +``` + +Open browser to [http://localhost:8080/](http://localhost:8080/). + +## Run with Docker + +### Docker Requirments + +* [Docker](https://docs.docker.com/install/) + +#### 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](https://docs.docker.com/docker-for-mac/#advanced) +to a minimum of 4 GB. + +### Docker Build Options + +* [Build and run docker locally](#build-and-run-docker-locally) +* [Run from Docker Hub](#run-from-docker-hub) + +### 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 Docker Hub + +A public Docker image is avaialable on [Docker Hub](https://hub.docker.com/r/usgs/nshmp-haz-ws) + +There are 2 main tags: + +* staging-latest (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 nshmp-haz-ws:latest + +# Run +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. + +#### Docker Hub Example with NSHM + +```bash +# Pull image +docker pull 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" nshmp-haz-ws +``` + +Open browser to [http://localhost:8080/](http://localhost:8080/). + +--- + +* [**Documentation Index**](../README.md) + +--- + [U.S. Geological Survey](https://www.usgs.gov) +National Seismic Hazard Mapping Project ([NSHMP](https://earthquake.usgs.gov/hazards/))