CSPP Geo Web Viewer - Web Client

For information on the entire GeoSphere project see the geosphere-deploy repository.

This is the main website for the CSPP Geo Web Viewer project. This repository contains all of the static content (HTML, CSS, JS, etc) for running the website. It also contains the necessary configuration to create a docker image to run this website on any machine with Docker installed. See the below sections for details on building and using these containers.

This website depends on a WMTS server and other components running on a remote server. This is currently run on the SSEC on-premise "gamma" cluster, but will be moved to another server after initial development has completed.

Website Configuration

There are two main ways the website can be configured to modify behavior. The first is the assets/config/categories.json file which defines the products that can be loaded and how those human-readable names map to backend requests.

Maintenance Notifications

The other way the client can be configured is via the assets/config/notification.json file. With this file, a special message can be defined which will be displayed to the user. This JSON file should specify a single key "message" where the value is the message to be displayed. To disable this message the message key should be updated to "_message" (note the underscore prefix).

Any changes to this file currently require a complete redeployment of the site in the operational Kubernetes cluster setting. There is no way to temporarily edit the configuration at this time.

Docker Build

This website can be bundled into a Docker image and then run from any machine that can run docker images. The configuration is all stored in the Dockerfile and can be built by running the below command from the root of this repository.

docker build -t gitlab.ssec.wisc.edu:5555/cspp_geo/cspp-geo-web-viewer/web_client:latest .

This builds the docker image and tags it so it can be added to the main CSPP Geo Web Viewer project. The "latest" part is the actual docker image tag that tells others what "version" this build is. Standard practice is to use "latest" for the newest build, but regular version numbers can also be used.

To actually push this image to the gitlab docker container registry:

docker push -t gitlab.ssec.wisc.edu:5555/cspp_geo/geosphere/geosphere-client/geosphere-client:latest

You can then do docker pull on another machine to get this image and use it.

Docker Usage

To run the docker container and serve this website you must first pull the image (see above) and then run:

docker run --rm -d --name web-client -p 8080:80 gitlab.ssec.wisc.edu:5555/cspp_geo/geosphere/geosphere-client/geosphere-client:latest

This starts up the container using its internal "nginx" server (similar to Apache) and serves the HTML from this repository. The --rm flag says to not keep this container around if it crashes or exits; just delete any reference of it. The -d tells docker to run this in the background (as a daemon). The --name web-client gives this running container a specific name instead of a just the random ID that docker will assign. The -p 8080:80 flag says to make nginx's port 80 available on this local systems port 8080. We then specify which image tag to run (latest).

Once this command is run you can then reach the website from http://localhost:8080/.

Docker Environment Variable Options

Some pieces of the website can be customized at runtime with the following environment variables:

• INFO_SERVER: URL where metadata can be retrieved from the /wms_times path.
• TILE_SERVER: Server URL serving the GeoSphere MapCache (WMTS) server. Multiple servers/domains can be specified by passing an OpenLayers compatible URL (ex. 'http://g2g{1-4}.ssec.wisc.edu:8889/mapcache/wmts').

Docker Debug

This section will provide some basic docker debugging information for anyone unfamiliar with docker. The first and easiest way to get information on the running container is to see its logs. On this container nginx writes its normal access and error logs do the docker container log. You can see it using (uses the --name from the docker run command):

docker logs web-client

Add -f after logs to "tail" the log and see output as it comes in.

You can check that your container is running by doing:

docker ps

Another way to debug running docker containers is to run commands on them:

docker exec web-client ls /usr/share/nginx/html

Or to get an interactive environment on the container:

docker exec -it web-client sh

NOTE: bash is not available on this container because of the way the image is structured (to keep the size small) so we use sh.

Lastly, you can kill a running container by doing:

docker kill web-client