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

DSF Upgrade From 0.5.x to 0.5.5

Jump to bottom
Hauke Hund edited this page Apr 5, 2022 · 18 revisions

Upgrading from 0.5.x

Upgrading the DSF from 0.5.0, 0.5.1, 0.5.2, 0.5.3 or 0.5.4 to 0.5.5 involes replacing a few config files, modifying the docker-compose.yml files and recreating the containers.

A previous version of the upgrade guide (pre 2022-03-29 13:09 CEST) contained non working tar commands. Please see instructions on how to fix an install that got broken using the previous upgrade guide at the end of the page.

Modify DSF FHIR Server Setup

  1. Preparation / Backup

    • We recommend to create a backup of the /opt/fhir directory before proceeding with the upgrade.
      For example using: sudo cp -rp /opt/fhir /opt/fhir_backup_pre_0.5.5_upgrade

  2. Download prepared DSF FHIR server config files and extract modified/missing files

    The command will add/replace files in /opt/fhir/secrets as well as update the external FHIR bundle at /opt/fhir/conf/bundle.xml

    The output of the tar command should be

    fhir/
fhir/conf/
fhir/conf/bundle.xml
fhir/postgres-data/
fhir/secrets/
fhir/secrets/ssl_root_ca_certificate_file.pem
fhir/secrets/ssl_certificate_chain_file_Sectigo_ECC_Organization_Validation_Secure_Server_CA.pem
fhir/secrets/ssl_certificate_chain_file_GEANT_OV_ECC_CA_4.pem
fhir/secrets/ssl_certificate_chain_file_D-TRUST_SSL_Class_3_CA_1_2009.pem
fhir/secrets/README.txt
fhir/secrets/ssl_certificate_chain_file_GEANT_OV_RSA_CA_4.pem
fhir/secrets/ssl_ca_dn_request_file.pem
fhir/secrets/ssl_certificate_chain_file_DFN-Verein.pem
fhir/secrets/ssl_certificate_chain_file_GEANT_EV_ECC_CA_4.pem
fhir/secrets/ssl_certificate_chain_file_Sectigo_RSA_Organization_Validation_Secure_Server_CA.pem
fhir/secrets/ssl_certificate_chain_file_GEANT_EV_RSA_CA_4.pem
fhir/secrets/ssl_ca_certificate_file.pem
fhir/log/

  3. Delete not needed file

    sudo rm /opt/fhir/secrets/ssl_certificate_chain_file.pem

  4. Modify the DSF FHIR docker-compose.yml file, replacting 0.5.x (0.5.0, 0.5.1, 0.5.2, 0.5.3, 0.5.4) with 0.5.5

    @@ -1,7 +1,7 @@
 version: '3.8'
 services:
   proxy:
-    image: ghcr.io/highmed/fhir_proxy:0.5.x
+    image: ghcr.io/highmed/fhir_proxy:0.5.5
     restart: on-failure
     ports:
       - 127.0.0.1:80:80
@@ -27,7 +27,7 @@
       - app

   app:
-    image: ghcr.io/highmed/fhir:0.5.x
+    image: ghcr.io/highmed/fhir:0.5.5
     restart: on-failure
     secrets:
       - db_liquibase.password
@@ -46,7 +46,6 @@
         source: ./log
         target: /opt/fhir/log
     environment:
-      EXTRA_JVM_ARGS: -Dlog4j2.formatMsgNoLookups=true
       TZ: Europe/Berlin
       ORG_HIGHMED_DSF_FHIR_DB_LIQUIBASE_PASSWORD_FILE: /run/secrets/db_liquibase.password
       ORG_HIGHMED_DSF_FHIR_DB_USER_PASSWORD_FILE: /run/secrets/db_user.password
@@ -97,8 +96,26 @@
     file: ./secrets/ssl_certificate_file.pem
   ssl_certificate_key_file.pem:
     file: ./secrets/ssl_certificate_key_file.pem
