RelayDeployment

Relay Deployment

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

Prerequisites

Deployment Steps

Get the example 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/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, and your Upstream Task API host connection

Database Migrations

Currently the preferred way to run migrations is to have Relay do it automatically at startup.

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

Alternatively you can use the dotnet-ef tooling to run Migrations from Relay’s source.

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.

You can add a user using Relay’s CLI, and when you do, Relay will create an associated Sub Node, and generate a password.

The CLI will return the generated password and Sub Node Collection ID.

Here’s an example of adding a Relay User, when the database is running locally on the docker host machine:

docker run \
--network=host \
-e ConnectionStrings__Default="Server=localhost;Port=5432;Database=hutch-relay;User Id=postgres;Password=postgres" \
ghcr.io/health-informatics-uon/hutch/relay:dev-latest \
users add demo1
💡

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

Sub Node Bunny setup

For a Sub Node’s Bunny to talk to Relay, you (or someone else) will need to configure it with:

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

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

Relay establishes a connection to your upstream Task API server, then polls for a task. When it receives a task, it enqueues it for each configured downstream SubNode. When results have been received from all SubNodes, Relay passes the aggregated results back to the upstream Task API.

🎉
Congratulations on your first Relay deployment!