Merge 6123a9aeba into e4ac27061a

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 <PROJECT>
 ```
 
-... 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@<PROJECT>.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