Configuration

Relay can be configured using environment variables, or any approach supported by ASP.NET Core

Your desired approach may differ depending on the environment you’re configuring, e.g.:

If you’re running Relay as part of a composed stack of containers, we recommend setting environment variables in the compose.yml.

For example:

compose.yml

services:
  # ...
 
  relay:
    # ...
 
    environment:
      ConnectionStrings__Default: Server=db_host;Port=5432;Database=hutch-relay;User Id=postgres;Password=postgres
      RelayTaskQueue__ConnectionString: amqp://user:password@rabbitmq:5672
 
      UpstreamTaskApi__BaseUrl: https://my-task-api.com
      UpstreamTaskApi__CollectionId: dd52026b-5a61-4c89-b733-04ba141b3f31
      UpstreamTaskApi__Username: user
      UpstreamTaskApi__Password: password
 
    # ...

Upstream Task API

Configuration Section: UptreamTaskApi

Key	Description
`BaseUrl`*	The Base URL for an Upstream Task API that Relay should fetch jobs from. This only needs to include scheme (e.g. `https://`), host (`my-task-api.com`) and optionally port `8080`
`CollectionId`*	An ID (provided from the Upstream API) for this Task API consumer
`Username`*	A valid username for accessing the Task API
`Password`*	A valid password for the Task API user configured above
`PollingFrequency`	Interval in milliseconds between polling requests to the Upstream Task API. Defaults to `5000` (5 seconds).
`Enable`	Whether to enable UpstreamTaskApi functionality: `true\|false` When set to false, the following occur: All other UpstreamTaskApi configuration is not required The background polling service which polls the Upstream Task API for jobs will not start. When Relay receives results from downstream clients, it will not submit them to an Upstream Task API. Defaults to `true`.
`ResumeOnError`	Whether to resume polling after a non-critical error occurs, swallowing (but logging) the exception. Container orchestrated (k8s, compose) or systemd service environments should prefer to always terminate, and control restarting the application themselves. Defaults to `false`.
`ErrorDelay`	The delay in seconds to wait before resuming polling after an error occurs. Defaults to `5`.
`QueueTypes`	Specify which Job Type queues Relay should poll against in the Upstream Task API. Can be an empty string, a ``, or a list of comma separated Task API Job Type codes. An empty string will cause Relay to poll single “unified” queue for jobs of any type, e.g. when connecting to Upstream Relays. A comma separated list will cause Relay to poll separate queues for each supported type listed, in parallel, e.g. when connecting to upstream RQUEST. Defaults to `` polling all supported types from separate queues (standard RQUEST behaviour)

Examples:

.env

UpstreamTaskApi__BaseUrl="https://my-task-api.com"
UpstreamTaskApi__CollectionId="dd52026b-5a61-4c89-b733-04ba141b3f31"
UpstreamTaskApi__Username=user
UpstreamTaskApi__Password=password
UpstreamTaskApi__PollingFrequency=5000

compose.yml

environment:
  UpstreamTaskApi__BaseUrl: https://my-task-api.com
  UpstreamTaskApi__CollectionId: dd52026b-5a61-4c89-b733-04ba141b3f31
  UpstreamTaskApi__Username: user
  UpstreamTaskApi__Password: password
  UpstreamTaskApi__PollingFrequency: 5000

secrets.json

{
  "UpstreamTaskApi": {
    "BaseUrl": "https://my-task-api.com",
    "CollectionId": "dd52026b-5a61-4c89-b733-04ba141b3f31",
    "Username": "user",
    "Password": "password"
    "PollingFrequency": 5000
  }
}

GA4GH Beacon

Configuration Section: Beacon

Key Description

