Deploy a Submission Layer

This page contains:

a summary of what is involved when deploying a Five Safes TES Submission Layer
a Sample Deployment Guide
- with recommendations for deploying in Production

Component Summary

Here is a summary of the required components which make up the Submission Layer:

Component	Notes
KeyCloak	The Submission apps require a Keycloak realm containing users and clients authorised to access them
Minio	An Amazon S3 compatible Submission Storage service
RabbitMQ	A message broker for queueing submissions for target TREs
PostgreSQL	A database for the Submission apps to keep local state
Submission API	A REST API for Submission Layer functionality, including the GA4GH TES API
Submission GUI	A Web Frontend for users to log into and interact with the Submission Layer

You may choose how to distribute your own deployment of these components, as long as they are able to communicate with each other over the network.

For some components, such as KeyCloak or MinIO, you may wish to use your own existing deployments.

User accessible components

A subset of the components will need to be accessible by users, outside of the host environent:

Component	Reason
KeyCloak	So that users can authenticate and admins can manage the Submission KeyCloak Realm
Minio	So that Researchers and TREs can upload and download Submission data (inputs or outputs)
Submission GUI	So that users can log into and interact with the Submission Layer
Submission API	So that Researchers and TREs can interact with the Submission Layer via a REST API

Sample Deployment Guide

Note that this guide is a sample. It can be modified to reflect your own infrastructure and configuration choices.

This guide deploys all the components of the Submission Layer on a single host (e.g. a Virtual Machine) using Docker Compose.

All the components are deployed on suitable Docker networks and can communicate with each other as required.

It also automatically configures the KeyCloak realm, ready for following our other guides.

User accessible components

Components which may need to be accessed from outside the host are forwarded to the host on specific ports

Component	Ports
KeyCloak	HTTP: `8085`
MinIO	API HTTP: `9000`, GUI HTTP: `9001`
Submission GUI	HTTP: `7220`
Submission API	HTTP: `5034`

This sample also includes some additional components useful for diagnostic purposes:

Component	Notes	Ports
Seq	Logs aggregator and web-based viewer	HTTP: `5341`
Adminer	Web-based PostgreSQL client	HTTP: `8087`

Production Recommendations

To use this sample as a starting point for a production deployment, some general recommendations should be considered.

The ports specified above can be used for configuring a reverse proxy for access to the necessary components.

Get Started

Prerequisites

Docker and Docker Compose installed. For Linux/Ubuntu VMs, you can follow this guide
Git installed on your machine.

Deployment Steps

To deploy a Submission Layer:

Clone the repository

git clone https://github.com/SwanseaUniversityMedical/5S-TES-deployment.git

Go to the Submission Layer directory

Within the 5S-TES-deployment directory, the Submission Layer docker compose and configuration files are in the Submission directory:

cd Submission

Configure the .env file

Open the .env file in the Submission directory and configure the environment variables.

The descriptions of the environment variables and the guide to set them are as follows:

