Configuring and deploying the Relay Proxy

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:

1. Create a new file:

   Basic example

   Multiple environments

   # A single environment which only proxies server-side SDKs
       [environment "Production"]
           sdkKey = "sdk-key-123abc"
   COPY

2. 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:

   Run the binary

   $GOPATH/bin/ld-relay --config ./ld-relay.conf
   COPY

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.

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:

1. 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:

   Example environment variable

   export LD_ENV_MyEnvName=<sdk-key-123abc>
   COPY

2. Run the Relay Proxy binary while passing the --from-env argument. The following command assumes that the ld-relay binary is in $GOPATH/bin.

   Run the binary

   $GOPATH/bin/ld-relay --from-env
   COPY

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.

Starting the Relay Proxy from a Docker image

The Relay Proxy's Docker image is available in two flavors: "Distroless", which is based on Debian, or Alpine.

We recommend "Distroless" because it contains fewer 3rd party dependencies which may require patching.

Both flavors are available on Docker Hub. For more information, read Using with Docker.

To deploy the Relay Proxy with Docker:

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

docker pull launchdarkly/ld-relay:v8-static-debian12-nonroot
COPY

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

2. 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 Configuration.

In the following example, the Relay Proxy is configured to have two LaunchDarkly environments.

For the first environment, the SDK key is staging-sdk-key-123abc, 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-sdk-key-123abc" \
    -e LD_ENV_Prod="prod-sdk-key-456def"       \
    -p 8030:8030                        \
    -e PORT=8030                        \
    launchdarkly/ld-relay:v8-static-debian12-nonroot
COPY

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:

1. Add the LaunchDarkly Relay Proxy Helm chart repository.

   Add chart repository

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

2. 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_environment-key-123abc=sdk-key123bc launchdarkly-ld-relay/ld-relay
COPY

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

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.

Building within an existing Go app

To build the Relay Proxy from source:

1. Install Go 1.21 or higher. To install Go, read Go's documentation.
2. Check out the source code from the default branch of the repository: https://github.com/launchdarkly/ld-relay
3. In the directory where you checked out the code, run go build .

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/v8@latest
COPY

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.