> ## Documentation Index
> Fetch the complete documentation index at: https://launchdarkly.com/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Configuring and deploying the Relay Proxy

<View title="Developer" />

<View title="Federal docs" />

<View title="EU docs" />

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](/docs/sdk/relay-proxy/automatic-configuration).

<Note>
  **Relay Proxy metrics only appear when an SDK is connected**

  Some of the Relay Proxy configuration options enable you to export metrics, including the number of connections and requests. The Relay Proxy only exports metrics when an SDK is connected to it. To learn more, read the Relay Proxy GitHub repository's [Metrics integrations](https://github.com/launchdarkly/ld-relay/blob/v8/docs/metrics.md).
</Note>

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

<AccordionGroup>
  <Accordion title="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](https://github.com/launchdarkly/ld-relay/blob/v8/docs/configuration.md). To learn about Relay Proxy logging level options, read [Logging](https://github.com/launchdarkly/ld-relay/blob/v8/docs/logging.md).

    To use a configuration file:

    1. Create a new file:

           <CodeGroup>
             ```text title="Basic example" lines wrap theme={null}
                 # A single environment which only proxies server-side SDKs
                 [environment "Production"]
                     sdkKey = "YOUR_SDK_KEY"
             ```

             ```text title="Multiple environments" lines wrap theme={null}
                 # 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"
             ```
           </CodeGroup>

    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:

           <CodeGroup>
             ```bash title="Run the binary" lines wrap theme={null}
             $GOPATH/bin/ld-relay --config ./ld-relay.conf
             ```
           </CodeGroup>

    If you're using Relay Proxy Enterprise and want to enable automatic configuration or use it in offline mode, read [Enable automatic configuration](/docs/sdk/relay-proxy/automatic-configuration#enable-automatic-configuration) or [Enable offline mode](/docs/sdk/relay-proxy/offline#enable-offline-mode).
  </Accordion>

  <Accordion title="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](https://github.com/launchdarkly/ld-relay/blob/v8/docs/configuration.md#configuration-file-format-and-environment-variables). To learn about Relay Proxy logging level options, read [Logging](https://github.com/launchdarkly/ld-relay/blob/v8/docs/logging.md).

    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`:

           <CodeGroup>
             ```bash title="Specify the SDK key for an environment" lines wrap theme={null}
             export LD_ENV_MyEnvName=<YOUR_SDK_KEY>
             ```
           </CodeGroup>

    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`.

           <CodeGroup>
             ```bash title="Run the binary" lines wrap theme={null}
             $GOPATH/bin/ld-relay --from-env
             ```
           </CodeGroup>

    If you're using Relay Proxy Enterprise and want to enable automatic configuration or use it in offline mode, read [Enable automatic configuration](/docs/sdk/relay-proxy/automatic-configuration#enable-automatic-configuration) or [Enable offline mode](/docs/sdk/relay-proxy/offline#enable-offline-mode).
  </Accordion>
</AccordionGroup>

## 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](/docs/sdk/relay-proxy/deployment-strategies).

<AccordionGroup>
  <Accordion title="Expand Starting the Relay Proxy from a Docker image">
    ### Starting the Relay Proxy from a Docker image

    The Relay Proxy's Docker image is available in two flavors: ["Distroless"](https://github.com/GoogleContainerTools/distroless),
    which is based on Debian, or [Alpine](https://alpinelinux.org/).

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

    Both flavors are available on [Docker Hub](https://hub.docker.com/r/launchdarkly/ld-relay). For more information, read [Using with Docker](https://github.com/launchdarkly/ld-relay/blob/v8/docs/docker.md).

    <Warning>
      **Pin the Docker image to the most recent major version**

      We strongly recommend pinning the Docker image to the most recent major version. In the examples below, 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`.

      We recommend against using the unpinned "latest" version from Docker in your production environments.
    </Warning>

    To deploy the Relay Proxy with Docker:

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

    <CodeGroup>
      ```bash title="Distroless image" lines wrap theme={null}
        docker pull launchdarkly/ld-relay:v8-static-debian12-nonroot
      ```

      ```bash title="Distroless image, debug variant" lines wrap theme={null}
        # This image contains a debug shell.
        docker pull launchdarkly/ld-relay:v8-static-debian12-debug-nonroot
      ```

      ```bash title="Alpine image" lines wrap theme={null}
        docker pull launchdarkly/ld-relay:v8-alpine
      ```
    </CodeGroup>

    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](https://github.com/launchdarkly/ld-relay/blob/v8/docs/docker.md) and [SDK configuration](https://github.com/launchdarkly/ld-relay/blob/v8/docs/configuration.md).

    In the following example, the Relay Proxy is configured to have 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:

    <CodeGroup>
      ```bash title="Run with a Docker container" lines wrap theme={null}
      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:v8-static-debian12-nonroot
      ```
    </CodeGroup>
  </Accordion>

  <Accordion title="Expand Using Helm to run the Relay Proxy in Kubernetes">
    ### Using Helm to run the Relay Proxy in Kubernetes

    We maintain a [Helm chart](https://github.com/launchdarkly/ld-relay-helm) 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.

           <CodeGroup>
             ```bash title="Add chart repository" lines wrap theme={null}
             helm repo add launchdarkly-ld-relay https://launchdarkly.github.io/ld-relay-helm
             ```
           </CodeGroup>

    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:

    <CodeGroup>
      ```bash title="Using command line flags" lines wrap theme={null}
      helm install relay --set relay.environment.LD_ENV_example-environment-key=example-sdk-key launchdarkly-ld-relay/ld-relay
      ```

      ```yaml title="Using values file" lines wrap theme={null}
      # 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
      ```
    </CodeGroup>

    You can find examples and full documentation on all configuration options in the [GitHub repository](https://github.com/launchdarkly/ld-relay-helm).
  </Accordion>

  <Accordion title="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](https://github.com/launchdarkly/ld-relay/releases).

    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](#using-a-configuration-file) or [environment variables](#using-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](https://github.com/launchdarkly/ld-relay/blob/v8/docs/windows.md).
  </Accordion>

  <Accordion title="Expand Building within an existing Go app">
    ### 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](https://golang.org/doc/install).
    2. Check out the source code from the default branch of the repository: [https://github.com/launchdarkly/ld-relay](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.

    <CodeGroup>
      ```bash title="Download and build the Relay Proxy" lines wrap theme={null}
      go install github.com/launchdarkly/ld-relay/v8@latest
      ```
    </CodeGroup>

    When executing the binary, use either a [configuration file](#using-a-configuration-file) or [environment variables](#using-environment-variables) to set up your desired configuration.

    To learn more, read the Relay Proxy GitHub repository's [Building within an application](https://github.com/launchdarkly/ld-relay/blob/v8/docs/in-app.md).
  </Accordion>
</AccordionGroup>