bridgehead/README.md

Bridgehead

A Bridgehead is a set of components that must be installed locally, in order to connect your clinic or research centre to a federated search system. This repository contains the information and tools that you will need to deploy a Bridgehead. If you have questions, please contact us.

TOC

1. Requirements
   • Hardware
   • System
     • Git
     • Docker
2. Deployment
   • Installation
   • Register with Beam
   • Starting and stopping your Bridgehead
   • Auto-starting your Bridgehead when the server starts
3. Additional Services
   • Monitoring
   • Register with a Directory
4. Site-specific configuration
   • HTTPS Access
   • Locally Managed Secrets
   • Git Proxy Configuration
   • Docker Daemon Proxy Configuration
   • Non-Linux OS
5. License

Requirements

Hardware

To get the most out of your Bridgehead, we recommend the follwing Hardware:

• 4 CPU cores
• At least 8 GB Ram
• 100GB Hard Drive, SSD recommended

System

You are strongly recommended to install the Bridgehead under a Linux operating system (but see the section Non-Linux OS). You will need root (administrator) priveleges on this machine in order to perform the deployment.

The following software should be installed:

Git

Check if you have at least git 2.0 installed on the system with:

git --version

Docker

Check the installed Docker version:

docker --version

The version should ideally be higher than "20.10.1". The next step is to check docker-compose with:

docker-compose --version

The recomended version is "2.XX" and higher.

If docker or docker-compose are not installed, please refer to the Docker website.

Deployment

Installation

First, clone the repository to the directory "/srv/docker/bridgehead":

sudo mkdir -p /srv/docker/;
sudo git clone https://github.com/samply/bridgehead.git /srv/docker/bridgehead;

Now create a user for the Bridgehead service:

sudo useradd -M -g docker -N -s /sbin/nologin bridgehead

After adding the user you will need to change the ownership of the directory to the Bridgehead user.

sudo chown bridgehead /srv/docker/bridgehead/ -R

Download the configuration repository:

sudo git clone https://github.com/samply/bridgehead-config.git -b fix/bbmri-config /etc/bridgehead;

Change ownership:

sudo chown bridgehead /etc/bridgehead/ -R

Edit /etc/bridgehead/bbmri.conf and modify SITE_ID and SITE_NAME to be relevant to your biobank. SITE_ID should not contains spaces. By convention, it is lower-case. E.g.:

SITE_ID="toulouse-prod"
SITE_NAME="Toulouse"

Register with Beam

You will need to register with Beam in order to be able to start your Bridgehead. Please send an email to: bridgehead@helpdesk.bbmri-eric.eu, mentioning the SITE_ID that you chose above.

The response will contain your private key for Beam.

Create a file for this private key:

/etc/bridgehead/pki/$SITE_ID.priv.pem

Starting and stopping your Bridgehead

To start your new Bridgehead, type:

sudo /srv/docker/bridgehead/bridgehead start bbmri

The script may break, because Spot tries to connect to Blaze, but Blaze is not yet ready, causing Spot to terminate. Try to start and stop the script a few times.

To shut down the Bridgehead, type:

sudo /srv/docker/bridgehead/bridgehead stop bbmri

Auto-starting your Bridgehead when the server starts

Using this feature is optional.

Many Linux distributions support the "systemctl" command, which enables you to autostart processes whenever your server is booted.

In this repository you will find tools that allow you to take advantage of "systemctl" to automatically start the Bridgehead whenever your server gets restarted. You can set this up by executing the bridgehead script:

sudo /srv/docker/bridgehead/bridgehead install bbmri

This will install the systemd units to run and update the Bridgehead.

If your site operates with a proxy, you will need to set it up with systemctl edit as follows:

sudo systemctl edit bridgehead@bbmri.service;

This will open your default editor allowing you to edit the docker system units configuration. Insert the following lines in the editor and define your machines secrets.

[Service]
Environment=HOSTIP=
Environment=HOST=
Environment=HTTP_PROXY_USER=
Environment=HTTP_PROXY_PASSWORD=
Environment=HTTPS_PROXY_USER=
Environment=HTTPS_PROXY_PASSWORD=
Environment=CONNECTOR_POSTGRES_PASS=

To make the configuration active, you need to tell systemd to reload the configuration and restart the docker service:

sudo systemctl daemon-reload;
sudo systemctl bridgehead@bbmri.service;

Additional Services

Monitoring

We provide a central monitoring service, which checks the health of your Bridgehead 24/7. Using this service is optional but recommended.

You can register for it by sending a request to: bridgehead@helpdesk.bbmri-eric.eu.

The confirmation of your registration will contain a monitoring API key.

You need to add the key to the "/etc/bridgehead/bbmri.conf" file, e.g.:

MONITOR_APIKEY=1b9e5e21-8b34-5382-8590-7eae98a4f6d3

(your key will be different to the one shown above, obviously).

Your site should now show up in the monitoring with grey (updates) and green (query) messages at the next full hour.

Register with a Directory

