verbis-admin
/
bridgehead
1
0
Fork 0
Code Issues Packages Projects Releases Wiki Activity

Result from Meeting with Patrick

This commit is contained in:
Torben Brenner 2022-03-01 17:24:53 +01:00
parent 1f6ae18cfb
commit c53ae9173c
7 changed files with 139 additions and 53 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

183
README.md
View File

@ -4,6 +4,8 @@ This repository contains all information and tools to deploy a bridgehead. If yo
TODO: Insert comprehensive feature list of the bridgehead? Why would anyone install it? TODO: Insert comprehensive feature list of the bridgehead? Why would anyone install it?
TODO: TOC
## Requirements ## Requirements
Before starting the installation process, please ensure that following software is available on your system: Before starting the installation process, please ensure that following software is available on your system:
@ -24,9 +26,15 @@ docker run --rm --name hello-world hello-world;
``` ```
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!". 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]() > 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](#docker-daemon-proxy-configuration)
### [Docker Compose](https://docs.docker.com/compose/install/) You should also check, that the version of docker installed by you is newer than "1.20". To check this, just run
``` shell
docker --version
```
### [Docker Compose](https://docs.docker.com/compose/cli-command/#installing-compose-v2)
To check your docker-compose installation, please run the following command. It uses the "hello-world" image from the previous section: To check your docker-compose installation, please run the following command. It uses the "hello-world" image from the previous section:
``` shell ``` shell
docker-compose -f - up <<EOF docker-compose -f - up <<EOF
@ -38,6 +46,12 @@ EOF
``` ```
After executing the command, you should again see the message starting with "Hello from Docker!". After executing the command, you should again see the message starting with "Hello from Docker!".
You should also ensure, that the version of docker-compose installed by you is newer than "2.XX". To check this, just run
``` shell
docker-compose --version
```
### [systemd](https://systemd.io/) ### [systemd](https://systemd.io/)
You shouldn't need to install it yourself. If systemd is not available on your system you should get another system. 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 To check if systemd is available on your system, please execute
@ -57,30 +71,77 @@ sudo mkdir /srv/docker/;
sudo git clone https://github.com/samply/bridgehead.git /srv/docker/bridgehead; sudo git clone https://github.com/samply/bridgehead.git /srv/docker/bridgehead;
``` ```
Next, you need to download the cooperatively created site-configuration to the directory "/srv/docker/bridgehead/site-config": Next, you need to configure a set of variables, specific for your site with not so high security concerns. You can visit the configuration template at [GitHub](https://github.com/samply/bridgehead-config). You can download the repositories contents and add them to the "bridgehead-config" directory.
``` shell ``` shell
sudo git clone <link-to-sites-configuration-repository> /srv/docker/bridgehead/site-config; sudo git submodule add -f https://github.com/samply/bridgehead-config.git ./site-config;
```
> NOTE: If you are part of the CCP-IT we will provide you another link for the configuration.
You should now be able to run a bridgehead instance. To check if everything works, execute the following:
``` shell
sudo ./lib/init-test-environment.sh;
sudo ./start-bridgehead.sh <dktk/gbn/c4>;
``` ```
After this, you need to install the systemd units. This is currently done with the [install-bridgehead.sh script](./install-bridgehead.sh). You should now be able to access the landing page on your system, e.g "http://<your-host>/"
You can execute it with To remove the test-environment, run (make sure you don't have other docker services installed on this system, docker volume prune is destructive!)
``` shell ``` shell
sudo ./install-bridgehead.sh sudo ./stop-bridgehead.sh <dktk/gbn/c4>;
sudo docker volume prune;
```
For a server, we highly recommend that you install the system units for managing the bridgehead, provided by us. . You can do this by executing the [setup-bridgehead-units.sh](./lib/setup-bridgehead-units.sh) script:
``` shell
sudo ./lib/setup-bridgehead-units.sh
``` ```
Finally, you need to configure your sites secrets. These are places as configuration for each bridgeheads system unit. Refer to the section for your specific project: Finally, you need to configure your sites secrets. These are places as configuration for each bridgeheads system unit. Refer to the section for your specific project:
### DKTK/C4 ### DKTK/C4
You can create the site specific configuration with: You can create the site specific configuration with:
``` shell ``` shell
sudo systemctl edit bridgehead@dktk.service; sudo systemctl edit bridgehead@dktk.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. You share some of the ID-Management secrets with the central patientlist (Mainz) and controlnumbergenerator (Frankfurt). Refer to the ["Configuration" section]() for this. 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. You share some of the ID-Management secrets with the central patientlist (Mainz) and controlnumbergenerator (Frankfurt). Refer to the ["Configuration" section](#configuration) for this.
``` conf
[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=
Environment=ML_DB_PASS=
Environment=MAGICPL_API_KEY=
Environment=MAGICPL_MAINZELLISTE_API_KEY=
Environment=MAGICPL_API_KEY_CONNECTOR=
Environment=MAGICPL_MAINZELLISTE_CENTRAL_API_KEY=
Environment=MAGICPL_CENTRAL_API_KEY=
Environment=MAGICPL_OIDC_CLIENT_ID=
Environment=MAGICPL_OIDC_CLIENT_SECRET=
```
To make the configuration effective, you need to tell systemd to reload the configuration and restart the docker service:
``` shell
sudo systemctl daemon-reload;
sudo systemctl bridgehead@dktk.service;
```
### C4
You can create the site specific configuration with:
``` shell
sudo systemctl edit bridgehead@c4.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. You share some of the ID-Management secrets with the central patientlist (Mainz) and controlnumbergenerator (Frankfurt). Refer to the ["Configuration" section](#configuration) for this.
``` conf ``` conf
[Service] [Service]
@ -102,25 +163,18 @@ Environment=MAGICPL_OIDC_CLIENT_ID=
Environment=MAGICPL_OIDC_CLIENT_SECRET= Environment=MAGICPL_OIDC_CLIENT_SECRET=
``` ```
For the C4 project, you need to additionally set the "LDM_URL_BASE" setting in the configuration table to null. You need to execute this after starting the bridgehead system unit for c4:
``` shell
docker exec bridgehead-c4-connector-db-1 bash -c 'psql -U $POSTGRES_USER $POSTGRES_DB -c "UPDATE samply.configuration SET setting=\'\' WHERE name=\'LDM_URL_BASE\'"';
```
To make the configuration effective, you need to tell systemd to reload the configuration and restart the docker service: To make the configuration effective, you need to tell systemd to reload the configuration and restart the docker service:
``` shell ``` shell
sudo systemctl daemon-reload; sudo systemctl daemon-reload;
sudo systemctl restart docker; sudo systemctl bridgehead@c4.service;
``` ```
### GBA/BBMRI-ERIC ### GBA/BBMRI-ERIC
You can create the site specific configuration with: You can create the site specific configuration with:
``` shell ``` shell
sudo systemctl edit bridgehead@dktk.service; sudo systemctl edit bridgehead@gbn.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. 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.
@ -140,47 +194,82 @@ To make the configuration effective, you need to tell systemd to reload the conf
``` shell ``` shell
sudo systemctl daemon-reload; sudo systemctl daemon-reload;
sudo systemctl restart docker; sudo systemctl bridgehead@gbn.service;
``` ```
### Developers ### Developers
Because some developers machines doesn't support system units (e.g Windows Subsystem for Linux), we provide a dev environment [configuration script](./init-dev-environment.sh). Because some developers machines doesn't support system units (e.g Windows Subsystem for Linux), we provide a dev environment [configuration script](./lib/init-test-environment.sh).
It is not recommended to use this script in production! It is not recommended to use this script in production!
## Configuration ## Configuration
### Locally Managed Secrets ### Locally Managed Secrets
This section describes the secrets you need to configure locally through the configuration This section describes the secrets you need to configure locally through the configuration
|Name|Recommended Value|Description|
|HOSTIP|Compute with: `docker run --rm --add-host=host.docker.internal:host-gateway ubuntu cat /etc/hosts | grep 'host.docker.internal' | awk '{print $1}'`|The ip from which docker containers can reach your host system.| | Name | Recommended Value | Description |
|HOST|Compute with: `hostname`|The hostname from which all components will eventually be available| |--------------------------------------|---------------------------------------------------------------------------------------------------| ----------- |
|HTTP_PROXY_USER||Your local http proxy user| | HTTP_PROXY_USER | | Your local http proxy user |
|HTTP_PROXY_PASSWORD||Your local http proxy user's password| | HOSTIP | Compute with: `docker run --rm --add-host=host.docker.internal:host-gateway ubuntu cat /etc/hosts | grep 'host.docker.internal' | awk '{print $1}'` | The ip from which docker containers can reach your host system. |
|HTTPS_PROXY_USER||Your local https proxy user| | HOST | Compute with: `hostname` |The hostname from which all components will eventually be available|
|HTTPS_PROXY_PASSWORD||Your local https proxy user's password| | HTTP_PROXY_PASSWORD | |Your local http proxy user's password|
|CONNECTOR_POSTGRES_PASS|Random String|The password for your project specific connector.| | HTTPS_PROXY_USER | |Your local https proxy user|
|STORE_POSTGRES_PASS|Random String|The password for your local datamanagements database (only relevant in c4)| | HTTPS_PROXY_PASSWORD || Your local https proxy user's password |
|ML_DB_PASS|Random String|The password for your local patientlist database| | CONNECTOR_POSTGRES_PASS | Random String |The password for your project specific connector.|
|MAGICPL_API_KEY|Random String|The apiKey used by the local datamanagement to create pseudonymes.| | STORE_POSTGRES_PASS | Random String |The password for your local datamanagements database (only relevant in c4)|
|MAGICPL_MAINZELLISTE_API_KEY|Random String|The apiKey used by the local id-manager to communicate with the local patientlist| | ML_DB_PASS | Random String |The password for your local patientlist database|
|MAGICPL_API_KEY_CONNECTOR|Random String|The apiKey used by the connector to communicate with the local patientlist| | MAGICPL_API_KEY | Random String |The apiKey used by the local datamanagement to create pseudonymes.|
|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_MAINZELLISTE_API_KEY | Random String |The apiKey used by the local id-manager to communicate with the local 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_API_KEY_CONNECTOR | Random String |The apiKey used by the connector to communicate with the local patientlist|
|MAGICPL_OIDC_CLIENT_ID||The client id used for your machine, to connect with the central authentication service| | 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_OIDC_CLIENT_SECRET||The client secret used for your machine, to connect with the central authentication service| | 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 |
### Cooperatively Managed Secrets ### Cooperatively Managed Secrets
> TODO: Describe secrets from site-config > TODO: Describe secrets from site-config
## Managing your Bridgehead ## Managing your Bridgehead
> TODO: Rewrite this section (restart, stop, uninstall, manual updates) > TODO: Rewrite this section (restart, stop, uninstall, manual updates)
There two methods to start the bridgehead. For Windows, Linux and Mac OS you can use the start-bridgehead.sh to deploy it wit docker-compose. If will also check some other setting of your system. ### On a Server
#### Start
The second methods is using the systemd management tool you start, stop and update your bridgehead. This will start a not running bridgehead system unit:
``` shell
Just run the install-bridgehead and thats it. sudo systemctl start bridgehead@<dktk/c4/gbn>
```
#### Stop
This will stop a running bridgehead system unit:
``` shell
sudo systemctl stop bridgehead@<dktk/c4/gbn>
```
#### Update
This will update bridgehead system unit:
``` shell
sudo systemctl start bridgehead-update@<dktk/c4/gbn>
```
#### Remove the Bridgehead System Units
If, for some reason you want to remove the installed bridgehead units, we added a [script](./lib/remove-bridgehead-units.sh) you can execute:
``` shell
sudo ./lib/remove-bridgehead-units.sh
```
### On Developers Machine
For developers, we provide additional scripts for starting and stopping the specif bridgehead:
#### Start
This shell script start a specified bridgehead. Choose between "dktk", "c4" and "gbn".
``` shell
./start-bridgehead <dktk/c4/gbn>
```
#### Stop
This shell script stops a specified bridgehead. Choose between "dktk", "c4" and "gbn".
``` shell
./stop-bridgehead <dktk/c4/gbn>
```
#### Update
This shell script updates the configuration for all bridgeheads installed on your system.
``` shell
./update-bridgehead
```
> NOTE: If you want to regularly update your developing instance, you can create a CRON job that executes this script.
## Migration Guide ## Migration Guide
> TODO: How to transfer from windows/gbn > TODO: How to transfer from windows/gbn
@ -189,8 +278,8 @@ Just run the install-bridgehead and thats it.
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: 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:
``` shell ``` shell
git config --global http.proxy http://<your-proxy-host>:<your-proxy-port>; sudo git config --global http.proxy http://<your-proxy-host>:<your-proxy-port>;
git config --global https.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://<your-proxy-user>:<your-proxy-user-password>@<your-proxy-host>:<your-proxy-port>". > NOTE: Some proxies may require user and password authentication. You can adjust the settings like this: "http://<your-proxy-user>:<your-proxy-user-password>@<your-proxy-host>:<your-proxy-port>".
> NOTE: It is also possible that a proxy requires https protocol, so you can replace this to. > NOTE: It is also possible that a proxy requires https protocol, so you can replace this to.
@ -198,11 +287,9 @@ git config --global https.proxy http://<your-proxy-host>:<your-proxy-port>;
You can check that the updated configuration with You can check that the updated configuration with
``` shell ``` shell
git config --global --list; sudo git config --global --list;
``` ```
Please repeat this configuration for the root user to. Otherwise the update service won't be able to properly update the git repository.
### Docker Daemon Proxy Configuration ### 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: Docker has a background daemon, responsible for downloading images and starting them. To configure the proxy for this daemon, use the systemctl command:

1
dktk/docker-compose.yml
View File

@ -1,4 +1,3 @@
# TODO: Is there a reason why the docker-compose files are not at root level? e.g. docker-compose.(dktk|gbn|c4).yml
version: "3.7" version: "3.7"
volumes: volumes:
dktk-connector-db-data: dktk-connector-db-data:

0
init-dev-environment.sh → lib/init-test-environment.sh
View File

0
uninstall-bridgehead.sh → lib/remove-bridgehead-units.sh
View File

0
install-bridgehead.sh → lib/setup-bridgehead-units.sh
View File

4
start-bridgehead.sh
View File

@ -7,10 +7,10 @@ if ! lib/prerequisites.sh; then
log "Prerequisites failed, exiting" log "Prerequisites failed, exiting"
exit exit
fi fi
source site.conf
log "Starting bridgehead" log "Starting bridgehead"
docker-compose -f ${project}/docker-compose.yml --env-file site-config/${project}.env up -d # TODO: Check $1 for proper values
docker-compose -f $1/docker-compose.yml --env-file bridgehead-config/$1.env up -d
log "The bridgehead should be in online in a few seconds" log "The bridgehead should be in online in a few seconds"

4
stop-bridgehead.sh
View File

@ -1,8 +1,8 @@
#!/bin/bash -e #!/bin/bash -e
source lib/functions.sh source lib/functions.sh
source site.conf
log "Stopping bridgehead" log "Stopping bridgehead"
docker-compose -f ${project}/docker-compose.yml --env-file site-config/${project}.env down # TODO: Check $1 for proper values
docker-compose -f $1/docker-compose.yml --env-file bridgehead-config/$1.env down