diff --git a/README.md b/README.md index 8fba0c9..1a11867 100644 --- a/README.md +++ b/README.md @@ -58,9 +58,64 @@ Note for Ubuntu: Please note that the uncomplicated firewall (ufw) is known to c ## 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, clone the repository to the directory `/srv/docker/bridgehead`: +First, get the Bridgehead: ```shell sudo mkdir -p /srv/docker/ @@ -74,7 +129,11 @@ cd /srv/docker/bridgehead sudo ./bridgehead install ``` -... and follow the instructions on the screen. You should then be prompted to do the next step: +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 @@ -109,6 +168,79 @@ To enable/disable autostart, run 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