Skip to main content

Deploy your own Client

Prerequisites​

Furthermore if you want to access the FLNet Client also from another machine, you need to ensure HTTPS encryption or if this isn't possible use an ssh tunnel to connect to the FLNet Client. If you only ever access the FLNet Client from the same machine you can skip these two steps and in the initialization just run the FLNet Client on 127.0.0.1 (localhost) and a chosen port, accessing it from the browser on the same machine.

Special prerequisites to take during development​

As the docker registry is not yet public, the images for the FLNet Client as well as app images used by the FLNet Client for federated learning and the ETL process are currently behind an auth check. Therefore please contact a FLNet developer to provide you with credentials:

  • A username
  • A Gitlab Personal Access Token (PAT) You will be provided with credentials that can pull images from the FLNet registry. Given this PAT, please do the following:
docker login gitlab.cosy.bio:5050

As username use the username, as password the PAT given.

Deploying your FLNet Client​

Please follow these steps to create, run and setup your FLNet Client in 5 to 15 minutes.

0. Prepare​

First make sure the prerequisites are all installed! Then, clone the repository containing the FLNet Client setup:

git clone https://github.com/fedDBNet/FedDB-Client-Deployment.git

And cd into the cloned folder

cd FedDB-Client-Deployment/

1. Creating the FLNet Client folder​

Simply run the initialization script and follow the command line prompts:

python3 client_installer.py

You will need to specify:

  • The IP the Client should listen on. Choose 127.0.0.1 if you use your own reverse proxy, a (reverse) ssh tunnel or only access the Client from the machine the Client is running on.
  • The port the Client should listen on. The port should be free. If you deploy onto 0.0.0.0 to allow direct access from the Internet to the Client, we recommend to use 443 as this is the standard https port. This way you can access your Client via <your-domain> instead of having to specify a port like <your-domain:5555>
  • The domain name used. If you only access the Client from this machine/use a SSH tunnel, this can stay empty. However if you want to access it from the Internet/Intranet we recommend to have a domain and ssl certificates to secure the connection.
  • The ssl certificate files. Refer to this section on how to generate these files.

After running the installer, the flnet_client folder is ready to be used. The install script will provide you with the next steps, but they are also listed here.

2. Running your created FLNet Client​

To start the Client, run the following:

cd flnet_client
docker compose up -d

The first start up might take upto a few minutes.

3. The initial setup of the FLNet Client​

3.1 First login as the admin user​

Now you need to update the initial admin account created for you. Please access the Client. If you gave a domain, use the domain name. Otherwise use the given IP and port. The authentication service is available at auth/, so e.g. at <your-domain>/auth/ In case you missed the initial password given by the initialization script, the initial username and password can be found in flnet_client/env/keycloak-secrets.env as the KC_BOOTSTRAP_ADMIN_PASSWORD. Use these credentials to log in.

Please immediately change the password, this can be done via the upper right corner under manage account. If going to the account management page causes an infinite reload glitch, you need to

  1. Go to the Clients page. This is found on the left site.
  2. Go to the account-console client by clicking on it's client id.
  3. In Web Origins, add a plus. This just allows the redirect URLS to also be origins of requests.

3.2 Create a user for the FLNet Client​

The FLNet Client is initialized without any users. To create one:

  1. On the left site go to Manage Realms and chose the FLNet-Client realm.
  2. On the left site select users and add a user. Make sure to tick Email verified or connect a SMTP server to the KeyCloak instance! Alternatively you can deactivate that email verification is required.

Make sure that the user joins a group or they will not be able to do anything. For more information about the groups, click on groups. Alternatively, here is a description of the groups:

Admin: Members of the Admin group may see and edit anything, having full access.

Data-Access-Manager: Members of the Data-Access-Manager group may see all patient data, but cannot edit it or add new data. Furthermore, they can control access via the network in the form of queries or federated learning. They have access to all logs.

Data-Admin: Members of the Data-Admin group may read, edit and add patient data. Furthermore, they may see all logs related to the addition, updating or removal of patient data.

The Client is now ready to be used, simply visit it at the domain you chose (or IP:port) and use the user you just created.

Further information​

Server availability 24/7​

The FLNet allows discovery of data at any point in time. To also be able to discover your data, your machine needs to be connected. Therefore, we recommend running the server/machine that participates in the FLNet 24/7. The docker containers deployed are set to restart unless manually stopped, so on restart the client should just restart. If you want to make sure, simply start the client again. Everything is persisted in docker volumes.

Securing your Client: Access to the FLNet Client from other machines​

Access to the FLNet Client is via a webserver it deploys. If you access the Client only from the same machine where it is running there are no further setup steps needed, you can use the machines browser and the address you configures, e.g. localhost:8250.

