Network Deployment

Deployment of profile test-network.

This profile deploys an arbitrary set of MedCo nodes independently in different machines that together form a MedCo network. This deployment assumes each node is deployed in a single dedicated machine. All the machines have to be reachable between each other. Nodes should agree on a network name and individual indexes beforehand (to be assigned a unique ID).

The next set of steps must be fully executed individually by each node of the network.

Pre-requisites

First step is to get the MedCo Deployment latest release at each node. Adapt ${MEDCO_SETUP_DIR} to where you wish to install MedCo.

export MEDCO_SETUP_DIR=~/medco MEDCO_SETUP_VER=v3.0.0
git clone --depth 1 --branch ${MEDCO_SETUP_VER} https://github.com/ldsec/medco.git ${MEDCO_SETUP_DIR}

Generation of the deployment Profile

Next the compose and configuration profiles must be generated using a script, executed in two steps.

• Step 1: each node generates its keys and certificates, and shares its public information with the other nodes

• Step 2: each node collects the public keys and certificates of the all the other nodes

Step 1

For step 1, the network name ${MEDCO_SETUP_NETWORK_NAME} should be common to all the nodes. ${MEDCO_SETUP_NODE_DNS_NAME} corresponds to the machine domain name where the node is being deployed. As mentioned before the different parties should have agreed beforehand on the members of the network, and assigned an index ${MEDCO_SETUP_NODE_IDX} to each different node to construct its UID (starting from 0, to n-1, n being the total number of nodes).

$ bash step1.sh MANDATORY [OPTIONAL]
MANDATORY:
  -nn,   --network_name  VAL  Network name (e.g. test-network-deployment)
  -ni,   --node_index    VAL  Node index (e.g. 0, 1, 2)
  -dns,  --node_dns_name VAL  Server dns name

OPTIONAL:
  -pk,   --public_key    VAL  Unlynx node public key
  -sk,   --secret_key    VAL  Unlynx node private key
  -crt,  --certificate   VAL  Filepath to certificate (*.crt)
  -k,    --key           VAL  Filepath to certificate key (*.key)
  -h,    --help 

export MEDCO_SETUP_NETWORK_NAME=example \
    MEDCO_SETUP_NODE_IDX=0 \
    MEDCO_SETUP_NODE_DNS_NAME=medconode0.example.com
cd "${MEDCO_SETUP_DIR}/scripts/network-profile-tool"
bash step1.sh -nn ${MEDCO_SETUP_NETWORK_NAME} -ni ${MEDCO_SETUP_NODE_IDX} -dns ${MEDCO_SETUP_NODE_DNS_NAME}

This script will generate the compose profile and part of the configuration profile, including a file srv${MEDCO_SETUP_NODE_IDX}-public.tar.gz. This file should be shared with the other nodes, and all of them need to place it in their configuration profile folder (${MEDCO_SETUP_DIR}/deployments/test-network-${MEDCO_SETUP_NETWORK_NAME}-node${MEDCO_SETUP_NODE_IDX}/configuration).

Step 2

Before proceeding to this step, you need to have gathered all the files srv${MEDCO_SETUP_NODE_IDX}-public.tar.gz from the persons deploying MedCo on the other nodes.

Once all nodes have shared their srv${MEDCO_SETUP_NODE_IDX}-public.tar.gz file with all other nodes, step 2 can be executed:

$ bash step2.sh MANDATORY [OPTIONAL]
MANDATORY:
  -nn,   --network_name  VAL  Network name (e.g. test-network-deployment)
  -ni,   --node_index    VAL  Node index (e.g. 0, 1, 2)
OPTIONAL:
  -s,    --secrets       VAL  Secret0,Secret1,...
  -h,    --help

cd "${MEDCO_SETUP_DIR}/scripts/network-profile-tool"
bash step2.sh -nn ${MEDCO_SETUP_NETWORK_NAME} -ni ${MEDCO_SETUP_NODE_IDX}

At this point, it is possible to edit the default configuration generated in ${MEDCO_SETUP_DIR}/deployments/test-network-${MEDCO_SETUP_NETWORK_NAME}-node${MEDCO_SETUP_NODE_IDX}/.env This is needed in order to modify the default passwords. When editing this file, be careful to change only the passwords and not the other values.

The deployment profile is now ready to be used.

MedCo Stack Deployment

Next step is to download the docker images and run the node:

cd "${MEDCO_SETUP_DIR}/deployments/test-network-${MEDCO_SETUP_NETWORK_NAME}-node${MEDCO_SETUP_NODE_IDX}"
make pull
make up

Wait some time for the initialization of the containers to be done, this can take up to 10 minutes. For the subsequent runs, the startup will be faster. You can use make stop to stop the containers and make down to delete them.

Keycloak Configuration

You will need to follow two sets of instruction to make Keycloak functional and be able to log in. Access the Keycloak administration interface and then:

• Update the MedCo OIDC client

• Update the Keycloak realm keys

Test the deployment

Note that by default the certificates generated by the script are self-signed and thus, when using Glowing Bear, the browser will issue a security warning. To use your own valid certificates, see HTTPS Configuration. If you wish anyway to use the self-signed certificates, you will need to visit individually the page of Glowing Bear of all nodes in your browser, and select to trust the certificate.

The database is pre-loaded with some encrypted test data using a key that is pre-generated from the combination of all the participating nodes’ public keys. For the network deployment profile this data will not be correctly encrypted, since the public key of each node is generated independently, and, as such, the data must be re-loaded before being able to test the system successfully.

Run first the MedCo loader (see Loading Data) to load some data and be able to test this deployment. Or to load some test data by performing a simple data loading you can execute the following:

make load_test_data

Then access Glowing Bear in your web browser at https://${MEDCO_SETUP_NODE_DNS_NAME} and use the default credentials specified in Keycloak user management. If you are new to Glowing Bear you can watch the Glowing Bear user interface walkthrough video. You can also use the CLI client to perform tests.