Stellio context broker
Stellio is an NGSI-LD compliant context broker developed by EGM. NGSI-LD is an Open API and Datamodel specification for context management published by ETSI.
Stellio is a FIWARE Generic Enabler. Therefore, it can be integrated as part of any platform βPowered by FIWAREβ. FIWARE is a curated framework of open source platform components which can be assembled together with other third-party platform components to accelerate the development of Smart Solutions. For more information check the FIWARE Catalogue entry for Core Context. The roadmap of this FIWARE GE is described here.
You can find more info at the FIWARE developers website and the FIWARE website. The complete list of FIWARE GEs and Incubated FIWARE GEs can be found in the FIWARE Catalogue.
Overview
Stellio is composed of 3 business services:
- Entity service is in charge of managing the information context, it is backed by a neo4j database
- Search service is in charge of handling the temporal (and geospatial) queries, it is backed by a TimescaleDB database
- Subscription service is in charge of managing subscriptions and subsequent notifications, it is backed by a TimescaleDB database
It is completed with:
- An API Gateway module that dispatches requests to downstream services
- A Kafka streaming engine that decouples communication inside the broker (and allows plugging other services seamlessly)
The services are based on the Spring Boot framework, developed in Kotlin, and built with Gradle.
Quick start
A quick way to start using Stellio is to use the provided docker-compose.yml
file in the root directory (feel free to change
the default passwords defined in the .env
file):
docker-compose up -d && docker-compose logs -f
It will start all the services composing the Stellio context broker platform and expose them on the following ports:
- API Gateway: 8080
- Entity service: 8082
- Search service: 8083
- Subscription service: 8084
Please note that the environment and scripts are validated on Ubuntu 19.10 and MacOS. Some errors may occur on other platforms.
We also provide an experimental configuration to deploy Stellio in a k8s cluster (only tested in Minikube as of now). For more information, please look at the README
Development
Developing on a service
Requirements:
- Java 17 (we recommend using sdkman! to install and manage versions of the JDK)
To develop on a specific service, you can use the provided docker-compose.yml
file inside each service's directory, for instance:
cd entity-service
docker-compose up -d && docker-compose logs -f
Then, from the root directory, launch the service:
./gradlew entity-service:bootRun
Running the tests
Each service has a suite of unit and integration tests. You can run them without manually launching any external component, thanks to Spring Boot embedded test support and to the great TestContainers library.
For instance, you can launch the test suite for entity service with the following command:
./gradlew entity-service:test
Building the project
To build all the services, you can just launch:
./gradlew build
It will compile the source code, check the code formatting (thanks to ktLint) and run the test suite for all the services.
For each service, a self executable jar is produced in the build/libs
directory of the service.
If you want to build only one of the services, you can launch:
./gradlew entity-service:build
Code quality
Code formatting and standard code quality checks are performed by ktLint and Detekt.
ktLint and Detekt checks are automatically performed as part of the build and fail the build if any error is encountered.
If you use IntelliJ:
- You can generate the corresponding ktLint settings with the following command:
./gradlew ktlintApplyToIdea
-
You may consider using a plugin like Save Actions that applies changed code refactoring and optimized imports on a save.
-
You can enable Detekt support with the Detekt plugin.
Working locally with Docker images
To work locally with a Docker image of a service without publishing it to Docker Hub, you can follow the below instructions:
- Build a tar image:
./gradlew entity-service:jibBuildTar
- Load the tar image into Docker:
docker load --input entity-service/build/jib-image.tar
- Run the image:
docker run stellio/stellio-entity-service:latest
Usage
To start using Stellio, you can follow the API quick start.
Further resources
For more detailed explanations on NGSI-LD or FIWARE:
License
Stellio is licensed under APL-2.0.
It mainly makes use of the following libraries and frameworks (dependencies of dependencies have been omitted):
Library / Framework | Licence |
---|---|
Spring | APL v2 |
JSON-LD Java | BSD-3 Clause |
Reactor | APL v2 |
Jackson | APL v2 |
JUnit | EPL v2 |
Mockk | APL v2 |
JsonPath | APL v2 |
WireMock | APL v2 |
Testcontainers | MIT |
Neo4j OGM | APL v2 |
Β© 2020 - 2022 EGM