Configuration

In a production environment, your application server would typically be run containerized in a Docker or Kubernetes context. As such, environment variables would either be set by your Docker Compose files, or Kubernetes deployment manifests.

Modlet Environment Variables

This section only covers GIS specific modlet environment variables. The Web Base environment variables still apply.

Environment Variable	Example Value
GIS_URL	http://gis-app:8080
PUBLIC_RTUS_SEH_URL	http://rtus-seh.127.0.0.1.nip.io
PUBLIC_GIS_RTUS_MAP_NAME	gis

GIS_URL

The URL to the GIS service

The base URL to call the GIS service endpoints. The modlet in the web server is responsible for making these calls, though you can use this base URL to make calls to the GIS service yourself as well.

PUBLIC_RTUS_SEH_URL

The URL to the RTUS - SEH

This URL is used by the browser to establish a connection to the SSE server (RTUS - SEH) to receive server-sent events.

PUBLIC_GIS_RTUS_MAP_NAME

The name of the RTUS map to access

This map refers to the Map datastructure, not a geospatial map. The RTUS provides a distributed map for other services to access and receive values via realtime updates. This map is used to namespace where the GIS service stores its data. For the GIS, we use the value gis, but this can be any name you want as long as it matches the map name configuration in the GIS service.

Service Environment Variables

As GIS service is a Java Spring application, it can be configured with many Spring-specific environment variables. However, we will only cover the ones you're highly likely to change. You can view the official Spring documentation on what common application properties can be added.

Environment Variable	Example Value
server.port	8080
spring.datasource.url	jdbc:postgresql://gis-db:5432/gis?currentSchema=gis
spring.datasource.username	postgres
spring.datasource.password	postgres
spring.liquibase.default-schema	gis
spring.liquibase.change-log	classpath:db/changelog/db.changelog-master.xml
spring.jpa.properties.hibernate.default_schema	gis
gis.keycloak.url	http://iams-keycloak:8080
gis.iams.aas.url	http://iams-aas:8080
gis.rtus.url	http://rtus-pms:8080
gis.active-tenant.claim-key	active_tenant
gis.rtus.map_name	gis
gis.batch-limit	1000
gis.puts-ignore-occ-lock	true

server.port

The server HTTP port to serve requests on

This is a server property from Spring, it defaults to 8080.

spring.datasource.url

The JDBC URL of the database - this should be a database connection string

https://docs.spring.io/spring-boot/appendix/application-properties/index.html#application-properties.data.spring.datasource.url

spring.datasource.username

Login username of the database

Official Spring Docs

spring.datasource.password

Login password of the database

Official Spring Docs

spring.liquibase.default-schema

The default database schema

PostgreSQL namespaces tables in the database with "schemas", we have a pre-liquibase script that runs before liquibase to create a schema if it does not already exist using the spring.liquibase.default-schema property.

This value should match with whatever you set for spring.jpa.properties.hibernate.default_schema, our convention is to use the module's short name for schemas. So for the GIS, we use gis as this value.

Official Spring Docs

spring.liquibase.change-log

Change log configuration path

We use liquibase to help with database schema migration and versioning. If you are unsure of how to use liquibase's changelogs, just use the default value classpath:db/changelog/db.changelog-master.xml.

• Official Liquibase Changelog Docs
• Official Spring Docs

spring.jpa.properties.hibernate.default_schema

This allows hibernate to use the correct schema for unqualified table names

This value should match with whatever you set for spring.liquibase.default-schema, our convention is to use the module's short name for schemas. So for the GIS, we use gis as this value.

• Official Hibernate Docs
• Official Spring Docs

gis.keycloak.url

The URL to the IAMS - Keycloak service

This GIS determines the appropriate realm based on the information in the JWT access tokens provided, so the URL to Keycloak server is sufficient.

gis.iams.aas.url

The URL to the IAMS - AAS service

The base URL in order for the GIS to call the IAMS - AAS endpoints.

gis.rtus.url

The URL to the RTUS - PMS service

This base URL in order for the GIS to call the RTUS - PMS endpoints. The RTUS - PMS is called whenever the GIS needs to send update events through the Real-time Update Service.

gis.active-tenant.claim-key

This key to use when accessing the active tenant in the JWT's claims

The GIS service decodes and processes the JWT's received. Within the claims, it expects to find an active tenant. This configuration is for the GIS to understand what key should be used to access the value in the claims.

For example, if you Keycloak configuration maps the active tenant claim to:

{
    "smelly_socks": "the_active_tenant_name"
}

Then, the gis.active-tenant.claim-key should be smelly_socks. Our typical configuration uses active_tenant as the claim key.

gis.rtus.map_name

The name of the RTUS map to access

This map refers to the Map datastructure, not a geospatial map. The RTUS provides a distributed map for other services to access and receive values via realtime updates. This map is used to namespace where the GIS service stores its data. For the GIS, we use the value gis, but this can be any name you want as long as it matches the map name configuration in the GIS modlet (as it must connect to the right RTUS - SEH map).

gis.batch-limit

The batch request size limit

It is dangerous to allow unlimited batch requests, this size limit prevents users from making very large queries and causing potential system down-time. We use 1000 in our testing.

gis.puts-ignore-occ-lock

Flag to control whether OCC Lock is ignored

The GIS service uses an optimistic concurrency control lock field to lock rows from updates if the values passed in are outdated.

Because the freshness of GIS data is of high importance, and data for tracks tends to be streamed in at regular intervals, one use-case is to simply continuously or upsert into the GIS (using the PUT endpoints), without the desire to track if the existng data is newer. For this reason, this flag exists to allow users to disable the OCC locking mechanism for upserts.

warning

Be warned that the repercussions for ignoring these checks whilst scaling the service horizontally can result in inconsistencies with the data.