Skip to content
This repository has been archived by the owner on Nov 17, 2023. It is now read-only.

NUM CODEX DSF 0.4.0 Deployment

Jump to bottom
Hauke Hund edited this page Aug 23, 2023 · 9 revisions

See NUM-CODEX Install 0.9.3 for the latest release.

This setup guide uses pre-build docker images for DSF Version 0.4.0. This guide is not suitable for HiGHmed organizations.

Prerequisites

Virtual Machines

  • DSF FHIR VM: min. 4 GB RAM, 4 vCPU, 20 GB HDD
  • DSF BPE VM: min. 4 GB RAM, 4 vCPU, 20 GB HDD

Docker / Docker-Compose

Both VMs need latest docker and docker-compose. For the latest install guide see https://docs.docker.com/engine/install and https://docs.docker.com/compose/install

docker:

sudo apt-get update
sudo apt-get install apt-transport-https ca-certificates curl gnupg lsb-release
curl -fsSL https://download.docker.com/linux/ubuntu/gpg | sudo gpg --dearmor -o /usr/share/keyrings/docker-archive-keyring.gpg
echo "deb [arch=amd64 signed-by=/usr/share/keyrings/docker-archive-keyring.gpg] https://download.docker.com/linux/ubuntu $(lsb_release -cs) stable" | sudo tee /etc/apt/sources.list.d/docker.list > /dev/null
sudo apt-get update
sudo apt-get install docker-ce docker-ce-cli containerd.io

docker-compose (warning: 1.29.1 might not be latest):

sudo curl -L "https://github.com/docker/compose/releases/download/1.29.1/docker-compose-$(uname -s)-$(uname -m)" -o /usr/local/bin/docker-compose
sudo chmod +x /usr/local/bin/docker-compose

Client/Server Certificates

Two Certificates from the DFN PKI are needed, more infos see Authentication

  • Certificate A: DFN PKI Server Certificate (Profile: 'Web Server', Common-Name: Your external DSF FHIR Servers FQDN)
  • Certificate B: DFN PKI Client Certificate (Profile: '802.1X Client', Common-Name: Your DSF BPE Servers FQDN)

Network setup / Network access

For additional information on the network setup see Network-and-Architecture.

  • The DSF FHIR server needs to be accessible via the internet and able to access the internet without TLS interception.
  • The BPE FHIR server should only be accessible by the internal network and able to access your DSF FHIR server via its external FQDN and the internet without TLS interception.

Here is a quick overview of the expected network setup, connections to the fTTP and the local GECCO FHIR server are not listed:

Source Target Port Protocol
DSF BPE (lokal) DSF FHIR (lokal) 443 https, wss
DSF BPE (lokal) DSF FHIR (GECCO Transfer Hub) 443 https
DSF FHIR (lokal) DSF FHIR (GECCO Transfer Hub) 443 https
DSF FHIR (GECCO Transfer Hub) DSF FHIR (lokal) 443 https

On-Boarding Excel Spreadsheet

Your are required to fill out the on-boarding Excel spreadsheet, provided with the NUM-CODEX hackathon invite, and send it to the GECCO Transfer Hub.

Setup

Prepare Certificates

  1. DFN PKI CA Certificate Chain

  2. Certificate with DFN PKI Profile 'Web Server' (certificate A)
    This certificate will be used as the DSF FHIR servers server certificate (certificate.pem, private-key.pem, ca_certificate.pem)

    • Store PEM encoded certificate as certificate.pem
    • Store not encrypted, PEM encoded private-key as private-key.pem
    • Store DFN PKI CA certificate chain as ca_certificate.pem

  3. Certificate with DFN PKI Profile '802.1X Client' (certificate B)
    This certificate will be used as the DSF BPE servers server certificate (certificate.pem, private-key.pem, ca_certificate.pem), the DSF BPE servers client certificate (client_certificate.p12) as well as the DSF FHIR servers client certificate (client_certificate.p12)

    • Store PEM encoded certificate as certificate.pem
    • Store not encrypted, PEM encoded private-key as private-key.pem
    • Store DFN PKI CA certificate chain as ca_certificate.pem
    • Create client_certificate.p12 file using: openssl pkcs12 -export -out client_certificate.p12 -inkey private-key.pem -in certificate.pem -certfile ca_certificate.pem. The openssl command will ask for a password.

