Deployment of the BPE using Github Registry Images

Before deployment you have to get two certificates from the DFN PKI:

• Server X.509 certificate (DFN profile Web Server) for the FHIR server
• Server/Client X.509 certificate (DFN profile 802.1X Client) for the local Business Process Engine to access FHIR servers and for your FHIR server to perform HTTP HEAD calls to remote FHIR servers while validating incoming FHIR resources with references to remote FHIR servers.

Create a deployment folder named bpe_compose (for example) and copy the content of the folder dsf-docker-test-setup ▸ ⁨bpe into it to get a head start on configuring your setup.

Reverse-Proxy

• Add the CA chain, the BPE Server/Client Certificate and the BPE Server/Client Certificate Private Key to the folder bpe_compose ▸ ⁨proxy⁩ ▸ ssl:
• Filenames have to be:
  • ca_certificate.pem for the CA chain
  • certificate.pem for the server certificate
  • private-key.pem for the server certificate private key
• You can find the current DFN PKI CA chain here. All entries are needed since the ca_certificate.pem file is currently use to configure the servers intermediate CAs and the CA Root for trusting client certificates.

Database

• Adapt bpe_compose ▸ ⁨⁨app⁩ ▸ ⁨conf⁩ ▸ config.properties with a new org.highmed.dsf.bpe.db.liquibase_user_password and org.highmed.dsf.bpe.db.server_user_password
• Add the org.highmed.dsf.bpe.db.liquibase_user_password to bpe_compose ▸ ⁨db ▸ conf ▸ ⁨postgress_password⁨

App

• Create a .p12 keystore of the local Business Process Engine server/client certificate using openssl pkcs12 -export -out [client_certificate.p12] -inkey [private-key.pem] -in [client_certificate.pem] -certfile [chain.txt] and move it into ⁨⁨bpe_compose ▸ ⁨app⁩ ▸ ⁨conf⁩
• You can find the current DFN PKI CA chain here. The full chain is needed since the .p12 store is used as trust-store to authenticate the server and as certificate key-store while authenticating as client. The root anchor (T-TeleSec GlobalRoot Class 2) is used to trust the server, when the server authenticates himself - transmitting all intermediate CAs with the server certificate to the client. The intermediate certificates together with the client certificate and its corresponding private key are used while the client is authenticating himself against a server, transmitting all intermediate CAs together with the client certificate to the server.

WATCH OUT: If the application runs on a machine behind a proxy using TLS Inspection, authentication based on client certificates will not work. TLS Inspection has to be turned off.

• Adapt the following settings in the file bpe_compose ▸ ⁨app⁩ ▸ ⁨conf⁩ ▸ config.properties:
  • org.highmed.dsf.bpe.fhir.local.webservice.baseUrl for the FHIR webservice interface
  • org.highmed.dsf.bpe.fhir.local.websocket.url for the FHIR websocket interface
  • keystore.p12file and the keystore.password for both, org.highmed.dsf.bpe.fhir.local.webservice and org.highmed.dsf.bpe.fhir.local.websocket
  • org.highmed.dsf.bpe.db.camunda_user_password with a new password
  • org.highmed.dsf.bpe.fhir.organization.identifier.localValue with the MeDIC identifier
• If outgoing connections use a proxy, additionally uncomment and change the settings:
  • org.highmed.dsf.bpe.fhir.remote.webservice.proxy.schemeHostPort with the proxy protocol, url and port
  • org.highmed.dsf.bpe.fhir.remote.webservice.proxy.proxy.username
  • org.highmed.dsf.bpe.fhir.remote.webservice.proxy.proxy.password
• Settings of the Jetty application server can be changed in the file bpe_compose ▸ ⁨app⁩ ▸ ⁨conf⁩ ▸ jetty.properties
• If there are additional processes to be deployed, drop them packaged as jar in the folder bpe_compose ▸ ⁨app⁩ ▸ plugin
• Make sure volumes can be accessed. The Application is run by a user with uid==gid==2202. That means that this user has to be able to read the conf and plugin folder and to read+write+execute the log folder.

Processes

Processes are developed independently of the Data Sharing Framework and must be included during deployment. This is done by adding the corresponding processes jars to the folder bpe_compose ▸ ⁨app⁩ ▸ process.

The processes for the HiGHmed consortia can be found as part of the release assets in the repository highmed-processes. The following processes are available:

• dsf-bpe-process-feasibility-<version>.jar
• dsf-bpe-process-local-services-<version>.jar
• dsf-bpe-process-ping-<version>.jar
• dsf-bpe-process-update-allow-list-<version>.jar
• dsf-bpe-process-update-resources-<version>.jar

It is possible to exclude or retire sub-processes from deployment by using the properties org.highmed.dsf.bpe.process.excluded and org.highmed.dsf.bpe.process.retrired in bpe_compose ▸ ⁨app⁩ ▸ ⁨conf⁩ ▸ config.properties. If the above processes are deployed, we suggest that a HiGHmed organization of type MeDIC excludes the following sub-processes:

• computeFeasibility/<version>
• computeDataSharing/<version>
• requestUpdateResources/<version>
• updateAllowList/<version>

openEHR Client

The openEHR client can be selected by uncommenting the setting org.highmed.dsf.bpe.openehr.webservice.factory.class in the file bpe_compose ▸ ⁨app⁩ ▸ ⁨conf⁩ ▸ config.properties and adding the client jar to the folder bpe_compose ▸ ⁨app⁩ ▸ plugin. If the setting remains commented, a default client stub implementation will be used.

The codebase contains the following clients:

• org.highmed.openehr.client.impl.OpenEhrClientJerseyFactory

Master Patient Index Client

The Master Patient Index client can be selected by uncommenting the setting org.highmed.dsf.bpe.mpi.webservice.factory.class in the file bpe_compose ▸ ⁨app⁩ ▸ ⁨conf⁩ ▸ config.properties and adding the client jar to the folder bpe_compose ▸ ⁨app⁩ ▸ plugin. If the setting remains commented, a default client stub implementation will be used.

The codebase contains the following clients:

• org.highmed.mpi.client.pdq.MasterPatientIndexClientPdqFactory

Docker-Compose Configuration

Adapt the file ⁨⁨docker-compose.yml:

• Adapt the entry HTTPS_SERVER_NAME_PORT with the permanent redirect url for https (:)
• If the BPE is located on its own machine without the FHIR Endpoint:
  • Remove the network entries with the name fhir_bpe
  • Adapt the ports to of the entry proxy ▸ ports to 80:80 and 443:443
• Replace the entry of services ▸ proxy ▸ image with ghcr.io/highmed/bpe_proxy:latest
• Replace the entry of services ▸ app ▸ image with ghcr.io/highmed/bpe:latest

Adapt the file ⁨docker-compose.prod.yml:

• If you need additional entries in the file /etc/hosts (e.g. if the external access ip/domain-name mapping for the local FHIR server is different then the internal network ip/domain-name mapping) add them to the field extra_hosts

Running

Make sure the fhir server is already running, since importing the processes at your first startup will also deploy the processes on the fhir server.

Run docker-compose -f docker-compose.yml -f docker-compose.prod.yml up to start the reverse-proxy, database and app servers.

With a single docker-compose.yml file you can start the server using docker-compose up -d && docker-compose logs -f. This command will start the servers detached and then follows log outputs on screen. Issuing ctrl-c will end log output but won't stop the servers.