Bridgehead

This repository contains all information and tools to deploy a bridgehead. If you have any questions about deploying a bridgehead, please contact us.

Table of Contents

1. About
2. Requirements
   • Hardware
   • System Requrements
     • git
     • docker
3. Getting Started
   • Installation
4. Configuration
   • Authentication
     • systemd
     • environment
   • Testing
   • After the Installation
5. Roadmap
6. Authors
7. License
8. Build With
9. Acknowledgements

---

About

The Bridgehead is a collection of Software componentens for medical informatics usecases. This repository helps the user to deploy these compoents efficently. The bridgehead contains of project independen components:

• forward proxy
• reverse proxy
• landingpage

Also, the bridgehead contains of componentens that are project specific. For deatil refer to each project in Projects.

---

Requirements

Hardware

For running your bridgehead we recommend the follwing Hardware:

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

System Requirements

Before starting the installation process, please ensure that following software is available on your system:

Git

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

git --version

Docker

To check your docker installation, you should execute the docker with --version:

docker --version

The Version should be higher than "20.10.1". Otherwise you will have problems starting the bridgehead. The next step is to check docker-compose with:

docker-compose --version

The recomended version is "2.XX" and higher. If docker-compose was not installed with docker follow these instructions. To futher check your docker and docker-compose installation, please run the following command.

docker-compose -f - up <<EOF
version: "3.7"
services:
  hello-world:
    image: hello-world
EOF

Docker will now download the "hello-world" docker image and try to execute it. After the download you should see a message starting with "Hello from Docker!".

NOTE: If the download of the image fails (e.g with "connection timed out" message), ensure that you have correctly set the proxy for the docker daemon. Refer to "Docker Daemon Proxy Configuration" in the "Pitfalls" section

systemd

You shouldn't need to install it yourself, If systemd is not available on your system you should get another system. To check if systemd is available on your system, please execute

systemctl --version

If systemd is not installed, you can start the bridgehead. However, for productive use we recomend using systemd.

---

Getting Started

Installation

If your system passed all checks from ["Requirements" section], you are now ready to download the bridgehead.

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;

It is recomended to create a user for the bridgehead service. This should be done after clone the repository. Since not all linux distros support adduser, we provide an action for the systemcall useradd. You should try the first one, when the systm can't create the user you should try the second one.

adduser --no-create-home --disabled-login --ingroup docker --gecos "" bridgehead

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

After adding the User you need to change the ownership of the directories to the bridgehead user.

chown bridgehead /srv/docker/bridgehead/ -R

Configuration

NOTE: If you are part of the CCP-IT we will provide you another link for the configuration.

Next, you need to configure a set of variables, specific for your site with not so high security concerns. You can clone the configuration template at GitHub. The confiugration of the bridgehead should be located in /etc/bridghead.

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

After cloning or forking the repository you need to add value to the template. If you are a part of the CCP-IT you will get an already filled out config repo.

After cloning your configuration you need to change the ownership of the folder aswell.

chown bridgehead /etc/bridgehead/ -R

Basic Auth

• TODO: Explain what will work without this

For data protection we use basic authenfication for some services. To access those services you need an username and password combination. If you start the bridgehead without basic auth, then those services are not accesbile. We provide a script to generate a basic auth login.

lib/add_bc_user.sh

The result needs to be set in either in the systemd service or in your environment.

systemd

sudo systemctl edit <project>

[Service]
...
Environment=bc_auth_users=<hash>

without systemd

Either add the hash to the environment with an export, or add it to /etc/environment

export bc_auth_user=<output>

Cation: for exporting need to escape occurring dollar signs with back slashes.

Testing your bridgehead

We recomend to run first with the start and stop script. If you have trouble starting the bridghead have a look at the troubleshooting section.

Now you ready to run a bridgehead instance. The bridgehead scripts checks if your configuration is correct. To check if everything works, execute the following:

/srv/docker/bridgehead/bridgehead start <Project>

You should now be able to access the landing page on your system, e.g "https:///".

To shutdown the bridgehead just run.

/srv/docker/bridgehead/bridgehead stop <Project>

After the Installation

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.

---

Roadmap 🚀

• Securely manage secrets using the vault warden fetcher
• Integrate the samply/share-client for the DKTK project with the new deployment
• Replace the multiple docker-compose files by using a template engine (e.g. Jinja) driven approach
• Migrate sites using samply/bridgehead-deployment
• Integrate an OAuth Provider (e.g. keycloak) in the deployment package to replace basic authentication for local components

---

Authors

• Patrick Skowronek - Team Member
• Martin Lablans - Team Member
• Torben Brenner - Team Member
• David Croft - Team Member

---

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.

---

Build With

• Git
• Docker
• Docker Compose
• systemd

---

Acknowledgements

• samply/bridgehead-deployment