Tiamat

Tiamat is the Stop Place Register. It is used nationally in Norway, and other places. Tiamat is created with technologies like Spring Boot, Hibernate, Postgis, Jersey and Jackson.

Core functionality

NeTEx imports

• Supports different pre steps and merging options for stop places, handling bad data quality.
• Assigns unique IDs to stop places (if desired).
• Validates incoming data against the XML schema.

NeTEx exports

Supports exporting stop places and other entities to the http://netex-cen.eu/ format. There are many options for exports:

• Asynchronous exports to google cloud storage. Asynchronous exports handles large amount of data, even if exporting thousands of stop places.
• Synchronous exports directly returned
• Several export parameters and filtering (ex: query or administrative polygons filtering)
• Exports can be validated against the NeTEx schema, ensuring quality.

GraphQL API

Tiamat provides a rich GraphQL API for stop places, topographic places, path links, tariff zones and so on, support the same parameters as the NeTEx export API. It also supports mutations. So you can update or create entities. There are also graphql processes (named functions) which allows functionality like merging quays or stop places.

A ReactJS Frontend

A frontend for Tiamat is available. It's name is Abzu. See https://github.com/entur/abzu

Supports running multiple instances

Tiamat uses Hazelcast memory grid to communicate with other instances in kubernetes. This means that you can run multiple instances.

Mapping of IDs

After import stop places and assigning new IDs to stop places, tiamat keeps olds IDs in a mapping table. The mapping table between old and new IDs is available through the GraphQL API and a REST endpoint.

Automatic topographic place and tariff zone lookup

Tiamat supports looking up and populating references to tariff zones and topographic places from polygon matches when saving a stop place.

Versioning

Stop places and other entities are versioned. This means that you have full version history of stop places and what person that made those changes. Tiamat also includes a diff tool. This is used to compare and show the difference between two versions of a stop place (or other entity).

Build

mvn clean install

You need the directory /deployments/data with rights for the user who performs the build.

Integration tests

Tiamat uses testcontainers to run integration tests against a real database. To run Testcontainers-based tests, you need a Docker-API compatible container runtime for more detail see https://www.testcontainers.org/supported_docker_environment/

(default profiles are set in application.properties)

Running the service

There are several options for running the service depending on what you need.

• Run locally for development is for people intending to maintain, modify and improve tiamat's source code
• Run tiamat with Docker compose if you just need to get the service running
• Run with external properties file and PostgreSQL for low level debugging

Note! Each of these configurations use unique port numbers and such, be sure to read the provided documentation and configuration files for more details.

Run locally for development

Local development is a combination of using Docker Compose based configuration for starting up the supporting services and running Spring Boot with at least local profile enabled.

When running,

• tiamat will be available at http://localhost:37888
• PostGIS will be available at localhost:37432

1. Start Local Environment through Docker Compose

Tiamat has docker-compose.yml which contains all necessary dependent services for running tiamat in various configurations. It is assumed this environment is always running when the service is being run locally (see below).

Note! This uses the compose version included with modern versions of Docker, not the separately installable docker-compose command.

All Docker Compose commands run in relation to the docker-compose.yml file located in the same directory in which the command is executed.

# run with defaults - use ^C to shutdown containers
docker compose up
# run with additional profiles, e.g. with LocalStack based AWS simulator
docker compose --profile aws up
# run in background
docker compose up -d # or --detach
# shutdown containers
docker compose down
# shutdown containers included in specific profile
docker compose --profile aws down

Supported Docker Compose profiles

Docker Compose has its own profiles which start up additional supporting services to e.g. make specific feature development easier. You may include any number of additional profiles when working with Docker Compose by listing them in the commands with the --profile {profile name} argument. Multiple profiles are activated by providing the same attribute multiple times, for example starting Compose environment with profiles a and b would be

docker compose --profile a --profile b up

The provided profiles for Tiamat development are

| profile | description | |:--------|---------------------------------------------------------------------------------------------------| | aws | Starts up LocalStack meant for developing AWS specific features. |

See Docker Compose reference for more details.

See Supported Docker Compose Profiles for more information on provided profiles.

2. Run the Service

Available Spring Boot Profiles

Note! You must choose at least one of the options from each category below!

Note! local profile must always be included!

Storage

| profile | description | |:-----------------------|-----------------------------------------------------------------------------------------------------------------------------------------------------------------| | gcs-blobstore | GCP GCS implementation of tiamat's blob storage | | local-blobstore | Use local directory as backing storage location. | | rutebanken-blobstore | Use rutebanken-helpers/storage based implementation for storage. Must be combined with one of the supported extra profiles (see below). |

Supported rutebanken-blobstore extra profiles

If this profile is chosen, an additional implementation must be chosen to activate the underlying actual implementation. Supported extra profiles are

| extra profile | description | |:-----------------------|------------------------------------------| | local-disk-blobstore | Similar to local-blobstore. | | in-memory-blobstore | Entirely in-memory based implementation. | | s3-blobstore | AWS S3 implementation. |

Example: Activating in-memory-blobstore for local development

spring.profiles.active=local,rutebanken-blobstore,in-memory-blobstore,local-changelog

See the RutebankenBlobStoreServiceConfiguration class for configuration keys and additional information.

Changelog

| profile | description | |:------------------|--------------------------------------------------------------------| | local-changelog | Simple local implementation which logs the sent events to stdout | | activemq | JMS based ActiveMQ implementation. | | google-pubsub | GCP PubSub implementation for publishing tiamat entity changes. |

Supported Docker Compose Profiles

Tiamat's docker-compose.yml comes with built-in profiles for various use cases. The profiles are mostly optional, default profile contains all mandatory configuration while the named profiles add features on top of that. You can always activate zero or more profiles at the same time, e.g.

docker compose --profile first --profile second up
# or
COMPOSE_PROFILES=first,second docker compose up

Default profile (no activation key)

Starts up PostGIS server with settings matching the ones in application-local.properties.

aws profile

Starts up LocalStack meant for developing AWS specific features.

See also Disable AWS S3 Autoconfiguration, NeTEx Export.

Run It!

IntelliJ: Right-click on TiamatApplication.java and choose Run (or Cmd+Shift+F10). Open Run -> Edit configurations, choose the correct configuration (Spring Boot -> App), and add a comma separated list of desired profiles (e.g. local,local-blobstore,activemq) to Active profiles. Save the configuration.

Command line: mvn spring-boot:run

Run tiamat with Docker compose

To run Tiamat with Docker compose, you need to have a docker-compose.yml file. In docker-compose folder you will find a compose.yml fi