However if you want to access the node from another machine, you should either:

Generating SSL certificates (automatically)​

SSL certificates are the keys used for the encryption of traffic to/from the FLNet Client. The FLNet Client needs these keys to encrypt the traffic, using the NGINX reverse proxy shipped with the Client. If you use your own reverse proxy, refer to the advanced documentation on this We recommend to use letsencrypt.

SSL certificates are usually bound to a domain, so please register a domain/subdomain first before continuing. The FLNet Client is then accessed via the browser and this domain.

If your server is accessible from the internet We recommend using certbot. After installing certbot, run the following command, replacing yourdomain.com with your own domain.

sudo certbot certonly --standalone \
  -d <yourdomain.com> \
  --deploy-hook "docker exec flnet_client-reverse-proxy-encrypted-1 nginx -s reload"

This will generate the SSL certificates as well as take care of renewal. Please note that the deploy hook will initially fail as the FLNet Client has not been setup and you might find error logs in the certbot logs. THis is not an issue though as the FLNet Client is setup in the next step.

If your server is not accessible from the internet, e.g. it is behind a VPN or demilitarized zone SSL certificate authorities usually verify your domain by sending a request to your server running the FLNet Client.

If your server is not reachable via the internet this is not possible. You have multiple options:

  1. Generate self signed certificates. When you access the FLNet Client via the Browser a security warning will show, but traffic will be encrypted. You can generate self signed SSL certificates via this command: sudo openssl req -x509 -nodes -days 365 -newkey rsa:2048 -keyout /etc/ssl/private/my-self-signed.key -out /etc/ssl/certs/my-self-signed.crt This generates SSL certificates valid for a year. The files generated will be /etc/ssl/private/my-self-signed.key and /etc/ssl/certs/my-self-signed.crt. Make sure to (automatically) renew them before they expire. After renewal, you need to run the following command for the FLNet Client to pick up the new certificates:
docker exec flnet_client-reverse-proxy-encrypted-1 nginx -s reload

After generating the certificates you can initialize and start the FLNet Client. 2. You can also setup an entry in your domain that lets encrypt can use to verify your domain. This would be using the DNS-01 challenge. For automating the certification renewal, you need to check the API of your domain provider. 3. Do NOT generate SSL certificates at all and just use an SSH tunnel for encryption. For this you need to modify how the computer accessing the FLNet Client node behaves! 4. Use your own CA Authority to sign the certificates. This completely depends on your own IT infrastructure, so we cannot provide additional help.

Using an SSH tunnel​

If you prefer not to set up SSL certificates, you can run the Client on localhost and securely access it through an SSH tunnel. This approach encrypts the connection between your local machine and the server while keeping the Client bound to localhost only.

Steps to set up SSH tunneling:

  1. Deploy the Client to listen on 127.0.0.1 (localhost) during the initialization step. You don't need any SSL certificates as the SSH tunnel we use here already encrypts traffic.
  2. From your local machine accessing the FLNet Client, establish an SSH tunnel to your server:
# Replace 4444 with the port you configured during Client setup
# Replace user@your-server with your actual SSH credentials
ssh -L 4444:localhost:4444 user@your-server

This can also be setup in e.g. Putty. 3. While the SSH connection is active, open your browser and navigate to http://localhost:4444/

The Client will now be accessible on your local machine as if it were running locally, with all traffic securely encrypted through the SSH tunnel.

Advanced: Using your own reverse proxy​

A reverse proxy handles all the traffic send to the FLNet Client, proxying it. Furthermore, the proxy is used for the encryption of this traffic.

The FLNet Client uses it's own NGINX reverse proxy. If you want to use your own reverse proxy, it simply needs to relay traffic to your chosen IP:Port where you want to run the FLNet Client. Please note that we use Server Sent Events (SSE), usually requiring special proxy configuration.

An example configuration for apache would be (Make sure to input your actual domain!):

<IfModule mod_ssl.c>
<VirtualHost *:443>
    ServerName <your-domain>

    # Relay the traffic to where you deploy the client
    ProxyPass / http://127.0.0.1:8250/
    ProxyPassReverse / http://127.0.0.1:8250/

    # SSE Support
    SetEnv proxy-sendchunked 1

You then need to generate SSL certificates. If your server is accessible from the internet You can easily use certbots default certificate generation (Make sure to input your actual domain). Use sudo certbot --apache -d <yourdomain.com> for apache or sudo certbot --nginx -d <yourdomain.com> for nginx.

This will also automatically update the SSL certificates!

If your server is not accessible from the internet, e.g. it is behind a VPN or demilitarized zone Refer to the section on generating SSL certificates. While this is written for the FLNet Client NGINX reverse proxy, this is fundamentally the same with your own reverse proxy.