25. Relay Configuration

Relay can be configured using a configuration file. As with Cog, most of Relay’s configuration entries can be controlled via environment variables. For each key in the configuration file, the corresponding environment variable is the upper-cased key, prepended with RELAY_. Thus, the key max_concurrent can be overridden using the environment variable RELAY_MAX_CONCURRENT, and so on.

Warning

The sole exception to this is the Relay “execution env” setting. If used, this must be set in the configuration file; there is no corresponding environment variable.

Note

An annotated example of a complete configuration file is kept in Relay’s GitHub repo here.

DOCKER_API_VERSION

Controls what version of the Docker API should be used when interacting with Docker.

Defaults to 1.23

RELAY_COG_ENABLE_SSL

Encrypts MQTT traffic between Relay and Cog.

Defaults to false.

RELAY_COG_HOST

The host name or IP address of the Cog server.

Defaults to 127.0.0.1. See also [COG_MQTT_HOST].

RELAY_COG_PORT

The MQTT listen port of the Cog server.

Defaults to 1883. See also [COG_MQTT_PORT].

RELAY_COG_REFRESH_INTERVAL

Controls how often Relay refreshes its list of installed bundles and Docker images.

Valid time units are s (seconds), m (minutes), and h (hours).

Defaults to 15m. Consider reducing this interval to 1m or less when frequently updating bundles.

RELAY_COG_SSL_CERT_PATH

Path to the Cog server’s SSL certificate.

Enables certificate verification if set.

RELAY_COG_TOKEN

Shared secret between Cog and a given Relay.

Corresponds to the TOKEN argument used when creating a Relay via cogctl.

Note

This is a required setting.

RELAY_DOCKER_CLEAN_INTERVAL

Controls how frequently Relay will remove unused Docker containers.

Uses the same time unit notation as [RELAY_COG_REFRESH_INTERVAL].

Defaults to 5m.

RELAY_DOCKER_CONTAINER_MEMORY

Controls how much memory (in megabytes) is allocated to each Docker container Relay uses to execute a command.

Docker requires a minimum of 4MB per container.

Defaults to 16.

RELAY_DOCKER_REGISTRY_HOST

Docker image registry host name.

Defaults to index.docker.io.

RELAY_DOCKER_REGISTRY_EMAIL
Email address credential used to access an authenticating Docker registry.
RELAY_DOCKER_REGISTRY_USER
Username credential used to access an authenticating Docker registry.
RELAY_DOCKER_REGISTRY_PASSWORD
Password credential used to access an authenticating Docker registry.

Note

RELAY_DOCKER_REGISTRY_EMAIL, RELAY_DOCKER_REGISTRY_USER, and RELAY_DOCKER_REGISTRY_PASSWORD are required when using Relay with private Docker repositories or private registries.

RELAY_DOCKER_SOCKET_PATH

Location of Docker’s Unix socket. Must begin with either unix:// or tcp://.

Defaults to unix:///var/run/docker.sock.

RELAY_DOCKER_USE_ENV
Controls whether or not Relay uses environment variables to set up its Docker connection. If true, Relay will use the environment variables DOCKER_HOST, DOCKER_TLS_VERIFY, and DOCKER_CERT_PATH to connect.

Note

This is a required setting when using Relay with Docker running inside docker-machine.

RELAY_ENABLED_ENGINES

Comma separated list of command execution engines. Valid engine names are:

  • native: Runs commands distributed as native executables installed directly on the Relay host.

  • docker: Runs commands distributed as Docker container images

    Defaults to native,docker. At least one engine must be enabled.

RELAY_ID
UUID assigned to the Relay.

Note

This is a required setting.

RELAY_LOG_JSON

Controls if Relay logs in plain text or JSON.

Defaults to false.

RELAY_LOG_LEVEL

Controls logging verbosity.

Defaults to info.

RELAY_LOG_PATH

Controls where Relay sends its log output. Valid values are:

  • Any valid file path

  • stdout or console

  • stderr

    Defaults to console.

RELAY_MAX_CONCURRENT

Maximum number of concurrent command invocations.

Defaults to 16.

RELAY_MANAGED_DYNAMIC_CONFIG

Controls whether or not Relay pulls dynamic configuration for installed command bundles from Cog.

If set to true, Relay will retrieve dynamic configuration files from the Cog server, instead of relying on files placed on the Relay host itself. Configuration changes can be submitted to Cog via the API, and will be picked up by Relay when it checks in periodically. See [RELAY_MANAGED_DYNAMIC_CONFIG_INTERVAL].

Defaults to true.

RELAY_DYNAMIC_CONFIG_ROOT
File path used to store dynamic bundle configuration files. A missing or empty value disables this feature. Nonexistent paths will be created on first use.
RELAY_MANAGED_DYNAMIC_CONFIG_INTERVAL

Controls how often Relay polls Cog for dynamic configuration updates.

Uses the same time units as [RELAY_COG_REFRESH_INTERVAL].

Defaults to 5s.

Note

This setting only takes effect when managed dynamic configuration is enabled.