kuubu Backend Service
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
Requirements
Build
- Java Development Kit (JDK) 17+
- Apache Maven 3.5+
- Docker 4.0+
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 theProjects
domain -
projects-rest
: REST adapter for theProjects
domain -
projects-platform
: SLR platform adapter for theProjects
domain - ...
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 differentcore
modules. -
/commons-rest
Maven module with functionalities often needed by differentrest
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.
-
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
-
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/
. -
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 thegeneric
Variant profile. Additional configuration values are set by the tests. -
integration-test
Used by failsafe maven plugin during test execution together with thegeneric
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 totarget/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.