Key	Description
`Enable`	Whether to enable Beacon functionality: `true\|false` Defaults to `false`
`RequestFilteringTermsOnStartup`	Whether to request filtering terms from subnodes when Relay starts. `Never`: do not queue Generic Code Distribution tasks at Startup `IfEmpty`: if there are no cached terms at startup, then queue Generic Code Distribution tasks if there aren’t any already in progress. `ForceIfEmpty`: if there are no cached terms at startup, then queue Generic Code Distribution tasks EVEN IF there ARE some already in progress. `Always`: Regardless of the state of the cache, queue Generic Code Distribution tasks if there aren’t any already in progress. `ForceAlways`: Regardless of the state of the cache, queue Generic Code Distribution tasks EVEN IF there ARE some already in progress. Default `Never`.

Enable

Whether to enable Beacon functionality: true|false

Defaults to false

RequestFilteringTermsOnStartup

Whether to request filtering terms from subnodes when Relay starts.

Never: do not queue Generic Code Distribution tasks at Startup
IfEmpty: if there are no cached terms at startup, then queue Generic Code Distribution tasks if there aren’t any already in progress.
ForceIfEmpty: if there are no cached terms at startup, then queue Generic Code Distribution tasks EVEN IF there ARE some already in progress.
Always: Regardless of the state of the cache, queue Generic Code Distribution tasks if there aren’t any already in progress.
ForceAlways: Regardless of the state of the cache, queue Generic Code Distribution tasks EVEN IF there ARE some already in progress.

Default Never.

Configuration Section: Beacon.SecurityAttributes

Key Description

Key	Description
`DefaultGranularity`	Default Granularity for Relay’s Beacon functionality. `boolean` `count` Defaults to `boolean`
`SecurityLevels`	Security Level for Relay’s Beacon functionality. Only `PUBLIC` is currently supported by Relay. Defaults to `PUBLIC`

DefaultGranularity

Default Granularity for Relay’s Beacon functionality.

boolean
count

Defaults to boolean

SecurityLevels

Security Level for Relay’s Beacon functionality.

Only PUBLIC is currently supported by Relay.

Defaults to PUBLIC

Configuration Section: Beacon.MaturityAttributes

Key Description

Key	Description
`ProductionStatus`	Production Status for Relay’s Beacon functionality. `DEV` `TEST` `PROD` Defaults to `DEV`

ProductionStatus

Production Status for Relay’s Beacon functionality.

DEV
TEST
PROD

Defaults to DEV

Configuration Section: Beacon.Info

Key	Description
`Id`	A unique identifier for this Beacon installation. Values should typically be in reverse domain notation e.g. `org.my-organization.beacon` Default is empty.
`Name`	A friendly name for this Beacon installation. Defaults to `Hutch Relay Beacon`
`Description`	Description of this Beacon installation. Defaults to `A federated discovery service for aggregate individuals summaries across multiple downstream data sources`
`BeaconOrganization`	Details of the organisation responsible for this Beacon installation.
`WelcomeUrl`	Link to a web page for this Beacon installation.
`AlternativeUrl`	Another URL where this Beacon may be accessed; possibly with other restrictions in place.
`CreatedDate`	The ISO-8601 date/time this Beacon installation was made available. Defaults to when Beacon functionality was made available in Relay.
`UpdatedDate`	The ISO-8601 date/time this Beacon installation was last updated. Defaults to the Build timestamp of the running release of Relay.

Examples:

.env

Beacon__Enable=true
Beacon__RequestFilteringTermsOnStartup="IfEmpty"
Beacon__SecurityAttributes__DefaultGranularity="count"
Beacon__MaturityAttributes__ProductionStatus="PROD"
Beacon__Info__Id="org.my-organization.beacon"

compose.yml

environment:
  Beacon__Enable: true
  Beacon__RequestFilteringTermsOnStartup: "IfEmpty"
  Beacon__SecurityAttributes__DefaultGranularity: "count"
  Beacon__MaturityAttributes__ProductionStatus: "PROD"
  Beacon__Info__Id: "org.my-organization.beacon"

secrets.json

{
  "Beacon": {
    "Enable": "true",
    "RequestFilteringTermsOnStartup": "IfEmpty",
    "SecurityAttributes": {
      "DefaultGranularity": "count"
    },
    "MaturityAttributes": {
      "ProductionStatus": "PROD"
    },
    "Info": {
      "Id": "org.my-organization.beacon"
    }
  }
}

