Mintaka

Mintaka is an implementation of the NGSI-LD temporal retrieval api. It relies on the Orion-LD Context Broker to provide the underlying database.

⚠️ See the Compatibility-Matrix for information about compatible Orion and Mintaka versions.

The NGSI-LD specification is a living, changing document, and the latest Orion-LD beta release is nearly feature complete to the 1.3.1 ETSI specification.

This project is part of FIWARE. For more information check the FIWARE Catalogue entry for Core Context.

🐳 Docker Hub	📚 Java Doc

Table of contents

• Build & Install
  • Build
    • Jar
    • Docker
  • Install
    • Preconditions
    • How-to-run
    • Configuration
    • Operations
• Testing
  • Coverage
  • Static analyzes
• Documentation
• API-Remarks
  • Pagination

Build and Install

Build

The project is build using maven.

Jar

In order to create a working jar file, run: mvn clean install

Docker

For building a new docker container, the usage of the jib-plugin is recommended. Build the image locally via: mvn clean install jib:dockerBuild

If for some reasons required, a plain dockerfile can be used to build: docker build -t my-custom-image -f docker/Dockerfile . and run: docker run my-custom-image

Install

Preconditions

Mintaka should be viewed as a component of Orion-LD and therefore has no mechanism for populating the database itself. It relies on a TimescaleDB installation(including the Postgis extension), that is populated by Orion-LD. For installing Orion-LD, see the Installation-guide, for Timescale we recommend the Timescale-Postgis image for Postgres 12. Working docker-compose setups can be found at the test-folder.

How-to-run

Start mintaka via docker run fiware/mintaka.

Configuration

We recommend to run mintaka with the provided docker container.
Since mintaka is built using the Micronaut-Framework all configurations can be provided either via configuration file (application.yaml) or as environment variables. For detailed information about the configuration mechanism, see the framework documentation.

The following table concentrates on the most important configuration parameters for Mintaka:

Property	Env-Var	Description	Default
micronaut.server.port	MICRONAUT_SERVER_PORT	Server port to be used for mintaka	8080
micronaut.metrics.enabled	MICRONAUT_METRICS_ENABLED	Enable the metrics gathering	true
endpoints.all.port	ENDPOINTS_ALL_PORT	Port to provide the management endpoints	8080
endpoints.metrics.enabled	ENDPOINTS_METRICS_ENABLED	Enable the metrics endpoint	true
endpoints.health.enabled	ENDPOINTS_HEALTH_ENABLED	Enable the health endpoint	true
datasources.default.host	DATASOURCES_DEFAULT_HOST	Host of timescale	localhost
datasources.default.port	DATASOURCES_DEFAULT_PORT	Port of timescale	5432
datasources.default.database	DATASOURCES_DEFAULT_DATABASE	Name of the default database, needs to coincide with orion-ld	orion
datasources.default.username	DATASOURCES_DEFAULT_USERNAME	Username to be used for db connections	orion
datasources.default.password	DATASOURCES_DEFAULT_PASSWORD	Password to be used for db connections	orion
loggers.levels.ROOT	LOGGERS_LEVELS_ROOT	Root log level of mintaka	ERROR
basepath	BASEPATH	The basepath to be used for the api. Could for example be /ngsi-ld/v1	``

Operations

Mintaka provides the micronaut management api. If not configured differently, the health endpoint will be available at https://<MINTAKA_HOST>:9090/health and metrics at https://<MINTAKA_HOST>:9090/metrics. For all available options, please check the framework documentation.

Testing

Since Mintaka relies on the database to be populated by Orion-LD, the testsuite is built around a docker-compose setup including Orion-LD. The tests use testcontainers and JUnit-5.

Test can be executed via: mvn clean test

Coverage

Code-coverage reports are automatically created by Jacoco when the test are executed by maven. Public reports are available at Coveralls.io.

Static analyzes

Static code analyzes("linting") are provided via Spotbugs. Reports can be created via: mvn -B verify spotbugs:spotbugs -DskipTests

Documentation

The code is documented in the Javadoc comments format and automatically published from the main branch to: https://fiware.github.io/mintaka/

API-Remarks

The API complies with the NGSI-LD spec version 1.3.1.

OpenAPI

Mintaka uses a modified version of the NGSI-LD OpenAPI-Spec that can be found in the api folder. Models and Interfaces are generated by the Micronaut-OpenAPI-Codegenerator. Only the tag "Temporal Retrieval" is implemented since all other tags are in scope of Orion-LD. It's necessary to use a modified spec here, since the underlying Java-Codegenerator does not properly support the OpenAPI "oneOf" structure, which is heavily used in the api.

Pagination

The api supports two dimensions of pagination.

The first one is similar to the normal query api and compliant with the NGSI-LD spec (see 5.5.9):

• retrieval of entities is automatically limited to a default pageSize (100)
• the id of the next-page anchor will be returned via the header "Next-Page"
• the id of the previous-page anchor will be returned via the header "Previous-Page"
• the page-size will be returned via the header "Page-Size"
• "Next-Page" will not be returned for the last page
• "Previous-Page" will not be returned for the first page
• the parameters "pageAnchor" and "pageSize" can be used for requesting pages

The second one limits the retrieval of temporal instances and will be described in section 6.3.10 of future NGSI-LD api releases. It automatically limits the number of returned instances and responds with Http-Status 206 "PARTIAL-CONTENT". The returned range is described in the "Content-Range" header.

Contribution

Please check the contribution documentation for more information