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), andh
(hours).Defaults to
15m
. Consider reducing this interval to1m
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 viacogctl
.
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://
ortcp://
.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 variablesDOCKER_HOST
,DOCKER_TLS_VERIFY
, andDOCKER_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 imagesDefaults 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
orconsole
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.