BPDM offers Helm Charts, Dockerfiles and configuration files to support the installation process of the BPDM applications. The following chapters show how to install the applications in different scenarios.
- JAVA 21
- Maven (3.9 supported)
- Docker Engine (tested on 26.1.2)
- Docker Compose (tested on 2.27.0)
BPDM services require a PostgreSQL database and Keycloak server to run. Navigate to the root folder of the BPDM repository. Then set up the necessary dependencies by using the provided Docker Compose file:
docker compose -f docker/compose/dependencies/docker-compose.yml up -d This will run a Postgres and Keycloak with an initial realm already configured to be used by the BPDM services. You will need to pass the necessary client secrets when starting the BPDM services. Those client secrets are generated by Keycloak after the first time setup. Therefore, we will log in to the Keycloak server, look-up the secrets and write them into environment variables that are read by the BPDM services.
- Log in to Keycloaks admin console with the admin credentials (default in the Docker Compose file): http://localhost:8180/admin/master/console
- Navigate to realm "Cx-Central"
- Navigate to the following clients and write the client secret to the environment variable:
| Client | Environment Variable |
|---|---|
| DUMMY-ORCHESTRATOR-TASK_PROCESSOR | BPDM_DUMMY_ORCH_CLIENT_SECRET |
| GATE-ORCHESTRATOR-TASK_CREATOR | BPDM_GATE_ORCH_CLIENT_SECRET |
| GATE-POOL-SHARING_MEMBER | BPDM_GATE_POOL_CLIENT_SECRET |
| POOL-ORCHESTRATOR-TASK-PROCESSOR | BPDM_POOL_ORCH_CLIENT_SECRET |
This information on what client expects which environment variable is also available in the application properties files of the respective BPDM applications (like for the gate) Now, make sure that client secrets are available in the expected environment variables:
export BPDM_DUMMY_ORCH_CLIENT_SECRET=...
export BPDM_GATE_ORCH_CLIENT_SECRET=...
export BPDM_GATE_POOL_CLIENT_SECRET=...
export BPDM_POOL_ORCH_CLIENT_SECRET=...After this step, we can finally build, install the BPDM applications.
mvn clean installEach BPDM application can now be run separately. We will run each application after another. For this, we navigate into the application's subfolder and run the application with the spring-boot run goal.
cd bpdm-orchestrator
mvn spring-boot:run
cd ../bpdm-cleaning-service-dummy
mvn spring-boot:run
cd ../bpdm-pool
mvn spring-boot:run
cd ../bpdm-gate
mvn spring-boot:runAfter this you have full-fledged running BPDM system. As a next step on how to pass business partner data and create golden records you can have a look at the api documentation of this repository.
You may want to perform a quick installation in which security is not necessary.
In this case, you don't need to configure any environment variables.
This means you can directly run the BPDM applications after you set up the necessary dependencies.
Make sure to disable authentication requirements by using the provided no-auth profile when running the applications:
mvn spring-boot:run -Dspring.profiles.active=no-authInstallation of BPDM applications with the Helm Charts has the most software requirements but is the qickest way to set up a running system.
- kubectl (1.30 supported)
- Docker Engine (tested on 26.1.2)
- Minikube (tested on 1.33.0)
- Helm (tested on 3.14.4)
Navigate to the projects root folder. Then install a new release of BPDM on your default namespace via helm:
helm install bpdm ./charts/bpdmThis will install the BPDM applications with its own Postgres and Keycloak in default values. Mind that this will also install the applications with default passwords.
It is good practice to overwrite the default secrets and passwords that are used in the BPDM Charts. For this, you can first define a bunch of environment variables holding new secret values and use them later during deployment:
helm install bpdm \
--set-value postgres.auth.password=$BPDM_POSTGRES \
--set-value keycloak.auth.adminPassword=$BPDM_KEYCLOAK_ADMIN \
--set-value keycloak.bpdm.realm.clientSecrets.cleaningDummyOrchestrator=$BPDM_DUMMY_ORCH_CLIENT_SECRET \
--set-value keycloak.bpdm.realm.clientSecrets.poolOrchestrator=$BPDM_POOL_ORCH_CLIENT_SECRET \
--set-value keycloak.bpdm.realm.clientSecrets.gateOrchestrator=$BPDM_GATE_ORCH_CLIENT_SECRET \
--set-value keycloak.bpdm.realm.clientSecrets.gatePool=$BPDM_GATE_POOL_CLIENT_SECRET \
--set-value bpdm-gate.applicationSecrets.bpdm.client.orchestrator.registration=$BPDM_GATE_ORCH_CLIENT_SECRET \
--set-value bpdm-gate.applicationSecrets.bpdm.client.pool.registration=$BPDM_GATE_POOL_CLIENT_SECRET \
--set-value bpdm-pool.applicationSecrets.bpdm.client.orchestrator.registration=$BPDM_POOL_ORCH_CLIENT_SECRET \
--set-value bpdm-cleaning-service-dummy.applicationSecrets.bpdm.client.orchestrator.registration=$BPDM_DUMMY_ORCH_CLIENT_SECRET\
.charts/bpdm/bpdmFor non-production purposes you may want to install BPDM applications that are not authenticated. All BPDM applications offer a Spring profile to quickly remove all authentication configuration for their APIs and client connections. In this case you can also disable the Keycloak dependency from being deployed.
helm install bpdm \
--set-value keycloak.enabled=false
--set-value bpdm-gate.profiles=["no-auth"] \
--set-value bpdm-orchestrator.profiles=["no-auth"] \
--set-value bpdm-pool.profiles=["no-auth"] \
--set-value bpdm-cleaning-service-dummy.profiles=["no-auth"]
.charts/bpdm/bpdmYou can also more fine-granulary remove authentication on APIs and BPDM client connections. You can refer to the no-auth profile configurations (for example that of the Gate) as a documentation.
The BPDM Charts deploy their own PostgreSQL and Keycloak dependencies. However, for production it is recommended to host dedicated Postgres and Keycloak instances with which the BPDM applications should connect to.
- Postgres (15.4.0 supported)
- Keycloak (22.0.3 supported)
In this case, you can disable the dependencies and configure the connection to external systems in the application configuration.
helm install bpdm \
--set-value keycloak.enabled=false
--set-value postgres.enabled=false
--set-value bpdm-gate.applicationConfig.bpdm.datasource.host=external-db \
--set-value bpdm-gate.applicationConfig.bpdm.security.auth-server-url=http://external-keycloak \
--set-value bpdm-pool.applicationConfig.bpdm.datasource.host=external-db \
--set-value bpdm-pool.applicationConfig.bpdm.security.auth-server-url=http://external-keycloak \
--set-value bpdm-orchestrator.applicationConfig.bpdm.security.auth-server-url=http://external-keycloak \
--set-value bpdm-cleaning-service-dummy.applicationConfig.bpdm.client.orchestrator.provider.issuer-uri= http://external-keycloak/realms/CX-Central \
.charts/bpdm/bpdmYou can configure all BPDM applications over Helm values more fine-granulary via the applicationConfig and applicationSecrets.
Values under these groups are directly injected as application properties in the deployed containers.
As a reference of what can be changed have a look at the respective application properties files of each application:
This section shows how to make your BPDM Gate and Pool APIs available over an EDC. This documentation assumes that you already have running BPDM and EDC deployments. For deploying an EDC please consult the documentation on the EDC repository.
- Running BPDM applications
- Running EDC (0.7.0 supported)
The general idea of configuring data offers for BPDM is to assets which grant access to a portion of the BPDM APIs. Which API resources are accessible over an asset is determined by the purposes defined in the BPDM framework agreement. For some purposes you may need to access business partner output data from the BPDM Gate for example but won't have access to the input data. Blueprints for such assets are documented in this [POSTMAN collection](../postman/EDC Provider Setup.postman_collection.json). Accompanying the asset definitions are Policy and Contract Definition blueprints. Except for a general Access Policy those blueprints are grouped by purpose.
After all assets, policies and contract definitions are configured a sharing company's EDC now can query its available assets and the contract under which they are exposed.
For the most part BPDM applications don't need to be further configured after they started. The BPDM Pool is an exception to that rule. The Pool offers endpoints for operators to regulate available metadata. Metadata are supporting business partner information like legal forms, identifier types or administrative level 1 areas. For example, by adding a range of legal forms operators are able to determine the available legal forms business partners in the Pool can have.
Typically, business partner data references metadata via technical keys. If a technical key does not exist in the respective metadata the Pool rejects the record.
Administrative level 1 areas follows the ISO 3166-2 norm and is filled by default. Such metadata does not need to be added by the operator.
The use case Postman collection shows which metadata can be added and how that is done. Refer to use cases for Operators(O):
- CL: Shows how to add available legal forms
- CIL: Shows how to add available identifier types used for legal entities
- CIA: Shows how to add available identifier types used for addresses
Please note that in the current implementation there are no endpoints to delete metadata. Deletions would need to be done directly in the database.
This work is licensed under the Apache-2.0.
- SPDX-License-Identifier: Apache-2.0
- SPDX-FileCopyrightText: 2023,2024 ZF Friedrichshafen AG
- SPDX-FileCopyrightText: 2023,2024 SAP SE
- SPDX-FileCopyrightText: 2023,2024 Bayerische Motoren Werke Aktiengesellschaft (BMW AG)
- SPDX-FileCopyrightText: 2023,2024 Mercedes Benz Group
- SPDX-FileCopyrightText: 2023,2024 Robert Bosch GmbH
- SPDX-FileCopyrightText: 2023,2024 Schaeffler AG
- SPDX-FileCopyrightText: 2023,2024 Contributors to the Eclipse Foundation
- Source URL: https://github.com/eclipse-tractusx/bpdm