DSF FHIR Server

  1. Add Group/User
    Add group and user used by the DSF FHIR java application. Ubuntu compatible commands below:

    sudo addgroup --gid 2101 fhir
sudo adduser --system --no-create-home --uid 2101 --gid 2101 fhir

  2. Download and Extract Config Files
    Download prepared DSF FHIR server config files and folder structure from https://github.com/highmed/highmed-dsf/wiki/resources/dsf_fhir_0_4_0.tar.gz

    cd /opt
wget https://github.com/highmed/highmed-dsf/wiki/resources/dsf_fhir_0_4_0.tar.gz
sudo tar --same-owner -zxvf dsf_fhir_0_4_0.tar.gz

    The tar command will unpack the config files at /opt/fhir assuming you changed into the /opt directory.

  3. Verify that the fhir system user or group can write into the following folder

    • /opt/fhir/app/log

  4. Modify Config Files

    • /opt/fhir/app/conf/bundle.xml

      • Replace change-me-your-client-certificate-sha512-thumbprint-hex-lowercase-without-colons with the SHA-512 thumbprint of your client certificate (certificate B).
        Use certtool --fingerprint --hash=sha512 --infile=client_certificate.pem to generate the lowercase hex thumbprint without colons of your client certificate (certificate B).
      • Replace change-me-your-organization-identifier.de (line 14) with your organizations DSF identifier (shortest FQDN of your organizations homepage).
      • Replace Change-Me-Your-Organization-Name with your organizations official name.
      • Replace change-me-your-organization-identifier.de (line 33) with your organizations DSF identifier (shortest FQDN of your organizations homepage).

    • /opt/fhir/app/conf/config.properties

      • org.highmed.dsf.fhir.db.liquibase_user_password: Replace change-me-db-password-4 with a generated password.
      • org.highmed.dsf.fhir.db.server_user_password: Replace change-me-db-password-5 with a generated password.
      • org.highmed.dsf.fhir.serverBase: Replace https://change-me-your-dsf-fhir-server.fqdn/fhir with your external DSF FHIR Server base URL.
      • org.highmed.dsf.fhir.local-user.thumbprints: Replace change-me-your-client-certificate-sha512-thumbprint-hex-lowercase-without-colons with the SHA-512 thumprint of your client certificate (certificate B) generated earlier.
        org.highmed.dsf.fhir.local-user.thumbprints accepts a comma separated list of thumbprints, for easier access of the DSF FHIR server html front-end you might want to add additional thumbprints, e.g. the DFN PKI S/MIME certificate of your personal e-mail address.
      • org.highmed.dsf.fhir.local-organization.identifier: Replace change-me-your-organization-identifier.de with your organizations DSF identifier (shortest FQDN of your organizations homepage).
      • org.highmed.dsf.fhir.webservice.keystore.password: Replace change-me-p12-password with the password specified while generating the client_certificate.p12 file earlier.

    • /opt/fhir/db/conf/postgres_password

      • Replace change-me-db-password-4 with the password used for org.highmed.dsf.fhir.db.liquibase_user_password in /opt/fhir/app/conf/config.properties above.

  5. Add Certificates and Keys

    • Add client_certificate.p12 to folder /opt/fhir/app/conf/ (certificate B)
    • Add certificate.pem to folder /opt/fhir/proxy/ssl/ (certificate A)
    • Add private-key.pem to folder /opt/fhir/proxy/ssl/ (certificate A)
    • Add ca_certificate.pem to folder /opt/fhir/proxy/ssl/

  6. Start DSF FHIR Server
    Start using: docker-compose up -d && docker-compose logs -f (Ctrl-C will close log, but not stop container)

DSF BPE Server

  1. Add Group/User
    Add group and user used by the DSF BPE java application. Ubuntu compatible commands below:

    sudo addgroup --gid 2202 bpe
sudo adduser --system --no-create-home --uid 2202 --gid 2202 bpe

  2. Download and Extract Config Files
    Download prepared DSF BPE server config files and folder structure from https://github.com/highmed/highmed-dsf/wiki/resources/dsf_bpe_0_4_0.tar.gz

    cd /opt