Database Connections

Configuration Section: ConnectionStrings

Key	Description
`Default`*	An ODBC/ADO.NET style connection string for a PostgreSQL 16 Server, and a database name for Relay to store working state in.

Configuration Section: Database

Key Description

Key	Description
`ApplyMigrationsOnStartup`	Should Relay automatically apply outstanding database migrations at startup? `true` / `false`. Defaults to `false`.

ApplyMigrationsOnStartup

Should Relay automatically apply outstanding database migrations at startup? true / false.

Defaults to false.

Examples:

.env

ConnectionStrings__Default="Server=localhost;Port=5432;Database=hutch-relay;User Id=postgres;Password=postgres"
Database__ApplyMigrationsOnStartup=true

compose.yml

environment:
  ConnectionStrings__Default: "Server=localhost;Port=5432;Database=hutch-relay;User Id=postgres;Password=postgres"
  Database__ApplyMigrationsOnStartup: true

secrets.json

{
  "ConnectionStrings": {
    "Default": "Server=localhost;Port=5432;Database=hutch-relay;User Id=postgres;Password=postgres"
  },
  "Database": {
    "ApplyMigrationsOnStartup": true
  }
}

Any Relay CLI command that connects to the database can have its connection string specified with the --connection-string option

--connection-string "Server=localhost;Port=5432;Database=hutch-relay;User Id=postgres;Password=postgres"

RelayTask Queue

Configuration Section: RelayTaskQueue

Key	Description
`ConnectionString`*	A connection URL for an AMQP Server

Examples:

.env

RelayTaskQueue__ConnectionString="amqp://user:password@localhost:5672"

compose.yml

environment:
  RelayTaskQueue__ConnectionString: "amqp://user:password@localhost:5672"

secrets.json

{
  "RelayTaskQueue": {
    "ConnectionString": "amqp://user:password@localhost:5672"
  },
}

Declarative State Configuration

Relay requires some local state to operate. This state can be managed imperatively via the CLI, or configured declaratively.

Declarative configuration means you can specify in a configuration file or Environment Variables the state you would like to exist when Relay runs, and Relay will ensure that desired declared state at startup before doing anything else.

This is good for Container Orchestration environments in particular, which favour a “desired state” model. Values could be provided via secret management mechanisms where appropriate.

💡

Remember that declarative config is “desired state”, NOT just data seeding; if you remove users or subnodes from config later, Relay will reconcile the local datastore with the config, removing unspecified items if they were previously declared!

Mixing declarative and imperative (CLI) config

The recommendation generally is to not mix approaches, however it is possible if necessary.

Declarative Config is compatible with imperatively configured state (i.e. added by CLI) and will not interfere with state added manually; it only enacts the desired state resolution on “declared” state.

When Relay resolves Declarative Config, it will only amend state that is marked as coming from a declarative source.
- i.e. it will ignore imperatively added state
If you imperatively or manually modify declared state, it will be “corrected” the next time declared state is resolved.

Downstream Users and Subnodes

At minimum Relay requires at least one user and an associated subnode, to represent a downstream client and the credentials they use to interact with Relay.

💡

Users and Subnodes can alternatively be configured via the users cli, particularly users add.

Configuration Section: DownstreamUsers.<username>

💡

Note that for these configuration options, DownstreamUsers is a dictionary, and the keys are the desired username of each user.

Key	Description
`Password`*	The desired password for this user
`Subnode`	The ID to use when creating a subnode for this user (i.e. Collection ID). This must be a valid UUID format string.
`Subnodes`	An array of IDs to use when creating multiple subnodes for this user (i.e. Collection IDs). These must be a valid UUID format string.

Examples:

.env

# user with single subnode
DownstreamUsers__user1__Password=abc123
DownstreamUsers__user1__Subnode=93258ae6-472f-45d2-8cf9-8b64cbeb03c8
 
