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
spring.datasource.username
Login username of the database
spring.datasource.password
Login password of the database
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.
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.
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.
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
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.
Be warned that the repercussions for ignoring these checks whilst scaling the service horizontally can result in inconsistencies with the data.
* gis.puts-ignore-occ-lock is only available on the pre-release versions (latest-dev tag)!