Environment Variable	Description
`dareVer`	The version of the Submission Layer app you are deploying. Find the version here, between `v` and `-containers`. For example, `2.15.1` is the version for the release `v2.15.1-containers`.
`DemoMode`	Set to true if you’d like to simulate execution, otherwise default to false.
`KeyCloakDemoMode`	Allows Keycloak to not require https. Default is true.
`PGLOGIN` and `PGPASSWORD`	The admin credentials for the PostgreSQL database used by the Submission Layer.
`sslcookies`	If this is set to `true`, the Submission Layer will use secure SSL cookies. Default is `false` to prevent issues with Keycloak.
`httpsRedirect`	Disable HTTPS redirect (setting this to `false`) if using http only site to prevent silent redirect to non existent https site
`KeycloakHostName`	The hostname of the Keycloak server. For example, `https://my-keycloak.net`
`MinioOpenidSecret`	The OpenID secret for the Minio client of Dare-Control realm. There is a default value in the realm configuration, but you should regenerate it for production deployments. Do this by navigating to `Dare-Control` realm -> `Clients` -> `Dare-Control-Minio` -> `Credentials`. Then click `Regenerate` and copy the new value into this environment variable.
`MinioIdentityID`	Name of Dare-Control’s Minio client, i.e., `Dare-Control-Minio`
`MinioIdentityConfigURL`	The OpenID configuration URL for the Dare-Control realm. For example, `https://my-keycloak.net/realms/Dare-Control/.well-known/openid-configuration` or `http://keycloak:8080/realms/Dare-Control/.well-known/openid-configuration` (if Keycloak is running on the same Docker network)
`MinioRootUser`	The root user for the Minio server
`MinioRootPass`	The root password for the Minio server
`MinioBrowserHost`	This is useful if you are using a reverse proxy to access the Minio server. Read more about this here
`MinioSubmissionUrl`	The URL for the Minio server, for internal access within Docker network. For example, `http://minio:9000`
`MinioSubmissionAdminConsoleUrl`	The URL for the Minio server’s admin console. For example, `http://minio:9001`
`SubmissionAPIKeyCloakBaseRealmAddress`	This is the realm address for the Submission’s Keycloak server. For example, `http://keycloak:8080/realms/Dare-Control` (if Keycloak is running on the same Docker network) or `https://my-keycloak.net/realms/Dare-Control`
`SubmissionAPIKeyCloakAuthority`	Same as `MinioIdentityConfigURL`
`SubmissionAPIKeyCloakMetadataAddress`	Same as `MinioIdentityConfigURL`
`SubmissionAPIKeyCloakSecret`	Same as `MinioOpenidSecret`, but this one is for `Dare-Control-API` client.
`SubmissionUIAccountManagementURL`	The URL for the Submission Layer’s Keycloak server’s account management. For example, `http://keycloak:8080/realms/Dare-Control/account` or `https://my-keycloak.net/realms/Dare-Control/account`
`SubmissionUIKeyCloakBaseUrl`	Same as `SubmissionAPIKeyCloakBaseRealmAddress`
`KeyCloakUseRedirect`	If this is set to `true`, the Submission Layer will use redirects for Keycloak authentication. Default is `false`.
`KeyCloakClientUIRedirectURL`	The URL for the Submission Layer’s Keycloak redirect URL. For example, `http://localhost:8888/`
`KeyCloakTokenExpiredAddressUI`	The URL for the Submission Layer’s Keycloak token expired address.
`SubmissionUIClientSecret`	Same as `MinioOpenidSecret`, but this one is for `Dare-Control-UI` client.
`SubmissionUIKeyCloakMetadataAddress`	Same as `MinioIdentityConfigURL`
`SubmissionUIKeyCloakAuthority`	Same as `SubmissionAPIKeyCloakBaseRealmAddress`
`SuppressAntiforgery`	If this is set to `true`, the Submission Layer will suppress antiforgery. Default is `false`.
`SubmissionSignedOutRedirectUri`	The URL for the Submission Layer’s Keycloak signed out redirect URI.
`SubmissionTokenRefreshSeconds`	The number of seconds to refresh the Submission Layer’s Keycloak token. Default is `3600`.
`SubmissionValidAudiences`	The valid audiences for the Submission Layer’s Keycloak token. Default is `Dare-Control-UI,Dare-Control-API,Dare-Control-Minio`.
`SubmissionServer`	The URL for the Submission Layer’s Keycloak server. For example, `keycloak:8080` or `my-keycloak.net`
`SubmissionServerProtocol`	The protocol for the Submission Layer’s Keycloak server. Default is `http`. If you are using HTTPS for Keycloak, set this to `https`.
`SubmissionRealm`	Realm name for the Submission Layer’s Keycloak server, i.e., `Dare-Control`
`SubmissionAutoTrustKeycloakCert`	If this is set to `true`, the Submission Layer will automatically trust the Keycloak certificate. Default is `false`.

You can find an example .env file here.

Run docker compose

docker compose up -d

Check-in

After the containers are running, if you have configured the ports for the Submission layer components for user accessibility, you can access the Submission Layer UI by navigating to http://<hostname>:7220 in your browser.

Requirements Project Setup