# user with multiple subnodes
DownstreamUsers__user2__Password=def456
DownstreamUsers__user2__Subnodes__0=b8c58ab0-51c7-4842-ac96-efffc2c02472
DownstreamUsers__user2__Subnodes__1=50401056-8d4a-44c7-a257-f57ab2dcfb01

compose.yml

environment:
  # user with single subnode
  DownstreamUsers__user1__Password: abc123
  DownstreamUsers__user1__Subnode: "93258ae6-472f-45d2-8cf9-8b64cbeb03c8"
 
  # user with multiple subnodes
  DownstreamUsers__user2__Password: def456
  DownstreamUsers__user2__Subnodes__0: "b8c58ab0-51c7-4842-ac96-efffc2c02472"
  DownstreamUsers__user2__Subnodes__1: "50401056-8d4a-44c7-a257-f57ab2dcfb01"

secrets.json

{
  "DownstreamUsers": {
    "user1": {
      "Password": "abc123",
      "Subnode": "93258ae6-472f-45d2-8cf9-8b64cbeb03c8"
    },
    "user2": {
      "Password": "def456",
      "Subnodes": [
        "b8c58ab0-51c7-4842-ac96-efffc2c02472",
        "50401056-8d4a-44c7-a257-f57ab2dcfb01"
      ]
    }
  }
}

Results Obfuscation

Configuration Section: Obfuscation

Key Description

Key	Description
`LowNumberSuppressionThreshold`	A positive number will set the threshold below which Relay will suppress and return `0`. Set to `0` to disable suppression. Defaults to `10`, so turning it off is an explicit action.
`RoundingTarget`	The target nearest number to round to. e.g. `10` will round `170` - `174` down to `170` `175` - `179` up to `180` Set to `0` to disable rounding. Defaults to `10`, so turning it off is an explicit action.

LowNumberSuppressionThreshold

A positive number will set the threshold below which Relay will suppress and return 0.

Set to 0 to disable suppression.

Defaults to 10, so turning it off is an explicit action.

RoundingTarget

The target nearest number to round to.

e.g. 10 will round

170 - 174 down to 170
175 - 179 up to 180

Set to 0 to disable rounding.

Defaults to 10, so turning it off is an explicit action.

Examples:

.env

Obfuscation__LowNumberSuppressionThreshold=50
Obfuscation__RoundingTarget=5

compose.yml

environment:
  Obfuscation__LowNumberSuppressionThreshold: 50
  Obfuscation__RoundingTarget: 5

secrets.json

{
  "Obfuscation": {
    "LowNumberSuppressionThreshold": 50,
    "RoundingTarget": 5
  }
}

Monitoring

Configuration Section: Monitoring

Key Description

Key	Description
`HealthEndpoint`	The route to use for the health check endpoint. Defaults to `/healthz`.

HealthEndpoint

The route to use for the health check endpoint.

Defaults to /healthz.

Examples:

.env

Monitoring__HealthEndpoint="/health"

compose.yml

environment:
  Monitoring__HealthEndpoint: "/health"

secrets.json

{
  "Monitoring": {
    "HealthEndpoint": "/health",
  }
}

Logging

Configuration Section: Serilog

Logging is implemented through Serilog.

Examples:

.env

Serilog__MinimumLevel__Default="Information"

compose.yml

environment:
  Serilog__MinimumLevel__Default: "Information"

secrets.json

{
  "Serilog": {
    "MinimumLevel": {
      "Default": "Information",
      "Override": {
        "Microsoft": "Warning",
        "Microsoft.AspNetCore.Hosting.Diagnostics": "Error",
        "Microsoft.Hosting.Lifetime": "Information"
      }
}
},
}

ASP.NET Core

Since Relay is an ASP.NET Core application, there are some capabilities of that framework that can be configured in the standard way.

Examples of this include hosting configuration (e.g. bind addresses, TLS…).

Please refer to the ASP.NET Core documentation on these topics.

Quickstart Deployment