Configuring and deploying the Relay Proxy

This topic explains how to configure and deploy the Relay Proxy.

Configuring the Relay Proxy

After you have downloaded or built the Relay Proxy, you need to set its configuration options. You can set these options by either:

using a configuration file, or
using environment variables.

If you are using Relay Proxy Enterprise, you can also use automatic configuration. To learn more, read Automatic configuration.

Request metrics only appear after an SDK connectsSome of the Relay Proxy configuration options enable you to export metrics, including the number of connections and requests. Request and connection metrics have no data until an SDK sends a request to the Relay Proxy. In version 9.0 and later, status metrics are exported whenever metric export is on. To learn more, read the Relay Proxy GitHub repository’s Metrics.

Expand each section below to learn how to configure the Relay Proxy.

Expand Using a configuration file

Using a configuration file

It’s common to use a configuration file when you deploy the Relay Proxy from a release binary or build it from source.You can also use a configuration file when you run the Relay Proxy from a Docker container, but it is less convenient to do because you must place the configuration file at /ldr/ld-relay.conf.To learn more about the supported configuration options, read the Relay Proxy GitHub repository’s Configuration docs. To learn about Relay Proxy logging level options, read Logging.To use a configuration file:

Create a new file:

    # A single environment which only proxies server-side SDKs
    [environment "Production"]
        sdkKey = "YOUR_SDK_KEY"

    # An environment which proxies SDKs with SDK keys or client-side IDs
    [environment "Production"]
        sdkKey = "YOUR_SDK_KEY"
        envId = "example-client-side-id"

    # An environment which proxies SDKs with SDK keys or mobile keys
    [environment "Mobile Production"]
        sdkKey = "YOUR_SDK_KEY"
        mobileKey = "example-mobile-key"

Run the Relay Proxy binary while passing an argument to identify your configuration file’s location. The following example assumes that the configuration file is in your current directory and named ld-relay.conf, and that the ld-relay binary is in $GOPATH/bin. Run the following code:
$GOPATH/bin/ld-relay --config ./ld-relay.conf

If you’re using Relay Proxy Enterprise and want to enable automatic configuration or use it in offline mode, read Enable automatic configuration or Enable offline mode.

Expand Using environment variables

Using environment variables

The other way to configure your Relay Proxy is with environment variables. This method is available regardless of how you deploy the Relay Proxy, although it is most commonly used with Docker containers.To learn more about supported environment variables, read the Relay Proxy GitHub repository’s Configuration file format and environment variables. To learn about Relay Proxy logging level options, read Logging.To use environment variables:

Confirm that all of your Relay Proxy configuration values are specified with the appropriate environment variables. For example, to specify the SDK key for an environment named MyEnvName:
export LD_ENV_MyEnvName=<YOUR_SDK_KEY>
Run the Relay Proxy binary while passing the --from-env argument. The following command assumes that the ld-relay binary is in $GOPATH/bin.
$GOPATH/bin/ld-relay --from-env

If you’re using Relay Proxy Enterprise and want to enable automatic configuration or use it in offline mode, read Enable automatic configuration or Enable offline mode.

Deploying the Relay Proxy

You can deploy the Relay Proxy in one of four ways. In order from most common to least common, the methods are:

starting the Relay Proxy from a Docker image,
using Helm to run the Relay Proxy in Kubernetes,
downloading a Relay Proxy standalone release binary, or
building within an existing Go app.

Expand the sections below to learn how to use each method. For in-depth guidance on deployment strategies, including Relay Proxy service layers and node-level relays, read Relay Proxy deployment strategies.

Expand Starting the Relay Proxy from a Docker image

Starting the Relay Proxy from a Docker image

The Relay Proxy’s Docker images are based on Google’s Debian 13 “Distroless” images. Distroless images contain the Relay Proxy and its runtime dependencies, without a shell or package manager. The images run as the distroless nonroot user, ID 65532. Make sure that user can read any files you mount into the container, such as a configuration file or an offline mode archive.The images are available on Docker Hub for amd64, arm64, and armv7. A debug variant includes a BusyBox shell at /busybox/sh for troubleshooting. For more information, read Using with Docker.Relay Proxy 8.x also publishes Alpine images, and its distroless images are based on Debian 12. Version 9.0 and later publish only the Debian 13 distroless images. To learn more, read Relay Proxy 8.x to 9.0 migration guide.

Pin the Docker image to the most recent major versionWe strongly recommend pinning the Docker image to the most recent major version. In the examples below, the v9- pattern floats the minor and patch versions of the Relay Proxy. You may also pin to a specific version, such as launchdarkly/ld-relay:9.0.0-static-debian13-nonroot.We recommend against using the unpinned “latest” version from Docker in your production environments.

