Skip to content
Snippets Groups Projects
user avatar
Smarte.Land.Regionen dev authored
302a85f0
History

kuubu Backend Service

Logo

License

This project is licensed under the terms of the Apache License 2.0. Further information on the license can be found in the LICENSE file.

Overview

Overview

Requirements

Build

Run

Build and Test

mvn clean install

Run

cd application
mvn spring-boot:run

Architecture

The backend uses the "Onion Architecture" pattern to achieve a better separation of concerns and thus better maintainability, testability.

The main difference to classic layered architecture is that onion architecture puts the business logic in the center and not the infrastructure.

Modularization

A separate Maven module is created for each domain, for the core layers (domain models, domain services and application services) together, as well as for the different adapters (external services).

The module name is derived from the domain name and core for the core layers or the adapter name. For adapters that fulfill cross-cutting concerns, the domain name is omitted.

Example:

  • projects-core: domain models, domain services and application services for the Projects domain
  • projects-rest: REST adapter for the Projects domain
  • projects-platform: SLR platform adapter for the Projects domain
  • ...

Dependency Graph

Dependency Graph

Directory Structure

Beside the mentioned core and adapter modules, there are other modules:

  • /application Maven module for the executable service application. Integrates the individual modules and also includes the integration tests.
  • /build Maven module that contains only shared configuration files required by all modules at build time for static analysis.
  • /commons-core Maven module with functionalities often needed by different core modules.
  • /commons-rest Maven module with functionalities often needed by different rest adapter modules.
  • /coverage Maven module that serves exclusively for aggregation of coverage data of the individual Maven modules. New modules must be added as a dependency to this pom.xml so that they appear in the coverage report.
  • /docs Additional files of the project documentation such as images or diagrams.
  • /parent Maven module that contains the parent POM for all modules. All dependency versions, Maven plugins and profiles are preconfigured there.

Developer Guidelines

See Confluence page Lösung 2: Developer Guidelines

Common Tasks

Generate Liquibase Changelog

Create a Liquibase changelog between JPA entities defined in the project artifacts and the schema from a local PostgreSQL database.

  1. Ensure that all project artifacts are up-to-date

    mvn install -Dmaven.test.skip=true --activate-profiles !coverage,!security-check,!static-analysis,!error-prone,!license-check,!generate-openapi
  2. Generate Liquibase changelog

    To make sure that the database schema has been updated to the latest version, start the backend service once before with the profile local.

    cd application
    mvn liquibase:diff@to-local-db -Dspring.profiles.active=local -Dliquibase.password=<db password>

    The generated changelog file is then located at application/src/main/resources/db/changelog/.

  3. Copy the change sets from the generated changelog into the master changelog at application/src/main/resources/db/changelog/db.changelog-master.xml

Note Only JPA entities that are in a subpackage of de.fhg.iese.slr.solution2.backend are considered.

Profiles

Spring

For security reasons, secrets should not be specified in these profiles but should be passed at runtime via external configuration such as Kubernetes Secrets or application properties.

Environment

The environment profiles configure the application for a specific use case.

  • local To run on the local machine. Requires locally running instances of PostgreSQL, MongoDB and optionally a mail server. In addition, one profile each from the Variant and Platform categories must be activated.
  • kubernetes To run in the Kubernetes cluster. In addition, one profile each from the Variant and Platform categories must be activated and additional properties must be set.
  • test Used by surefire maven plugin during test execution together with the generic Variant profile. Additional configuration values are set by the tests.
  • integration-test Used by failsafe maven plugin during test execution together with the generic Variant profile. Additional configuration values are set by the tests.

Variant

  • generic To configure the backend as generic variant used by tests
  • solution2 To configure the backend as variant for solution 2 kuubu (Gemeinschaft und Ehrenamt)
  • solution3 To configure the backend as variant for solution 3 LANDwohl (Gesundheit und Pflege)

Platform

  • development To use the development environment of the SLR platform
  • stage To use the stage environment of the SLR platform
  • production To use the production environment of the SLR platform

Misc

  • extended-logging Lower log level and additional log output of SQL statements
  • pretty-print Formats and sorts the output of JSON for better comparability

Additional Properties

For some configuration properties, the values cannot be set in a profile, because their value depends on a combination of profiles or on the concrete deployment. Therefore, the values for these properties must be injected additionally. For example, via environment variables.

Config
Config Property Description
geocoding-service.url Base URL of the Nominatim service
platform.callback.url Publicly accessible URL of the solution backend
spring.data.mongodb.authentication-database
spring.data.mongodb.database
spring.data.mongodb.host
spring.datasource.url
spring.mail.host
Secrets
Config Property Description
platform.callback.key
platform.client.client-secret Secret of the confidential client from Keycloak
spring.datasource.password
spring.datasource.username

Maven

  • coverage Collects code coverage information during test execution via Jacoco
  • static-analysis Performs static code analysis with Spotbugs, PMD, Checkstyle and Forbidden API Checker
  • security-check Checks the used dependencies for vulnerability via OWASP Dependency-Check
  • license-check Checks the licenses of the dependencies used
  • generate-sbom Generates a Software Bill of Materials (SBOM)
  • generate-openapi Exports the OpenAPI definition as JSON file to target/openapi.json

Commandline Parameters

  • --update-gps Updates the internally stored GPS positions of all address data during the start of the service.
  • --update-plain-text Updates the internally stored plain text variant of html data during the start of the service.
  • --shutdown Stops the service automatically after the start.

FAQ

Creating projects

Creating projects for the backend is currently only possible directly in the PostgreSQL database. To create a project, a new row must be added to the project table.

Use of Cookies

We use Matomo Analytics to analyze and evaluate the use of our platform. The insights help us to improve our offerings and make them more relevant for you.

You can choose whether to allow us to process your data for these purposes and set the corresponding cookies. For more information about data protection — especially regarding "Cookies" and "Matomo"— please refer to our Privacy Policy. You can withdraw your consent at any time.