# Bridgehead The Bridgehead is a secure, low-effort solution to connect your research institution to a federated research network. It bundles interoperable, open-source software components into a turnkey package for installation on one of your secure servers. The Bridgehead is pre-configured with sane defaults, centrally monitored and with an absolute minimum of "moving parts" on your side, making it an extremely low-maintenance gateway to data sharing. This repository is the starting point for any information and tools you will need to deploy a Bridgehead. If you have questions, please [contact us](mailto:verbis-support@dkfz-heidelberg.de). 1. [Requirements](#requirements) - [Hardware](#hardware) - [System](#system) - [Git](#git) - [Docker](#docker) 2. [Deployment](#deployment) - [Installation](#installation) - [Register with Samply.Beam](#register-with-samplybeam) - [Starting and stopping your Bridgehead](#starting-and-stopping-your-bridgehead) - [Auto-starting your Bridgehead when the server starts](#auto-starting-your-bridgehead-when-the-server-starts) 3. [Additional Services](#additional-Services) - [Monitoring](#monitoring) - [Register with a Directory](#register-with-a-Directory) 4. [Site-specific configuration](#site-specific-configuration) - [HTTPS Access](#https-access) - [Locally Managed Secrets](#locally-managed-secrets) - [Git Proxy Configuration](#git-proxy-configuration) - [Docker Daemon Proxy Configuration](#docker-daemon-proxy-configuration) - [Non-Linux OS](#non-linux-os) 5. [License](#license) ## Requirements ### Hardware Hardware requirements strongly depend on the specific use-cases of your network as well as on the data it is going to serve. Most use-cases are well-served with the following configuration: - 4 CPU cores - 32 GB RAM - 160GB Hard Drive, SSD recommended ### Software You are strongly recommended to install the Bridgehead under a Linux operating system (but see the section [Non-Linux OS](#non-linux-os)). You will need root (administrator) priveleges on this machine in order to perform the deployment. We recommend the newest Ubuntu LTS server release. Ensure the following software (or newer) is installed: - git >= 2.0 - docker >= 20.10.1 - docker-compose >= 2.xx (`docker-compose` and `docker compose` are both supported). - systemd 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. ### Network Since it needs to carry sensitive patient data, Bridgeheads are intended to be deployed within your institution's secure network and behave well even in networks in strict security settings, e.g. firewall rules. The only connectivity required is an outgoing HTTPS proxy. TLS termination is supported, too (see [below](#tls-terminating-proxies)) Note for Ubuntu: Please note that the uncomplicated firewall (ufw) is known to conflict with Docker [here](https://github.com/chaifeng/ufw-docker). ## Deployment ### Site name You will need to choose a short name for your site. This is not a URL, just a simple identifying string. For the examples below, we will use "your-site-name", but you should obviously choose something that is meaningful to you and which is unique. Site names should adhere to the following conventions: - They should be lower-case. - They should generally be named after the city where your site is based, e.g. ```karlsruhe```. - If you have a multi-part name, please use a hypen ("-") as separator, e.g. ```le-havre```. - If your site is for testing purposes, rather than production, please append "-test", e.g. ```zaragoza-test```. - If you are a developer and you are making changes to the Bridgehead, please use your name and append "-dev", e.g. ```joe-doe-dev```. ### Projects The following "projects" are known to the Bridgehead installation: - bbmri - ccp Use "bbmri" if you are in the BBMRI-ERIC European biobank network or the GBA (German Biobank Alliance) network. Use "ccp" if you are in the DKTK network, the C4 network or the nNGM network. ### GitLab repository In order to be able to install, you will need to have your own repository in GitLab for your site's configuration settings. This allows automated updates of the Bridgehead software. To request a new repository, please send an email to one of the following: - For the bbmri project: bridgehead@helpdesk.bbmri-eric.eu. - For the ccp project: support-ccp@dkfz-heidelberg.de Mention which project you belong to, i.e. "bbmri" or "ccp", plus your chosen site name. 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. - The repository's URL. - A token to access the repository. Before installation, you must set up your site's configuration in GitLab. To do this, visit the configuration repository's URL and click on the configuration file. Depending on your project, this will be called either ```bbmri.conf```or ```ccp.conf```. Use the blue button to edit it. You will need to change, as a minimum, the following variables: - SITE_NAME - SITE_ID - OPERATOR_FIRST_NAME - OPERATOR_LAST_NAME - OPERATOR_EMAIL - OPERATOR_PHONE SITE_NAME and SITE_ID can be set to the chosen name for your site, e.g. "your-site-name". OPERATOR_* should be set to values appropriate for the administrator of your site. Once you have made your changes, these will need to be reviewed by members of our team before you can proceed with the installation. ### Base Installation First, get the Bridgehead: ```shell sudo mkdir -p /srv/docker/ sudo git clone https://github.com/samply/bridgehead.git /srv/docker/bridgehead ``` Then, run the installation script: ```shell cd /srv/docker/bridgehead sudo ./bridgehead install ``` When prompted with "Please enter your site", you should enter the Repository Short Name (RSN) for GitLab that you were given in the previous section. When prompted with "Please enter the bridgehead's access token for your site configuration repository", you should enter the token for the GitLab repository that was given to you. You should then be prompted to do the next step: ### Register with Samply.Beam Many Bridgehead services rely on the secure, performant and flexible messaging middleware called [Samply.Beam](https://github.com/samply/beam). You will need to register ("enroll") with Samply.Beam by creating a cryptographic key pair for your bridgehead: ``` shell cd /srv/docker/bridgehead sudo ./bridgehead enroll ``` ... and follow the instructions on the screen. You should then be prompted to do the next step: ### Starting and stopping your Bridgehead If you followed the above steps, your Bridgehead should already be configured to autostart (via systemd). If you would like to start/stop manually: To start, run ```shell sudo systemctl start bridgehead@.service ``` To stop, run ```shell sudo systemctl stop bridgehead@.service ``` To enable/disable autostart, run ```shell sudo systemctl [enable|disable] bridgehead@.service ``` ### Testing your new Bridgehead After starting the Bridgehead, you can watch the initialization process with the following command: ```shell journalctl -u bridgehead@bbmri -f ``` if this exits with the following: ``` bridgehead@bbmri.service: Main process exited, code=exited, status=1/FAILURE ``` Then you know that there was a problem with starting the Bridgehead. Scroll up the printout to find the cause of the error. Once the Bridgehead is running, you can also view the individual Docker processes with: ```shell docker ps ``` There should be 6 Docker proceses. If there are fewer, then you know that something has gone wrong. To see what is going on, run: ```shell journalctl -u bridgehead@bbmri -f ``` Once the Bridgehead has passed these checks, take a look at the landing page: ``` https://localhost ``` You can either do this in a browser or with curl. If you visit the URL in the browser, you will neet to click through several warnings, because you will initially be using a self-signed certificate. With curl, you can bypass these checks: ```shell curl -k https://localhost ``` If you get errors when you do this, you need to use ```docker logs``` to examine your landing page container in order to determine what is going wrong. If you have chosen to take part in our monitoring program (by setting the ```MONITOR_APIKEY``` variable in the configuration), you will be informed by email when problems are detected in your Bridgehead. ### De-installing a Bridgehead You may decide that you want to remove a Bridgehead installation from your machine, e.g. if you want to migrate it to a new location or if you want to start a fresh installation because the initial attempts did not work. The following steps will remove all traces of the Bridgehead from your machine. All locally stored data pertaining to the Bridgehead will be lost. First, purge the Bridgehead from ```systemctl```: ```shell sudo systemctl stop bridgehead@bbmri.service sudo systemctl disable bridgehead@bbmri.service sudo systemctl daemon-reload sudo systemctl reset-failed ``` Now remove the directories where the Bridgehead files reside: ```shell sudo rm -rf /srv/docker/bridgehead /etc/bridgehead ``` Finally, get rid of the Docker images: ```shell docker image rm traefik:latest samply/beam-proxy:develop samply/blaze:0.18 samply/bridgehead-forward-proxy:latest samply/bridgehead-landingpage:master samply/spot:latest ``` Note that you will still have a functioning Beam certificate and a functioning GitLab configuration repository, even after you have removed everything locally. ## Site-specific configuration ### HTTPS Access Even within your internal network, the Bridgehead enforces HTTPS for all services. During the installation, a self-signed, long-lived certificate was created for you. To increase security, you can simply replace the files under `/etc/bridgehead/traefik-tls` with ones from established certification authorities such as [Let's Encrypt](https://letsencrypt.org) or [DFN-AAI](https://www.aai.dfn.de). ### TLS terminating proxies All of the Bridgehead's outgoing connections are secured by transport encryption (TLS) and a Bridgehead will refuse to connect if certificate verification fails. If your local forward proxy server performs TLS termination, please place its CA certificate in `/etc/bridgehead/trusted-ca-certs` as a `.pem` file, e.g. `/etc/bridgehead/trusted-ca-certs/mylocalca.pem`. Then, all Bridgehead components will pick up this certificate and trust it for outgoing connections. ### File structure - `/srv/docker/bridgehead` contains this git repository with the shell scripts and *project-specific configuration*. In here, all files are identical for all sites. You should not make any changes here. - `/etc/bridgehead` contains your *site-specific configuration* synchronized from your site-specific git repository as part of the [base installation](#base-installation). To change anything here, please consult your git repository (find out its URL via `git -C /etc/bridgehead remote -v`). - `/etc/bridgehead/.conf` is your main site-specific configuration, all bundled into one concise config file. Do not change it here but via the central git repository. - `/etc/bridgehead/.local.conf` contains site-specific parameters to be known to your Bridgehead only, e.g. local access credentials. The file is ignored via git, and you may edit it here via a text editor. - `/etc/bridgehead/traefik-tls` contains your Bridgehead's reverse proxies TLS certificates for [HTTPS access](#https-access). - `/etc/bridgehead/pki` contains your Bridgehead's private key (e.g., but not limited to Samply.Beam), generated as part of the [Samply.Beam enrollment](#register-with-samplybeam). - `/etc/bridgehead/trusted-ca-certs` contains third-party certificates to be trusted by the Bridgehead. For example, you want to place the certificates of your [TLS-terminating proxy](#network) here. Your Bridgehead's actual data is not stored in the above directories, but in named docker volumes, see `docker volume ls` and `docker volume inspect `. ## Things you should know ### Auto-Updates Your Bridgehead will automatically and regularly check for updates. Whenever something has been updates (e.g., one of the git repositories or one of the docker images), your Bridgehead is automatically restarted. This should happen automatically and does not need any configuration. If you would like to understand what happens exactly and when, please check the systemd units deployed during the [installation](#base-installation) via `systemctl cat bridgehead-update@.service` and `systemctl cat bridgehead-update@