Week 11 - Project Week: Zika Mission Control Part 4¶

Cross Origin Resource Sharing¶

Recall that CORS headers are required for resources (data) to be shared across origins when accessed through the browser. When a site rendered in the browser requests data from the same server the HTML/CSS/JS originates from we say these are requests to the same origin. However, when the client content is served from one origin (server) and requests data from another origin this is considered cross-origin. All modern browsers enforce the Same Origin Policy for improving the security by defaulting to rejection of any requests sent to different origins. CORS headers sent by the requested server allow this policy to be “relaxed” by communicating rules about what requests should be allowed.

In our current deployment we implemented CORS support in the Zika API in order for the browser to allow our front-end client (hosted at its own origin in an S3 bucket) to request API data served from a different origin (hosted in an EC2 instance). In the same way, our Geoserver will need to be configured to allow CORS in order for the WFS data to be received and displayed in the browser.

We could configure the CORS headers ourselves by modifying the Tomcat configuration files. But this is a tedious and delicate process that requires digging into and editing XML. Because it is increasingly common for a Geoserver to be hosted separately from clients that consume its data Kartoza has created an image that is pre-configured to set the headers for us!

This is a relatively large image so you can begin downloading it while completing the next sections by using the following command:

$ docker pull kartoza/geoserver:2.15.2

Database and Layer Setup¶

Before we start up and configure the Geoserver we will prepare our database to provide data in a format Geoserver recognizes. We will be creating some SQL views that pull in data from different tables that we want to be available as features. These views will then be used by Geoserver to generate queryable layers available through its exposed services.

Using the psql tool connect to your PostGIS database then create two views:

CREATE VIEW cases_by_location_and_date AS
  SELECT
    location_id,
    report_date,
    sum(value) AS cases
  FROM reports
  GROUP BY location_id, report_date
;

CREATE VIEW locations_with_cases_by_date AS
  SELECT locations.id, country, state, report_date, cases, geometry
  FROM locations
  INNER JOIN cases_by_location_and_date
    ON cases_by_location_and_date.location_id = locations.id
;

You are free to create any other views you would like using these examples as a template. Try querying from them to see how they work. They will be automatically detected by Geoserver once connected to the Postgis store. Views can then be published for use in the various Geoserver services such as the WFS project requirement.

Managing Geoserver Configuration Data¶

Recall in your Geoserver training that before we can begin consuming data we first need to configure the workspace, data store, layers and services we want it to expose. Each of these configurations are persisted by writing to files located in an installation directory called data_dir/. The location of this directory depends on how it was installed. In our containerized Geoserver its default location is /opt/geoserver/data_dir.

Although we will first configure Geoserver locally eventually our goal is to deploy it into our AWS cloud. We are presented with two options to choose from before beginning the configuration. Either save the local configuration, upload it to S3 and apply it in the deployed container or reconfigure the server from scratch once deployed.

The former approach involves mounting a host directory into the container as a bind mount so that data is written to the host (our local machine) instead of the container. The latter approach is simpler but will require more time during deployment. In both cases we will need to update the Postgis database connection details to point at our deployed database host.

If we choose to save a copy of the configuration we can use the -v volume option in the run command for the container. Bind mounting a volume is simply connecting a host machine directory to a container directory. Much in the same way that we use the -p option to “publish a port” which is just binding a host port to the container process’ port.

-p <host port>:<container port>

The general form for mounting a volume through a run command is:

-v </host/directory/path>:<container/directory/path>:<bind options>

As an example if we wanted to mount the host directory ~/geoserver/data to the container’s configuration directory /opt/geoserver/data_dir with rw or read-write ability we would use:

-v ~/geoserver/data:/opt/geoserver/data_dir:rw

Now when the container is started all of the configuration data will be written to the bind-mounted volume on the host at ~/geoserver/data. Later when we deploy the Geoserver we can upload this directory and mount it to the deployed container to save time having to reconfigure it!

Start Geoserver¶

Once the image has been pulled we can run the container using the following command. If you choose to bind mount a volume don’t forget to include that option in the run command.

$ docker run -d -p 8081:8080 --name zika-geoserver kartoza/geoserver:2.15.2

Create a Zika Workspace¶

name: zika

namespace URI: https://zika.devops.launchcode.org

you do not need to check either of the boxes (default, isolated)

Configure a PostGIS Data Store¶

• Create a PostGIS data store using the Zika PostGIS database credentials. If you are running the launchcodedevops/zika database container then the following credentials can be used:
  • name: zika
  • host: localhost
  • port: 5432
  • username: zika_user
  • password: zika

Create a View Layer¶

• Create a new layer from the locations_with_cases_by_date view
  • Make sure Native and Declared SRS are set to EPSG:4326
  • For Native Bounding Box, click on Compute from data
  • For Lat/Lon Bounding Box, click on Compute from native bounds

Updating OpenLayers Code¶

Following the OpenLayers example for querying GetFeature, update your OpenLayers code to query GeoServer to get locations with report totals by date. You’ll need to use the ol.format.filter.equalTo filter.

Docker Compose Deployment¶

If you want to gain more advanced practice with Docker you can also consider using docker-compose to deploy everything within a single EC2 instance. This approach creates a back-end stack which runs the primary Zika API and Geoserver services along with the backing services of the PostGIS and Elasticsearch databases. Your VPC will be simplified by only requiring a single instance. Once you have it working you can safely remove the previous EC2 instances.

You will want to refer to the docker-compose file reference along with the practice project covered in the prep weeks to develop your compose file. Remember that writing a compose file is like writing a script for running several containers at once. Think about the options you use when running each container manually with docker run ... then translate those into service definitions.

FROM launchcodedevops/openjdk8-jre

# expects app.jar to be in the same directory as this Dockerfile
COPY app.jar app.jar

CMD [ "java", "-jar", "app.jar" ]

You can use the following commands to test and manage the compose stack:

# issue these from within the directory with the docker-compose.yml file

# test the compose file for errors - if no errors are found the file contents will be printed
$ docker-compose config

# start up the stack in detached mode
$ docker-compose up -d

# shut down the stack
$ docker-compose down

# view stack containers
$ docker-compose ps

# view memory usage of all containers in the stack
# thanks to https://github.com/docker/compose/issues/1197#issuecomment-405207016
$ docker-compose ps -q | xargs docker stats

Geoserver Elasticsearch Integration¶

Check out the ElasticGeo Plugin. It is an Elasticsearch plugin that allows you to integrate Elasticsearch into GeoServer. The great thing is that you can do Elasticsearch queries directly through GeoServer via WFS calls. Here are the setup instructions and instructions on how to make the calls: ElasticGeo Instructions