Provided a more general relation between resource count & disk space

set mtba image to latest

README.md

@@ -22,6 +22,7 @@ This repository is the starting point for any information and tools you will nee
     - [TLS terminating proxies](#tls-terminating-proxies)
     - [File structure](#file-structure)
     - [BBMRI-ERIC Directory entry needed](#bbmri-eric-directory-entry-needed)
+    - [Loading data](#loading-data)
 4. [Things you should know](#things-you-should-know)
     - [Auto-Updates](#auto-updates)
     - [Auto-Backups](#auto-backups)
@@ -51,24 +52,41 @@ Ensure the following software (or newer) is installed:
 - docker >= 20.10.1
 - docker-compose >= 2.xx (`docker-compose` and `docker compose` are both supported).
 - systemd
+- curl
 
 We recommend to install Docker(-compose) from its official sources as described on the [Docker website](https://docs.docker.com).
 
-Note for Ubuntu: Please note that snap versions of Docker are not supported.
-
-Note for git and Docker: if you have a local proxy, you will need to adjust your setup appropriately, see [git proxy](https://gist.github.com/evantoli/f8c23a37eb3558ab8765) and [docker proxy](https://docs.docker.com/network/proxy/).
+> 📝 Note for Ubuntu: Snap versions of Docker are not supported.
 
 ### Network
 
-A running Bridgehead requires an outgoing HTTPS proxy to communicate with the central components.
+A Bridgehead communicates to all central components via outgoing HTTPS connections.
 
-Additionally, your site might use its own proxy. You should discuss this with your local systems administration. If a proxy is being used, you will need to note down the URL of the proxy. If it is a secure proxy, then you will also need to make a note of its username and password. This information will be used later on during the installation process.
+Your site might require an outgoing proxy (i.e. HTTPS forward proxy) to connect to external servers; you should discuss this with your local systems administration. In that case, you will need to note down the URL of the proxy. If the proxy requires authentication, you will also need to make a note of its username and password. This information will be used later on during the installation process. TLS terminating proxies are also supported, see [here](#tls-terminating-proxies). Apart from the Bridgehead itself, you may also need to configure the proxy server in [git](https://gist.github.com/evantoli/f8c23a37eb3558ab8765) and [docker](https://docs.docker.com/network/proxy/).
 
-Note that git and Docker may also need to be configured to use this proxy. This is a job for your systems administrators.
+The following URLs need to be accessible (prefix with `https://`):
+* To fetch code and configuration from git repositories
+  * github.com
+  * git.verbis.dkfz.de
+* To fetch docker images
+  * docker.verbis.dkfz.de
+  * Official Docker, Inc. URLs (subject to change, see [official list](https://docs.docker.com/desktop/all))
+    * hub.docker.com
+    * registry-1.docker.io
+    * production.cloudflare.docker.com
+* To report bridgeheads operational status
+  * healthchecks.verbis.dkfz.de
+* only for DKTK/CCP
+  * broker.ccp-it.dktk.dkfz.de
+* only for BBMRI-ERIC
+  * broker.bbmri.samply.de
+  * gitlab.bbmri-eric.eu
+* only for German Biobank Node
+  * broker.bbmri.de
 
-If there is a site firewall, this needs to be configured so that outgoing calls to the following URLs are allowed: *.dkfz.de, github.com, docker.io, *.docker.io, *.samply.de.
+> 📝 This URL list is subject to change. Instead of the individual names, we highly recommend whitelisting wildcard domains: *.dkfz.de, github.com, *.docker.com, *.docker.io, *.samply.de, *.bbmri.de.
 
-Note for Ubuntu: Please note that the uncomplicated firewall (ufw) is known to conflict with Docker [here](https://github.com/chaifeng/ufw-docker).
+> 📝 Ubuntu's pre-installed uncomplicated firewall (ufw) is known to conflict with Docker, more info [here](https://github.com/chaifeng/ufw-docker).
 
 ## Deployment
 
@@ -101,7 +119,7 @@ Mention:
 We will set the repository up for you. We will then send you:
 
 - A Repository Short Name (RSN). Beware: this is distinct from your site name.
-- Repository URL containing the acces token eg. https://BH_Dummy:dummy_token@git.verbis.dkfz.de/bbmri-bridgehead-configs/dummy.git
+- Repository URL containing the acces token eg. https://BH_Dummy:dummy_token@git.verbis.dkfz.de/<project>-bridgehead-configs/dummy.git
 
 During the installation, your Bridgehead will download your site's configuration from GitLab and you can review the details provided to us by email.
 
@@ -294,6 +312,32 @@ Once you edited the gitlab config, the bridgehead will autoupdate the config wit
 
 There will be a delay before the effects of Directory sync become visible. First, you will need to wait until the time you have specified in ```TIMER_CRON```. Second, the information will then be synchronized from your national node with the central European Directory. This can take up to 24 hours.
 
+### Loading data
+
+The data accessed by the federated search is held in the Bridgehead in a FHIR store (we use Blaze).
+
+You can load data into this store by using its FHIR API:
+
+```
+https://<Name of your server>/bbmri-localdatamanagement/fhir
+```
+The name of your server will generally be the full name of the VM that the Bridgehead runs on. You can alternatively supply an IP address.
+
+The FHIR API uses basic auth. You can find the credentials in `/etc/bridgehead/<project>.local.conf`.
+
+Note that if you don't have a DNS certificate for the Bridgehead, you will need to allow an insecure connection. E.g. with curl, use the `-k` flag.
+
+The storage space on your hard drive will depend on the number of FHIR resources that you intend to generate. This will be the sum of the number of patients/subjects, the number of samples, the number of conditions/diseases and the number of observations. As a general rule of thumb, you can assume that each resource will consume about 2 kilobytes of disk space.
+
+For more information on Blaze performance, please refer to [import performance](https://github.com/samply/blaze/blob/master/docs/performance/import.md).
+
+#### ETL for BBMRI and GBA
+
+Normally, you will need to build your own ETL to feed the Bridgehead. However, there is one case where a short cut might be available:
+- If you are using CentraXX as a BIMS and you have a FHIR-Export License, then you can employ standard mapping scripts that access the CentraXX-internal data structures and map the data onto the BBMRI FHIR profile. It may be necessary to adjust a few parameters, but this is nonetheless significantly easier than writing your own ETL.
+
+You can find the profiles for generating FHIR in [Simplifier](https://simplifier.net/bbmri.de/~resources?category=Profile).
+
 ## Things you should know
 
 ### Auto-Updates
@@ -337,8 +381,28 @@ Installation under WSL ought to work, but we have not tested this.
 
 ### Docker Daemon Proxy Configuration
 
-Docker has a background daemon, responsible for downloading images and starting them. Sometimes, proxy configuration from your system won't carry over and it will fail to download images. In that case, configure the proxy for this daemon as described in the [official documentation](https://docs.docker.com).
+Docker has a background daemon, responsible for downloading images and starting them. Sometimes, proxy configuration from your system won't carry over and it will fail to download images. In that case, you'll need to configure the proxy inside the system unit of docker by creating the file `/etc/systemd/system/docker.service.d/proxy.conf` with the following content:
 
+``` ini
+[Service]
+Environment="HTTP_PROXY=http://proxy.example.com:3128"
+Environment="HTTPS_PROXY=https://proxy.example.com:3128"
+Environment="NO_PROXY=localhost,127.0.0.1,some-local-docker-registry.example.com,.corp"
+```
+
+After saving the configuration file, you'll need to reload the system daemon for the changes to take effect:
+
+``` shell
+sudo systemctl daemon-reload
+```
+
+and restart the docker daemon:
+
+``` shell
+sudo systemctl restart docker
+```
+
+For more information, please consult the [official documentation](https://docs.docker.com/config/daemon/systemd/#httphttps-proxy).
 
 ### Monitoring
 

bbmri/vars

@@ -14,7 +14,7 @@ do
 done
 
 SUPPORT_EMAIL=$ERIC_SUPPORT_EMAIL
-BROKER_URL_FOR_PREREQ=$ERIC_BROKER_URL
+BROKER_URL_FOR_PREREQ="${ERIC_BROKER_URL:-$GBN_BROKER_URL}"
 
 if [ -n "$GBN_SUPPORT_EMAIL" ]; then
     SUPPORT_EMAIL=$GBN_SUPPORT_EMAIL

bridgehead

@@ -65,6 +65,7 @@ loadVars() {
 	fi
 	detectCompose
 	setHostname
+	setupProxy
 }
 
 case "$ACTION" in

ccp/docker-compose.yml

@@ -28,7 +28,7 @@ services:
       BLAZE_URL: "http://bridgehead-ccp-blaze:8080/fhir/"
       BEAM_PROXY_URL: http://beam-proxy:8081
       RETRY_COUNT: ${FOCUS_RETRY_COUNT}
-      OBFUSCATE: "no"
+      EPSILON: 0.28
     depends_on:
       - "beam-proxy"
       - "blaze"

ccp/modules/adt2fhir-rest-compose.yml

@@ -0,0 +1,18 @@
+version: "3.7"
+
+services:
+  adt2fhir-rest:
+    container_name: bridgehead-adt2fhir-rest
+    image: docker.verbis.dkfz.de/ccp/adt2fhir-rest:main
+    environment:
+      IDTYPE: BK_${IDMANAGEMENT_FRIENDLY_ID}_L-ID
+      MAINZELLISTE_APIKEY: ${IDMANAGER_LOCAL_PATIENTLIST_APIKEY}
+      SALT: ${LOCAL_SALT}
+    restart: always
+    labels:
+      - "traefik.enable=true"
+      - "traefik.http.routers.adt2fhir-rest.rule=PathPrefix(`/adt2fhir-rest`)"
+      - "traefik.http.middlewares.adt2fhir-rest_strip.stripprefix.prefixes=/adt2fhir-rest"
+      - "traefik.http.services.adt2fhir-rest.loadbalancer.server.port=8080"
+      - "traefik.http.routers.adt2fhir-rest.tls=true"
+      - "traefik.http.routers.adt2fhir-rest.middlewares=adt2fhir-rest_strip,auth"

ccp/modules/adt2fhir-rest-setup.sh

@@ -0,0 +1,13 @@
+#!/bin/bash
+
+function adt2fhirRestSetup() {
+  if [ -n "$ENABLE_ADT2FHIR_REST" ]; then
+    log INFO "ADT2FHIR-REST setup detected -- will start adt2fhir-rest API."
+    if [ ! -n "$IDMANAGER_LOCAL_PATIENTLIST_APIKEY" ]; then
+      log ERROR "Missing ID-Management Module! Fix this by setting up ID Management:"
+      exit 1;
+    fi
+    OVERRIDE+=" -f ./$PROJECT/modules/adt2fhir-rest-compose.yml"
+    LOCAL_SALT="$(echo \"local-random-salt\" | openssl pkeyutl -sign -inkey /etc/bridgehead/pki/${SITE_ID}.priv.pem | base64 | head -c 30)"
+  fi
+}

ccp/modules/id-management-compose.yml

@@ -43,7 +43,7 @@ services:
       - patientlist-db
 
   patientlist-db:
-    image: docker.verbis.dkfz.de/cache/postgres:15.1-alpine
+    image: docker.verbis.dkfz.de/cache/postgres:15.4-alpine
     container_name: bridgehead-patientlist-db
     environment:
       POSTGRES_USER: "mainzelliste"

ccp/modules/id-management-setup.sh

@@ -39,6 +39,7 @@ function applySpecialCases() {
 	result="$1";
 	result="${result/Lmu/LMU}";
 	result="${result/Tum/TUM}";
+	result="${result/Dktk Test/Teststandort}";
 	echo "$result";
 }
 

ccp/modules/mtba-compose.yml

@@ -2,7 +2,7 @@ version: "3.7"
 
 services:
   mtba:
-    image: docker.verbis.dkfz.de/cache/samply/mtba:develop
+    image: docker.verbis.dkfz.de/cache/samply/mtba:latest
     container_name: bridgehead-mtba
     environment:
       BLAZE_STORE_URL: http://blaze:8080

ccp/modules/mtba-setup.sh

@@ -1,11 +1,10 @@
 #!/bin/bash
 
 function mtbaSetup() {
-       # TODO: Check if ID-Management Module is activated!
   if [ -n "$ENABLE_MTBA" ];then
     log INFO "MTBA setup detected -- will start MTBA Service and CBioPortal."
     if [ ! -n "$IDMANAGER_UPLOAD_APIKEY" ]; then
-                      log ERROR "Detected MTBA Module configuration but ID-Management Module seems not to be configured!"
+      log ERROR "Missing ID-Management Module! Fix this by setting up ID Management:"
       exit 1;
     fi
     OVERRIDE+=" -f ./$PROJECT/modules/mtba-compose.yml"

ccp/modules/nngm-setup.sh

@@ -1,8 +1,6 @@
 #!/bin/bash
 
-function nngmSetup() {
-	if [ -n "$NNGM_CTS_APIKEY" ]; then
+if [ -n "$NNGM_CTS_APIKEY" ]; then
   log INFO "nNGM setup detected -- will start nNGM Connector."
   OVERRIDE+=" -f ./$PROJECT/modules/nngm-compose.yml"
-	fi
-	}
+fi

ccp/vars

@@ -16,5 +16,5 @@ do
 done
 
 idManagementSetup
-nngmSetup
 mtbaSetup
+adt2fhirRestSetup

lib/functions.sh

@@ -9,6 +9,33 @@ detectCompose() {
 	fi
 }
 
+setupProxy() {
+	### Note: As the current data protection concepts do not allow communication via HTTP,
+	### we are not setting a proxy for HTTP requests.
+
+	local http="no"
+	local https="no"
+	if [ $HTTPS_PROXY_URL ]; then
+		local proto="$(echo $HTTPS_PROXY_URL | grep :// | sed -e 's,^\(.*://\).*,\1,g')"
+		local fqdn="$(echo ${HTTPS_PROXY_URL/$proto/})"
+		local hostport=$(echo $HTTPS_PROXY_URL | sed -e "s,$proto,,g" | cut -d/ -f1)
+		HTTPS_PROXY_HOST="$(echo $hostport | sed -e 's,:.*,,g')"
+		HTTPS_PROXY_PORT="$(echo $hostport | sed -e 's,^.*:,:,g' -e 's,.*:\([0-9]*\).*,\1,g' -e 's,[^0-9],,g')"
+		if [[ ! -z "$HTTPS_PROXY_USERNAME" && ! -z "$HTTPS_PROXY_PASSWORD" ]]; then
+			local proto="$(echo $HTTPS_PROXY_URL | grep :// | sed -e 's,^\(.*://\).*,\1,g')"
+			local fqdn="$(echo ${HTTPS_PROXY_URL/$proto/})"
+			HTTPS_PROXY_FULL_URL="$(echo $proto$HTTPS_PROXY_USERNAME:$HTTPS_PROXY_PASSWORD@$fqdn)"
+			https="authenticated"
+		else
+			HTTPS_PROXY_FULL_URL=$HTTPS_PROXY_URL
+			https="unauthenticated"
+		fi
+	fi
+
+	log INFO "Configuring proxy servers: $http http proxy (we're not supporting unencrypted comms), $https https proxy"
+	export HTTPS_PROXY_HOST HTTPS_PROXY_PORT HTTPS_PROXY_FULL_URL
+}
+
 exitIfNotRoot() {
   if [ "$EUID" -ne 0 ]; then
     log "ERROR" "Please run as root"
@@ -49,7 +76,7 @@ fetchVarsFromVault() {
 
 	set +e
 
-	PASS=$(BW_MASTERPASS="$BW_MASTERPASS" BW_CLIENTID="$BW_CLIENTID" BW_CLIENTSECRET="$BW_CLIENTSECRET" docker run --rm -e BW_MASTERPASS -e BW_CLIENTID -e BW_CLIENTSECRET -e http_proxy samply/bridgehead-vaultfetcher $@)
+	PASS=$(BW_MASTERPASS="$BW_MASTERPASS" BW_CLIENTID="$BW_CLIENTID" BW_CLIENTSECRET="$BW_CLIENTSECRET" docker run --rm -e BW_MASTERPASS -e BW_CLIENTID -e BW_CLIENTSECRET -e http_proxy docker.verbis.dkfz.de/cache/samply/bridgehead-vaultfetcher:latest $@)
 	RET=$?
 
 	if [ $RET -ne 0 ]; then
@@ -188,7 +215,7 @@ function do_enroll_inner {
 		PARAMS+="--admin-email $SUPPORT_EMAIL"
 	fi
 
-	docker run --rm -v /etc/bridgehead/pki:/etc/bridgehead/pki samply/beam-enroll:latest --output-file $PRIVATEKEYFILENAME --proxy-id $MANUAL_PROXY_ID $PARAMS
+	docker run --rm -v /etc/bridgehead/pki:/etc/bridgehead/pki docker.verbis.dkfz.de/cache/samply/beam-enroll:latest --output-file $PRIVATEKEYFILENAME --proxy-id $MANUAL_PROXY_ID $PARAMS
 	chmod 600 $PRIVATEKEYFILENAME
 }
 

lib/monitoring.sh

@@ -47,8 +47,8 @@ function hc_send(){
 
     if [ -n "$2" ]; then
         MSG="$2\n\nDocker stats:\n$UPTIME"
-        echo -e "$MSG" | https_proxy=$HTTPS_PROXY_URL curl --max-time 5 -A "$USER_AGENT" -s -o /dev/null -X POST --data-binary @- "$HCURL"/"$1" || log WARN "Monitoring failed: Unable to send data to $HCURL/$1"
+        echo -e "$MSG" | https_proxy=$HTTPS_PROXY_FULL_URL curl --max-time 5 -A "$USER_AGENT" -s -o /dev/null -X POST --data-binary @- "$HCURL"/"$1" || log WARN "Monitoring failed: Unable to send data to $HCURL/$1"
     else
-        https_proxy=$HTTPS_PROXY_URL curl --max-time 5 -A "$USER_AGENT" -s -o /dev/null "$HCURL"/"$1" || log WARN "Monitoring failed: Unable to send data to $HCURL/$1"
+        https_proxy=$HTTPS_PROXY_FULL_URL curl --max-time 5 -A "$USER_AGENT" -s -o /dev/null "$HCURL"/"$1" || log WARN "Monitoring failed: Unable to send data to $HCURL/$1"
     fi
 }

lib/prerequisites.sh

@@ -14,7 +14,7 @@ checkOwner /etc/bridgehead bridgehead || exit 1
 
 ## Check if user is a su
 log INFO "Checking if all prerequisites are met ..."
-prerequisites="git docker"
+prerequisites="git docker curl"
 for prerequisite in $prerequisites; do
   $prerequisite --version 2>&1
   is_available=$?
@@ -68,7 +68,7 @@ source /etc/bridgehead/${PROJECT}.conf
 source ${PROJECT}/vars
 
 set +e
-SERVERTIME="$(https_proxy=$HTTPS_PROXY_URL curl -m 5 -s -I $BROKER_URL_FOR_PREREQ 2>&1 | grep -i -e '^Date: ' | sed -e 's/^Date: //i')"
+SERVERTIME="$(https_proxy=$HTTPS_PROXY_FULL_URL curl -m 5 -s -I $BROKER_URL_FOR_PREREQ 2>&1 | grep -i -e '^Date: ' | sed -e 's/^Date: //i')"
 RET=$?
 set -e
 if [ $RET -ne 0 ]; then

lib/update-bridgehead.sh

@@ -30,7 +30,7 @@ source $CONFFILE
 assertVarsNotEmpty SITE_ID || fail_and_report 1 "Update failed: SITE_ID empty"
 export SITE_ID
 
-checkOwner . bridgehead || fail_and_report 1 "Update failed: Wrong permissions in $(pwd)"
+checkOwner /srv/docker/bridgehead bridgehead || fail_and_report 1 "Update failed: Wrong permissions in /srv/docker/bridgehead"
 checkOwner /etc/bridgehead bridgehead || fail_and_report 1 "Update failed: Wrong permissions in /etc/bridgehead"
 
 CREDHELPER="/srv/docker/bridgehead/lib/gitpassword.sh"
@@ -50,12 +50,12 @@ for DIR in /etc/bridgehead $(pwd); do
     git -C $DIR config credential.helper "$CREDHELPER"
   fi
   old_git_hash="$(git -C $DIR rev-parse --verify HEAD)"
-  if [ -z "$HTTP_PROXY_URL" ]; then
+  if [ -z "$HTTPS_PROXY_FULL_URL" ]; then
     log "INFO" "Git is using no proxy!"
     OUT=$(retry 5 git -C $DIR fetch 2>&1 && retry 5 git -C $DIR pull 2>&1)
   else
-    log "INFO" "Git is using proxy ${HTTP_PROXY_URL} from ${CONFFILE}"
-    OUT=$(retry 5 git -c http.proxy=$HTTP_PROXY_URL -c https.proxy=$HTTPS_PROXY_URL -C $DIR fetch 2>&1 && retry 5 git -c http.proxy=$HTTP_PROXY_URL -c https.proxy=$HTTPS_PROXY_URL -C $DIR pull 2>&1)
+    log "INFO" "Git is using proxy ${HTTPS_PROXY_URL} from ${CONFFILE}"
+    OUT=$(retry 5 git -c http.proxy=$HTTPS_PROXY_FULL_URL -c https.proxy=$HTTPS_PROXY_FULL_URL -C $DIR fetch 2>&1 && retry 5 git -c http.proxy=$HTTPS_PROXY_FULL_URL -c https.proxy=$HTTPS_PROXY_FULL_URL -C $DIR pull 2>&1)
   fi
   if [ $? -ne 0 ]; then
     report_error log "Unable to update git $DIR: $OUT"
@@ -116,7 +116,7 @@ if [ -n "${BACKUP_DIRECTORY}" ]; then
     mkdir -p "$BACKUP_DIRECTORY"
     chown -R "$BACKUP_DIRECTORY" bridgehead;
   fi
-  checkOwner "$BACKUP_DIRECTORY" bridgehead || fail_and_report 1 "Automatic maintenance failed: Wrong permissions for backup directory $(pwd)"
+  checkOwner "$BACKUP_DIRECTORY" bridgehead || fail_and_report 1 "Automatic maintenance failed: Wrong permissions for backup directory $BACKUP_DIRECTORY"
   # Collect all container names that contain '-db'
   BACKUP_SERVICES="$(docker ps --filter name=-db --format "{{.Names}}" | tr "\n" "\ ")"
   log INFO "Performing automatic maintenance: Creating Backups for $BACKUP_SERVICES";

minimal/docker-compose.yml

@@ -35,8 +35,8 @@ services:
     image: docker.verbis.dkfz.de/cache/samply/bridgehead-forward-proxy:latest
     environment:
       HTTPS_PROXY: ${HTTPS_PROXY_URL}
-      USERNAME: ${HTTPS_PROXY_USERNAME}
-      PASSWORD: ${HTTPS_PROXY_PASSWORD}
+      HTTPS_PROXY_USERNAME: ${HTTPS_PROXY_USERNAME}
+      HTTPS_PROXY_PASSWORD: ${HTTPS_PROXY_PASSWORD}
     tmpfs:
       - /var/log/squid
       - /var/spool/squid
@@ -45,7 +45,7 @@ services:
 
   landing:
     container_name: bridgehead-landingpage
-    image: docker.verbis.dkfz.de/cache/samply/bridgehead-landingpage:master
+    image: docker.verbis.dkfz.de/cache/samply/bridgehead-landingpage:main
     labels:
       - "traefik.enable=true"
       - "traefik.http.routers.landing.rule=PathPrefix(`/`)"