Relay Deployment

This page will guide you through getting Relay deployed in a Virtual Machine (VM).

🐇

We provide a container registry for ease of deployment.

Prerequisites

A VM with these apps installed
- Docker and Docker Compose
- wget
A PostgreSQL 16+ Database Server accessible from the VM

Deployment Steps

Get the sample Compose file

Download the sample Relay Compose file by running the command:

wget https://raw.githubusercontent.com/Health-Informatics-UoN/hutch/refs/heads/main/samples/Bunny/compose/relay.compose.yml

Environment configuration

Modify the configuration of the newly downloaded relay.compose.yml file as described in Configuring Relay

You will need to configure the database connection.

The sample enables Relay’s GA4GH Beacon interface by default; you may wish to configure it more richly, or disable it.

If you want to use Relay with an Upstream Task API Query Source, you’ll need to enable it and configure your Upstream Task API host connection.

Database Migrations

You can choose to run migrations for Relay’s Database either on demand (via the CLI, e.g. in a CI/CD process) or automatically (on startup of the Web App).

If you are working from source, you may wish to use the developer tooling.

By default the Sample Compose file runs migrations automatically.

You can opt into this behaviour with the ApplyMigrationsOnStartup flag in Relay’s Database Config.

You can run migrations on demand from the Relay CLI, using the database update command.

Here’s an example of running migrations, using the compose configuration:

docker compose run relay database update

💡

We’ve used docker run to ensure we run the same version of Relay for the CLI as is running in our Compose stack.

When working from source, you should use the Entity Framework Core tooling to run migrations (and otherwise manage them) as normal.

dotnet tool restore in the root of the Relay repository to restore the correct version of the tooling locally
dotnet ef database update (or any other dotnet-ef commands as desired)

User and Sub Node setup

Relay’s job is to relay tasks from an upstream Task Api to one or more downstream “Sub Nodes”.

Each Sub Node requires a set of credentials (in effect a user) to communicate with Relay, and Relay requires at minimum one user and subnode to be configured.

The sample Compose file declaratively preconfigures one user and subnode, but you can also perform this setup imperatively via the CLI.

Sub Node Bunny setup

For a Sub Node’s Bunny to talk to Relay, it will need to be configured with:

The base URL to your Relay instance (scheme, hostname and port)
The username and password created for the Bunny
The Sub Node ID (Collection ID) created for that user

The Sample Compose file specifies the following declarative user and subnode configuration:


Username	`username`
Password	`password`
Sub Node ID	`93258ae6-472f-45d2-8cf9-8b64cbeb03c8`

⚠️

Remember, Bunny will need network access to Relay (outbound from Bunny; inbound to Relay, on whatever ports Relay is configured to listen on).

Running Relay

At the directory containing the relay.compose.yml file, run the command to activate Relay:

docker compose up

You should then see a message in your console like this:

relay-1     | info: Microsoft.Hosting.Lifetime[14]
relay-1     |       Now listening on: http://[::]:8080
relay-1     | info: Microsoft.Hosting.Lifetime[0]
relay-1     |       Application started. Press Ctrl+C to shut down.
relay-1     | info: Microsoft.Hosting.Lifetime[0]
relay-1     |       Hosting environment: Production
relay-1     | info: Microsoft.Hosting.Lifetime[0]
relay-1     |       Content root path: /app

Submitting Queries

Sending an HTTP Request to a Beacon endpoint, such as Filtering Terms or Individuals will cause Relay to enqueue a task for each configured downstream SubNode. When results have been received from all SubNodes, Relay returns the aggregated results as the HTTP Response.

🎉

Congratulations on your first Relay deployment!

Configuration CLI