This repository is part of the overarching CatenaX project.
BPDM stands for business partner data management. This project lets other CatenaX services query, add and change base information on CatenaX business partners.
The BPDM application is released in multiple stages. Currently, these are the available environments:
| Description | Link | |
|---|---|---|
dev |
Environment for testing newly developed BPDM features |
|
int |
Environment for running integration tests with other CatenaX services |
BPDM is a SpringBoot Kotlin software project managed by Maven.
The project can be run with the following command: mvn clean spring-boot:run
When running, the project requires a postgresql database to be available to connect to.
Per default configuration the application expects postgres to run on localhost on port 5432.
You can find the standard credentials as well as further database configurations int the application-persist.properties file in the resource folder.
The REST API documentation can be accessed at http://localhost:8080/api/swagger-ui.
-
Maven
-
JDK11
-
PostgreSQL 14.2
-
Keycloak 17.0.0 (with enabled authentication)
-
Connection to CDQ API v4.0 (with enabled CDQ component)
-
OpenSearch 2.1.0 (with enabled OpenSearch component)
The project offers a variety of different Spring profiles for configuration purposes.
What profiles are available and what effect they have configuration properties is described in the application properties files in the resources folder.
Application properties files are separated by concern to increase readability.
application.properties file contains general basic properties while the other files manage properties for major application components that usually can also be enabled or disabled.
Each of the application properties files are multi-documents containing default values for their component as well as value overrides for different environments.
Currently, the application can be run in the following environment profiles:
-
default: when no environment specified
-
local: for the execution on local machine (developer profile)
-
dev: for execution in remote dev environment
-
int: for execution in remote int environment
The following sections detail the configuration properties for each component.
The file application-persist.properties contains the configuration for general persistence and the database connection.
A running Postgres database instance is required (Tested and working on version 14.2), available either locally or remotely depending on the environment.
User credentials need to be provided as environment variable BPDM_DB_PASS.
For environments like int and dev you also have to specify the host on where the postgres database is located in the environment variable BPDM_DB_HOST.
application-auth.properties enables authorization of endpoints and configures the connection to an external Keycloak instance on which the authorization relies on.
Besides the URL of the Keycloak the configuration determines the client credentials to validate incoming tokens (Standard behaviour of this application is bearer-only).
The client secret has to be submitted via environment variable BPDM_KEYCLOAK_SECRET.
This profile also enables/disables the login form in the auto-generated Swagger documentation.
The Swagger login uses the client specified in the property springdoc.swagger-ui.oauth.client-id.
The file application-cdq.properties enables and configures the connection to a remote CDQ API with which the application can exchange business partner information.
Depending on whether this component is enabled, the application offers endpoints to import records from and to export Business Partner Numbers to CDQ.
When enabled the application requires the environment variable BPDM_CDQ_KEY to contain an API key with necessary privileges for accessing the specified storage.
application-opensearch.properties enables/disables and configures the connection to an external OpenSearch instance.
When enabled a running OpenSearch instance is required (Tested on version 2.1.0).
Then the application is able to search and filter business partners by their properties other than identifiers.
Additionally, suggestions for autocompletion can be obtained for each business partner property.
With the activation of the OpenSearch component the application also features new endpoints for exporting business partner records to the OpenSearch instance as well as clearing the current OpenSearch index.
You can specify the URL to connect to over the bpdm.opensearch properties.
On dev and int environment you need to specify the host of the OpenSearch instance with the variable BPDM_OPENSEARCH_HOST.
Without the OpenSearch component enabled the suggestions are always empty and search requests do not filter any business partners.
On default, with no profiles activated, the application persists on a postgresql database with no further dependencies needed.
In order to run the application with a specific profile you can use the appropriate maven flag Dspring.profiles.active.
When specifying an environment all components and properties will be configured for that particular environment.
For development purposes you can also fine tune which component should run in which environment configuration by using the profile of pattern environment_component, e.g. dev_persist.
| Persist | Auth | CDQ | OpenSearch | |
|---|---|---|---|---|
default |
Localhost |
Disabled |
Disabled |
Disabled |
local |
Localhost |
Disabled |
CDQ API v4 Test Storage |
Localhost |
dev |
Host defined in |
CDQ API v4 CatenaX Storage |
Host defined in |
|
int |
Host defined in |
CDQ API v4 CatenaX Storage |
Host defined in |
-
Run application on default configuration:
mvn clean spring-boot:run -
Run on local environment:
mvn clean spring-boot:run -Dspring.profiles.active=local -
Run in general default environment against dev environment CDQ Api:
mvn clean spring-boot:run -Dspring.profiles.active=dev_cdq -
Run in general local environment against dev environment CDQ Api:
mvn clean spring-boot:run -Dspring.profiles.active=local,dev_cdq -
Configure each component’s environment separately:
mvn clean spring-boot:run -Dspring.profiles.active=local_opensearch,dev_auth,int_cdq
The root of the project is reserved for basic repository files and the Maven project file (pom.xml). The source folder is split between test and application files. Source code files are in the kotlin subdirectory (analogous to java source folders). Additional files such as configuration files can be found in the resources subdirectory.
As per Spring framework’s default structure the domain model and persistence object information is encapsulated in entities.
Each entity in the project derives from the BaseEntity type which contains standard fields/columns such as identifier and timestamps.
Services describe the business logic of the application. They primarily work on entities but may also map such entities to data transfer objects (DTOs) which are needed for communication with outside systems. Most important DTOs are request and response objects which describe the model of the application’s API.
Repositories describe the interface with the persistence layer and should be used by the services to gather and save records from the database. Where possible repositories should be defined as interfaces and auto-implemented by Spring Data JPA. In cases when that is not feasible custom repositories can be defined.
Configuration classes configure the services and components in the application. Such configuration classes enable or disable component logic on startup. They are supplemented by the configuration properties. These property classes contain values obtained from the application.properties files and are available via dependency injection. When possible, configuration classes services and components should use configuration properties instead of accessing property values from the application.properties directly. However, in some cases such as conditional activation on configurations by annotation such an approach is not possible and direct access is permissible.
Optional components which require more logic than just simple configuration files are placed in the component package such as the cdq and opensearch component subpackages.
Such a component package is structured again like a mirror of the project structure.
That is, a component package can contain its own repository, service, configuration packages and so on.
By default, the application component scan ignores the component packages.
By enabling the corresponding properties component packages can be included in the component scan.
This repository contains Docker and Helm files for deploying the application to a Kubernetes environment. In order to deploy the application to a Kubernetes Cluster you need to containerize the application, push the resulting image to a container registry and deploy a Helm release on the prepared cluster.
-
A Container Registry (Currently ACR)
-
Kubernetes Ingress Controller (Tested with Ingress-Nginx)
The kubernetes deployment expects a kubernetes environment which already has an Ingress Controller installed in order to be available over ingress routing. Additionally, the ingress works over SSH and expects a Certmanager and Cluster Issuer to be present for obtaining a trustworthy certificate. When the Kubernetes cluster is configured with these components, the application can be deployed with the following steps:
-
Specify your container registry in the Helm values.yaml:
image: registry: your_registry.io
-
Package the application as a jar file:
mvn clean package -
Containerize the packaged application:
docker build -f kubernetes/Dockerfile -t your_container_registry.io/catena-x/bpdm:version . -
Push the image to your registry:
docker push your_container_registry.io/catena-x/bpdm:version -
Install the Helm release on the cluster:
helm install release_name ./kubernetes/bpdm -n your_namespace
When the deployment needs to be updated you can follow the same steps above, except for the last.
In order to update the Helm release you need the Helm upgrade command: helm upgrade release_name ./kubernetes/bpdm -n your_namespace
The instructions above deploys an application configured for the dev environment.
There is also helm configuration available for the int environment, defined in the values-int.yaml.
You would install the application for int environment with: helm install release_name ./charts/pool -n your_namespace -v ./charts/pool/values-int.yaml.
If you want to create a new helm release for a different environment you can create your own values file and adjust the values accordingly.
One of the most important values you want to adjust is in which profile (or profiles) the bpdm service application should run.
This is determined by the springProfiles value:
springProfiles:
- devBe aware that you may also want to replace placeholder passwords for the deployment.
This can be done by giving a values file overriding the password placeholders like so: helm install release_name ./charts/pool -n your_namespace -v secret-values.yaml
secret-values.yaml:
applicationSecret:
keycloak: your_keycloak_secret
cdq: your_cdq_api_key
postgres:
auth:
postgresPassword: your_postgres_user_password
password: your_bpdm_user_passwordIn order to avoid pushing secrets to the Github repository it’s a good practice to pass secret values over command line when deploying a helm release via the set flag like --set applicationSecrets.db-user.secret=some_secret.
You may want to set those secrets on the command line during install or update.
helm install release_name ./charts/pool \
--namespace your_namespace \
--set applicationSecret.keycloak=$BPDM_DB_USER \
--set applicationSecret.cdq=$BPDM_DB_PASS \
--set postgres.auth.postgresPassword=$BPDM_KEYCLOAK_SECRET \
--set postgres.auth.password=$BPDM_CDQ_KEYPrivate container registries may require authentication in order to be accessed. In this case the Helm deployment needs to be given pull secrets to pull the image from such a registry. Pull secrets are specified in the values.yaml like so:
imagePullSecrets:
mail: your_email@your_org.com
user: your_user
password: your_passAs with application secrets instead of writing your credentials directly into a value.yaml you better pass them via command line when deploying the helm release: --set imagePullSecret.user=your_user
Licenses of all maven dependencies need to be approved by eclipse. The Eclipse Dash License Tool can be used to check the license approval status of dependencies and to request reviews by the intellectual property team.
mvn org.eclipse.dash:license-tool-plugin:license-check -Ddash.summary=DEPENDENCIESmvn org.eclipse.dash:license-tool-plugin:license-check -Ddash.iplab.token=<token>Check the Eclipse Dash License Tool documentation for more detailed information.