-  ssl_certificate_chain_file.pem:
-    file: ./secrets/ssl_certificate_chain_file.pem
+
+# uncomment certificate chain entry based on the CA that signed your DSF FHIR server certificate
+# e.g. the next two lines if your certificate was signed by DFN-Verein Global Issuing CA
+#  ssl_certificate_chain_file.pem:
+#    file: ./secrets/ssl_certificate_chain_file_DFN-Verein.pem
+#  ssl_certificate_chain_file.pem:
+#    file: ./secrets/ssl_certificate_chain_file_D-TRUST_SSL_Class_3_CA_1_2009.pem
+#  ssl_certificate_chain_file.pem:
+#    file: ./secrets/ssl_certificate_chain_file_GEANT_EV_ECC_CA_4.pem
+#  ssl_certificate_chain_file.pem:
+#    file: ./secrets/ssl_certificate_chain_file_GEANT_EV_RSA_CA_4.pem
+#  ssl_certificate_chain_file.pem:
+#    file: ./secrets/ssl_certificate_chain_file_GEANT_OV_ECC_CA_4.pem
+#  ssl_certificate_chain_file.pem:
+#    file: ./secrets/ssl_certificate_chain_file_GEANT_OV_RSA_CA_4.pem
+#  ssl_certificate_chain_file.pem:
+#    file: ./secrets/ssl_certificate_chain_file_Sectigo_ECC_Organization_Validation_Secure_Server_CA.pem
+#  ssl_certificate_chain_file.pem:
+#    file: ./secrets/ssl_certificate_chain_file_Sectigo_RSA_Organization_Validation_Secure_Server_CA.pem
+
   ssl_ca_certificate_file.pem:
     file: ./secrets/ssl_ca_certificate_file.pem
   ssl_ca_dn_request_file.pem:

  5. Uncomment one of the certificate chain entries in the docker-compose file base on the certificate authority that signed your DSF FHIR server certificate. For example use the following two lines if the server certificate is signed by DFN-Verein Global Issuing CA

      ssl_certificate_chain_file.pem:
    file: ./secrets/ssl_certificate_chain_file_DFN-Verein.pem

  6. Upgrade the DSF FHIR containers
    From /opt/fhir execute

    docker-compose up -d && docker-compose logs -f

Modify DSF BPE Server Setup

  1. Preparation / Backup

    • We recommend to create a backup of the /opt/bpe directory before proceeding with the upgrade.
      For example using: sudo cp -rp /opt/bpe /opt/bpe_backup_pre_0.5.5_upgrade

  2. Download prepared DSF BPE server config files and extract modified/missing files

    The command will replace files in /opt/bpe/secrets

    The output of the tar command should be

    bpe/
bpe/plugin/
bpe/last_event/
bpe/postgres-data/
bpe/process/
bpe/secrets/
bpe/secrets/ssl_root_ca_certificate_file.pem
bpe/secrets/README.txt
bpe/log/

  3. Fix folder / file permissions (broken in previously provided tar.gz files)

    sudo chmod 0550 /opt/bpe/secrets
