From 28fcb2159cd28f84c04b0e7ec2638da8fb79cc8c Mon Sep 17 00:00:00 2001 From: Patrick Skowronek Date: Tue, 22 Mar 2022 09:43:07 +0100 Subject: [PATCH] Added more about the bridgehead in the README --- README.md | 102 ++++++++++++++++++++++++++++++++++++++++++++++++++++-- 1 file changed, 100 insertions(+), 2 deletions(-) diff --git a/README.md b/README.md index fce60cf..7745b47 100644 --- a/README.md +++ b/README.md @@ -2,10 +2,16 @@ This repository contains all information and tools to deploy a bridgehead. If you have any questions about deploying a bridgehead, please [contact us](mailto:verbis-support@dkfz-heidelberg.de). -TODO: Insert comprehensive feature list of the bridgehead? Why would anyone install it? TOC +1. [About](#about) + - [Projects](#projects) + - [GBA/BBMRI-ERIC](#gbabbmri-eric) + - [DKTK/C4](#dktkc4) + - [NNGM](#nngm) + - [Bridgehead Components](#bridgehead-components) + - [Blaze Server](#blaze-serverhttpsgithubcomsamplyblaze) 1. [Requirements](#requirements) - [Hardware](#hardware) - [System](#system-requirements) @@ -22,6 +28,42 @@ TOC 7. [License](#license) +## About + +TODO: Insert comprehensive feature list of the bridgehead? Why would anyone install it? + +### Projects + +#### GBA/BBMRI-ERIC + +The **Sample Locator** is a tool that allows researchers to make searches for samples over a large number of geographically distributed biobanks. Each biobank runs a so-called **Bridgehead** at its site, which makes it visible to the Sample Locator. The Bridgehead is designed to give a high degree of protection to patient data. Additionally, a tool called the [Negotiator][negotiator] puts you in complete control over which samples and which data are delivered to which researcher. + +You will most likely want to make your biobanks visible via the [publicly accessible Sample Locator][sl], but the possibility also exists to install your own Sample Locator for your site or organization, see the GitHub pages for [the server][sl-server-src] and [the GUI][sl-ui-src]. + +The Bridgehead has two primary components: +* The **Blaze Store**. This is a highly responsive FHIR data store, which you will need to fill with your data via an ETL chain. +* The **Connector**. This is the communication portal to the Sample Locator, with specially designed features that make it possible to run it behind a corporate firewall without making any compromises on security. + +#### DKTK/C4 + +TODO: + +#### NNGM + +TODO: + +### Bridgehead Components + +#### [Blaze Server](https://github.com/samply/blaze) + +This holds the actual data being searched. This store must be filled by you, generally by running an ETL on your locally stored data to turn it into the standardized FHIR format that we require. + +#### [Connector] + +TODO: + + + ## Requirements ### Hardware @@ -100,8 +142,10 @@ If your system passed all checks from ["Requirements" section], you are now read First, clone the repository to the directory "/srv/docker/bridgehead": +u + ``` shell -sudo mkdir /srv/docker/; +sudo mkdir -p /srv/docker/; sudo git clone https://github.com/samply/bridgehead.git /srv/docker/bridgehead; ``` @@ -397,6 +441,60 @@ sudo systemctl daemon-reload; sudo systemctl restart docker; ``` +## After the Installtion + +After starting your bridgehead, visit the landing page under the hostname. If you singed your own ssl certificate, there is probable an error message. However, you can accept it as exception. + +On this page, there are all important links to each component, central and local. + +### Connector Administration + +The Connector administration panel allows you to set many of the parameters regulating your Bridgehead. Most especially, it is the place where you can register your site with the Sample Locator. To access this page, proceed as follows: + +* Open the Connector page: https:///-connector/ +* In the "Local components" box, click the "Samply Share" button. +* A new page will be opened, where you will need to log in using the administrator credentials (admin/adminpass by default). +* After log in, you will be taken to the administration dashboard, allowing you to configure the Connector. +* If this is the first time you have logged in as an administrator, you are strongly recommended to set a more secure password! You can use the "Users" button on the dashboard to do this. + +### GBA/BBMRI-ERIC + +#### Register with a Directory + +The [Directory][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][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](http://www.bbmri-eric.eu/national-nodes/). If your country is not in this list, or you have any questions, please contact the [BBMRI helpdesk](mailto:directory@helpdesk.bbmri-eric.eu). If your biobank is for COVID samples, you can also take advantage of an accelerated registration process [here](https://docs.google.com/forms/d/e/1FAIpQLSdIFfxADikGUf1GA0M16J0HQfc2NHJ55M_E47TXahju5BlFIQ). + +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. +* Note the biobank ID and the collection ID that you have created - these will be needed when you register with the Locator (see below). + +#### Register with a Locator + +* Go to the registration page http://localhost:8082/admin/broker_list.xhtml. +* To register with a Locator, enter the following values in the three fields under "Join new Searchbroker": + * "Address": Depends on which Locator you want to register with: + * `https://locator.bbmri-eric.eu/broker/`: BBMRI Locator production service (European). + * `http://147.251.124.125:8088/broker/`: BBMRI Locator test service (European). + * `https://samplelocator.bbmri.de/broker/`: GBA Sample Locator production service (German). + * `https://samplelocator.test.bbmri.de/broker/`: GBA Sample Locator test service (German). + * "Your email address": this is the email to which the registration token will be returned. + * "Automatic reply": Set this to be `Total Size` +* Click "Join" to start the registration process. +* You should now have a list containing exactly one broker. You will notice that the "Status" box is empty. +* Send an email to `feedback@germanbiobanknode.de` and let us know which of our Sample Locators you would like to register to. Please include the biobank ID and the collection ID from your Directory registration, if you have these available. +* We will send you a registration token per email. +* You will then re-open the Connector and enter the token into the "Status" box. +* You should send us an email to let us know that you have done this. +* We will then complete the registration process +* We will email you to let you know that your biobank is now visible in the Sample Locator. + +If you are a Sample Locator administrator, you will need to understand the [registration process](./SampleLocatorRegistration.md). Normal bridgehead admins do not need to worry about this. + + ## License Copyright 2019 - 2022 The Samply Community