The Directory is a BBMRI project that aims to catalog all biobanks in Europe and beyond. Each biobank is given its own unique ID and the Directory maintains counts of the number of donors and the number of samples held at each biobank. You are strongly encouraged to register with the Directory, because this opens the door to further services, such as the Negotiator.

Generally, you should register with the BBMRI national node for the country where your biobank is based. You can find a list of contacts for the national nodes here. If your country is not in this list, or you have any questions, please contact the BBMRI helpdesk. If your biobank is for COVID samples, you can also take advantage of an accelerated registration process here.

Your national node will give you detailed instructions for registering, but for your information, here are the basic steps:

• Log in to the Directory for your country.
• Add your biobank and enter its details, including contact information for a person involved in running the biobank.
• You will need to create at least one collection.

Site-specific configuration

HTTPS Access

We recommend https for all services of your Bridgehead. HTTPS is enabled by default. For starting the Bridgehead you need an ssl certificate. You can either create it yourself or get a signed one. You need to drop the certificates in /certs.

The Bridgehead creates one autotmatically on the first start. However, it will be unsigned and we recomend getting a signed one.

Locally Managed Secrets

This section describes the secrets you may need to configure locally through the configuration

Name	Recommended Value	Description
HTTP_PROXY_USER		Your local http proxy user
HOSTIP	Compute with: `docker run --rm --add-host=host.docker.internal:host-gateway ubuntu cat /etc/hosts	grep 'host.docker.internal'
HOST	Compute with: hostname	The hostname from which all components will eventually be available
HTTP_PROXY_PASSWORD		Your local http proxy user's password
HTTPS_PROXY_USER		Your local https proxy user
HTTPS_PROXY_PASSWORD		Your local https proxy user's password
CONNECTOR_POSTGRES_PASS	Random String	The password for your project specific connector.
STORE_POSTGRES_PASS	Random String	The password for your local datamanagements database (only relevant in c4)
ML_DB_PASS	Random String	The password for your local patientlist database
MAGICPL_API_KEY	Random String	The apiKey used by the local datamanagement to create pseudonymes.
MAGICPL_MAINZELLISTE_API_KEY	Random String	The apiKey used by the local id-manager to communicate with the local patientlist
MAGICPL_API_KEY_CONNECTOR	Random String	The apiKey used by the connector to communicate with the local patientlist
MAGICPL_MAINZELLISTE_CENTRAL_API_KEY	You need to ask the central patientlists admin for this.	The apiKey for your machine to communicate with the central patientlist
MAGICPL_CENTRAL_API_KEY	You need to ask the central controlnumbergenerator admin for this.	The apiKey for your machine to communicate with the central controlnumbergenerator
MAGICPL_OIDC_CLIENT_ID		The client id used for your machine, to connect with the central authentication service
MAGICPL_OIDC_CLIENT_SECRET		The client secret used for your machine, to connect with the central authentication service

Git Proxy Configuration

Unlike most other tools, git doesn't use the default proxy variables "http_proxy" and "https_proxy". To make git use a proxy, you will need to adjust the global git configuration:

sudo git config --global http.proxy http://<your-proxy-host>:<your-proxy-port>;
sudo git config --global https.proxy http://<your-proxy-host>:<your-proxy-port>;

NOTE: Some proxies may require user and password authentication. You can adjust the settings like this: "http://:@:". NOTE: It is also possible that a proxy requires https protocol, so you can replace this to.

You can check that the updated configuration with

sudo git config --global --list;

Docker Daemon Proxy Configuration

Docker has a background daemon, responsible for downloading images and starting them. To configure the proxy for this daemon, use the systemctl command:

sudo systemctl edit docker

This will open your default editor allowing you to edit the docker system units configuration. Insert the following lines in the editor, replace and with the corresponding values for your machine and save the file:

[Service]
Environment=HTTP_PROXY=http://<your-proxy-host>:<your-proxy-port>
Environment=HTTPS_PROXY=http://<your-proxy-host>:<your-proxy-port>
Environment=FTP_PROXY=http://<your-proxy-host>:<your-proxy-port>

NOTE: Some proxies may require user and password authentication. You can adjust the settings like this: "http://:@:". NOTE: It is also possible that a proxy requires https protocol, so you can replace this to.

The file should now be at the location "/etc/systemd/system/docker.service.d/override.conf". You can proof check with

cat /etc/systemd/system/docker.service.d/override.conf;

To make the configuration effective, you need to tell systemd to reload the configuration and restart the docker service:

sudo systemctl daemon-reload;
sudo systemctl restart docker;

Non-Linux OS

The installation procedures described above have only been tested under Linux.

Below are some suggestions for getting the installation to work on other operating systems. Note that we are not able to provide support for these routes!

We believe that it is likely that installation would also work with FreeBSD and MacOS.

Under Windows, you have 2 options:

• Virtual machine
• WSL

We have tested the installation procedure with an Ubuntu 22.04 guest system running on a VMware virtual machine. That worked flawlessly.

Installation under WSL ought to work, but we have not tested this.

License

Copyright 2019 - 2022 The Samply Community

Licensed under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at

http://www.apache.org/licenses/LICENSE-2.0

Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License.