wget https://github.com/highmed/highmed-dsf/wiki/resources/dsf_bpe_0_4_0.tar.gz
sudo tar --same-owner -zxvf dsf_bpe_0_4_0.tar.gz

    The tar command will unpack the config files at /opt/bpe assuming you changed into the /opt directory.

  3. Verify that the bpe system user or group can write into the following folders

    • /opt/bpe/app/log
    • /opt/bpe/app/last_event

  4. Modify Config Files

    • /opt/bpe/app/conf/config.properties

      • org.highmed.dsf.bpe.db.liquibase_user_password: Replace change-me-db-password-1 with a generated password.

      • org.highmed.dsf.bpe.db.server_user_password: Replace change-me-db-password-2 with a generated password.

      • org.highmed.dsf.bpe.db.camunda_user_password: Replace change-me-db-password-3 with a generated password.

      • org.highmed.dsf.bpe.fhir.organization.identifier.localValue: Replace change-me-your-organization-identifier.de with your organizations DSF identifier (shortest FQDN of your organizations homepage) used earlier.

      • org.highmed.dsf.bpe.fhir.local.webservice.baseUrl: Replace https://change-me-your-dsf-fhir-server.fqdn/fhir with your external DSF FHIR Server base URL.

      • org.highmed.dsf.bpe.fhir.local.webservice.keystore.password: Replace change-me-p12-password with the password specified while generating the client_certificate.p12 file earlier.

      • org.highmed.dsf.bpe.fhir.local.websocket.url: Replace wss://change-me-your-dsf-fhir-server.fqdn/fhir/ws with your external DSF FHIR Server base URL.

      • org.highmed.dsf.bpe.fhir.local.websocket.keystore.password: Replace change-me-p12-password with the password specified while generating the client_certificate.p12 file earlier.

      • For additional config properties see Process Deployment and Configuration v0.3.4 and release notes of the NUM-CODEX data transfer process plugin.

    • /opt/bpe/db/conf/postgres_password

      • Replace change-me-db-password-1 with the password used for org.highmed.dsf.bpe.db.liquibase_user_password in /opt/bpe/app/conf/config.properties above.

  5. Add Certificates and Keys

    • Add client_certificate.p12 to folder /opt/bpe/app/conf/ (certificate B)

    • Add certificate.pem to folder /opt/bpe/proxy/ssl/ (certificate B)

    • Add private-key.pem to folder /opt/bpe/proxy/ssl/ (certificate B)

    • Add ca_certificate.pem to folder /opt/bpe/proxy/ssl/

    • Add RSA public-key provided by the Central Research Repository as crr_public-key.pem into /opt/bpe/app/conf/, see NUM-CODEX data transfer process plugin release notes.

  6. Start DSF BPE Server (without process plugins)
    Start using: docker-compose up -d && docker-compose logs -f (Ctrl-C will close log, but not stop container)

  7. Verify DSF BPE Startup

    • Check that the BPE was able to download new Task resources from the DSF FHIR server during startup.
    • Check that the BPE was able to download a Subscription resources from the DSF FHIR server during startup.
    • Check that the BPE was able to connect to the websocket endpoint of the DSF FHIR server during startup.

    If you need to debug the TLS connection to your DSF FHIR server use for example:
    docker run -it --rm alpine/openssl s_client your-fhir-server.fqdn:443
    The command above should print the server certificate of your DSF FHIR server (certificate A) and end with a message like [...]tlsv13 alert certificate required[...]

  8. Stop DSF BPE Server
    Stop using: docker-compose stop (Ctrl-C will close log, but not stop container)

  9. Add DSF Processes
    To install processes add the released process jars to the /opt/bpe/app/process folder:

  10. Start DSF BPE Server
    Start using: docker-compose up -d && docker-compose logs -f (Ctrl-C will close log, but not stop container)

  11. Verify DSF BPE Startup

    • Check that the BPE was able to download new Task resources from the DSF FHIR server during startup.
    • Check that the BPE was able to download a Subscription resources from the DSF FHIR server during startup.
    • Check that the BPE was able to connect to the websocket endpoint of the DSF FHIR server during startup.
    • Check that the BPE was able to deploy the process plugins from /opt/bpe/app/process.
    • Check that the BPE was able to add FHIR resource to your DSF FHIR server. For example multiple ActivityDefinition resources should have been created.
Clone this wiki locally