To deploy the Relay Proxy with Docker:

Use docker pull to pull the latest Relay Proxy Docker image:

  docker pull launchdarkly/ld-relay:v9-static-debian13-nonroot

  # This image contains a debug shell.
  docker pull launchdarkly/ld-relay:v9-static-debian13-debug-nonroot

The v9- pattern floats the minor and patch versions of the Relay Proxy. You may also pin to a specific version, such as launchdarkly/ld-relay:9.0.0-static-debian13-nonroot.

Use docker run to run the Relay Proxy from your Docker container while specifying your configuration details.

The simplest way to specify the configuration is with environment variables, using the -e option of docker run. An example configuration that uses environment variables appears below.For examples and a full list of allowable variables, read the Relay Proxy GitHub repository’s Using with Docker and SDK configuration.In the following example, the Relay Proxy has two LaunchDarkly environments.For the first environment, the SDK key is staging-YOUR_SDK_KEY, and the environment name, for the purposes of logging, is Staging. For the second environment, the SDK key is prod-sdk-key-456def, and the environment name is Production.In this example, the Relay Proxy is configured to listen on port 8030, which is its default port.The example configuration follows:

docker run --rm --name ld-relay              \
     -e LD_ENV_Staging="staging-YOUR_SDK_KEY" \
     -e LD_ENV_Production="prod-sdk-key-456def"       \
     -p 8030:8030                        \
     -e PORT=8030                        \
     launchdarkly/ld-relay:v9-static-debian13-nonroot

Expand Using Helm to run the Relay Proxy in Kubernetes

Using Helm to run the Relay Proxy in Kubernetes

We maintain a Helm chart to ease Kubernetes-based Relay Proxy deployments.To deploy the Relay Proxy using this Helm chart:

Add the LaunchDarkly Relay Proxy Helm chart repository.

helm repo add launchdarkly-ld-relay https://launchdarkly.github.io/ld-relay-helm

Use helm install to install the chart archive and deploy the proxy into your cluster. The fastest way to configure installation is through Helm’s --set flag. However, we recommend using files with the --values flag as this enables easier long term maintenance. In the examples below, replace MyEnvironment with the name of your Relay Proxy environment and sdk-key with your SDK key.

Here’s how:

helm install relay --set relay.environment.LD_ENV_example-environment-key=example-sdk-key launchdarkly-ld-relay/ld-relay

# values.yaml
relay:
    environment:
        LD_ENV_environment-key: example-sdk-key

# Run on the terminal
helm install relay --values ./values.yaml launchdarkly-ld-relay/ld-relay

You can find examples and full documentation on all configuration options in the GitHub repository.

Expand Downloading a Relay Proxy standalone release binary

Downloading a Relay Proxy standalone release binary

You can download one of the Relay Proxy’s most recent release binaries from our GitHub repository. This repository has all versions of the Relay Proxy releases with details about what each release improves or fixes. We recommend using the most recent release.To learn more about Relay Proxy release binaries, visit the GitHub repository.If you want to download a release binary from the GitHub repository, you should know the following things:

tar.gz files are executables. You can use these to run the Relay Proxy directly.
.deb and .rpm files are intended for use with a package manager.

When executing the binary, use either a configuration file or environment variables to set up your desired configuration.For an example of running the binary with Windows, read the Relay Proxy GitHub repository’s Building and running in Windows.

Expand Building within an existing Go app

Building within an existing Go app

To build the Relay Proxy from source:

Install Go 1.26 or higher. To install Go, read Go’s documentation.
Clone the default branch of the repository: https://github.com/launchdarkly/ld-relay
Run go build . in the directory where you cloned the code.

The executable binary ld-relay appears in the directory.There is also a shortcut command that can replace the longer procedure above. This command downloads the code and builds it in a single step. After you enter the command, the executable binary ld-relay appears in $GOPATH/bin. You can move it to any other location.

go install github.com/launchdarkly/ld-relay/v9@latest

When executing the binary, use either a configuration file or environment variables to set up your desired configuration.To learn more, read the Relay Proxy GitHub repository’s Building within an application.

​Configuring the Relay Proxy

​Using a configuration file

​Using environment variables

​Deploying the Relay Proxy

​Starting the Relay Proxy from a Docker image

​Using Helm to run the Relay Proxy in Kubernetes

​Downloading a Relay Proxy standalone release binary

​Building within an existing Go app

Configuring the Relay Proxy

Using a configuration file

Using environment variables

Deploying the Relay Proxy

Starting the Relay Proxy from a Docker image

Using Helm to run the Relay Proxy in Kubernetes

Downloading a Relay Proxy standalone release binary

Building within an existing Go app