sudo chmod 0440 /opt/bpe/secrets/*

  4. Modify the DSF BPE docker-compose.yml file, replacting 0.5.x (0.5.0, 0.5.1, 0.5.2, 0.5.3, 0.5.4) with 0.5.5

    @@ -1,7 +1,7 @@
 version: '3.8'
 services:
   app:
-    image: ghcr.io/highmed/bpe:0.5.x
+    image: ghcr.io/highmed/bpe:0.5.5
     restart: on-failure
     secrets:
       - db_liquibase.password
@@ -28,7 +28,6 @@
         source: ./last_event
         target: /opt/bpe/last_event
     environment:
-      EXTRA_JVM_ARGS: -Dlog4j2.formatMsgNoLookups=true
       TZ: Europe/Berlin
       ORG_HIGHMED_DSF_BPE_DB_LIQUIBASE_PASSWORD_FILE: /run/secrets/db_liquibase.password
       ORG_HIGHMED_DSF_BPE_DB_USER_PASSWORD_FILE: /run/secrets/db_user.password

  5. Upgrade the DSF BPE containers
    From /opt/bpe execute

    docker-compose up -d && docker-compose logs -f

Fixing a broken upgrade

A previous version of the upgrade guide (pre 2022-03-29 13:09 CEST) contained non working tar commands resulting in an incomplete upgrade of files and inadvertently overwritten secrets/db_*.password files. To fix this problem you have to replace the content of the secrets/db_*.password files with your original content and perform the upgrade guide again, specifically the tar commands.

After performing the upgrade guide again, if you can't remember the values of your secrets/db_*.password files, you need to change the password inside the database:

FHIR

  1. Start the database only, at /opt/fhir

    docker-compose up -d db

  2. Connect to the running database

    docker exec -it fhir_db_1 /bin/bash

  3. Inside the docker terminal connection, connect to the database using psql:

    psql fhir liquibase_user

  4. Modify the necessary passwords

    \password liquibase_user input content of /opt/fhir/secrets/db_liquibase.password when prompted.

    \password fhir_server_user input content of /opt/fhir/secrets/db_user.password when prompted.

    \password fhir_server_permanent_delete_user input content of /opt/fhir/secrets/db_user_permanent_delete.password when prompted.
     

  5. Clear MD5 hashes of two DB change log entries

    UPDATE databasechangelog SET md5sum = null WHERE id LIKE 'db.create-db-users.changelog%';

  6. End the psql session

    \q

  7. Disconnect from the database container, e.g. Ctrl-D or exit

  8. Start the FHIR Server / Reverse-Proxy

    docker-compose up -d && docker-compose logs -f

BPE

  1. Start the database only, at /opt/bpe

    docker-compose up -d db

  2. Connect to the running database

    docker exec -it bpe_db_1 /bin/bash

  3. Inside the docker terminal connection, connect to the database using psql:

    psql bpe liquibase_user

  4. Modify the necessary passwords

    \password liquibase_user inputting content of /opt/bpe/secrets/db_liquibase.password when prompted.

    \password bpe_server_user inputting content of /opt/bpe/secrets/db_user.password when prompted.

    \password camunda_server_user inputting content of /opt/bpe/secrets/db_user_camunda.password when prompted.
     

  5. Clear MD5 hashes of one DB change log entry

    UPDATE databasechangelog SET md5sum = null WHERE id LIKE 'db.create-db-users.changelog%';

  6. End the psql session

    \q

  7. Disconnect from the database container, e.g. Ctrl-D or exit

  8. Start the BPE Server

    docker-compose up -d && docker-compose logs -f

Alternative for fixing DB user passwords (not recommended in production):
Deleting the content of the postgres-data folder will result in a clean setup using new database user password.

Notes for none standard deployments

If your are running a non standard deployment, here is a summary of the changes from 0.5.4 to 0.5.5.

  • New versions 0.5.5 with upgraded Java library dependency have been release for the docker images ghcr.io/highmed/fhir and ghcr.io/highmed/bpe. The docker images are based on OpenJDK 11.0.14.1.
  • New versions 0.5.5 of ghcr.io/highmed/fhir_proxy and ghcr.io/highmed/bpe_proxy based on Apache httpd version 2.4.53 have been release.
  • The new current install guide and this upgrade guide configures the DSF to be compatible with certificates from the certificate authorities DFN-PKI Global G2 (was supported in older versions), D-Trust (via TMF e.V.) and DFN GÉANT TCS.
    This is reflected by adding additional signing certificates via Apache httpd config parameter SSLCADNRequestFile (nginx: ssl_client_certificate) and additional certificate trust ca chains via Apache httpd config parameter SSLCACertificateFile (nginx: ssl_trusted_certificate). See fhir/secrets/ssl_ca_dn_request_file.pem and fhir/secrets/ssl_ca_certificate_file.pem in the provided tar.gz files.
    Also, additional certificates have been added to the trusted root ca certificates used by the DSF FHIR client of the fhir and bpe app containers. See fhir/secrets/ssl_root_ca_certificate_file.pem and bpe/secrets/ssl_root_ca_certificate_file.pem in the provided tar.gz files.
  • Based on the CA that signed the server certificate, an appropriate certificate chain file has to be activated now in the DSF FHIR docker-compose file. Options for all supported CAs are provided.
  • The external FHIR transaction Bundle for NUM-CODEX was modified to add the certificate thumbprint of the new client certificate of the GTH Test Server. See fhir/conf/bundle.xml in the provided dsf_codex_test_fhir_0_5_5.tar.gz file.
Clone this wiki locally