Offline mode

Read time: 5 minutes

Last edited: Dec 28, 2023

Relay Proxy offline mode is an Enterprise feature

Relay Proxy offline mode is available to customers on an Enterprise plan. To learn more, read about our pricing. To upgrade your plan, contact Sales.

Overview

This topic explains how to enable offline mode for the Relay Proxy.

The Relay Proxy can run in two modes:

Online mode is the default mode for the Relay Proxy. When you run the Relay Proxy in online mode, you can configure your SDKs for either proxy mode or daemon mode.
Offline mode prevents the Relay Proxy from connecting directly to LaunchDarkly. When you run the Relay Proxy in offline mode, you must configure your SDKs for proxy mode.

Benefits of offline mode

For most customers, we do not recommend running the Relay Proxy in offline mode. Running the Relay Proxy in offline mode means that any time you make changes to your flag rules, you must re-download the flag rule file, update it on the Relay Proxy's filesystem, and restart the Relay Proxy. In contrast, running the Relay Proxy in online mode handles these changes automatically.

However, there are benefits to using offline mode in certain circumstances. Enabling offline mode on the Relay Proxy lets you run the Relay Proxy without ever connecting it to LaunchDarkly. Instead of retrieving flag and segment values from LaunchDarkly's servers, the Relay Proxy gets them from files located on your local host or filesystem.

This allows you to run the Relay Proxy in a highly secure system, such as in your organization's air-gapped or FedRAMP-compliant system. By using offline mode, you can secure the Relay Proxy away from any external touchpoints. Alternatively, if your primary concern is FedRAMP-compliance, you can also use the LaunchDarkly federal instance. To learn more, read LaunchDarkly in federal environments.

Offline mode does not send events to LaunchDarkly

When the Relay Proxy is in offline mode, it does not send events to LaunchDarkly, and event-driven app features do not indicate new activity. For example, flag statuses and the flag evaluations graph do not update to reflect evaluations from an offline Relay Proxy. To learn more, read the Relay Proxy GitHub repository's Events in offline mode.

You should not use a persistent feature store between the Relay Proxy and your application in offline mode.

To run the Relay Proxy in offline mode, you must configure your SDKs to run in proxy mode. To learn how, read Configuring SDKs to use different modes.

Enabling offline mode

Enabling offline mode is a two-step process.

You must:

Create a Relay Proxy configuration from the Relay proxy tab of the Account settings page and save its unique key.
Configure your Relay Proxy instance to use the unique key from the prior step. You may do so either as a property in your Relay Proxy configuration file or as an environment variable.

Save the Relay Proxy's unique key

When you create a new Relay Proxy, LaunchDarkly assigns a unique key to it. You must save the key immediately after you create the Relay Proxy, because the key is only viewable on creation.

Here's how to create a Relay Proxy configuration in the LaunchDarkly user interface:

Navigate to the Account settings page and click into the Relay proxy tab.
Click Create configuration. The "Create a Relay Proxy configuration" panel appears.
Give the Relay Proxy a human-readable Name.
Choose a Rule from the menu. This rule determines what content the Relay Proxy receives.

"All projects and environments" sends changes about all projects and environments to the Relay Proxy.
"Inline policy" allows you to specify which projects and environments you can track events for. To learn more, read Writing an inline policy.

Click Save configuration. The Relay Proxy appears on the Relay proxy tab of the Account settings page with its key visible.
Copy and save the key somewhere secure:

The "Relay proxy" tab with a newly created Relay Proxy. The key is displayed.

Next, you must download all your flag rules and segments locally and tell the Relay Proxy where to find them. You do this by associating the file containing your flag rules with the Relay Proxy in a configuration file or with an environment variable.

To get your flag rules and make them accessible to the Relay Proxy:

curl /relay/latest-all. This generates a file containing all your flag rules.

An example curl is below:

curl https://sdk.launchdarkly.com/relay/latest-all \
  -H "Authorization: rel-EXAMPLE-RELAY-PROXY-CONFIGURATION-KEY" \
  -o EXAMPLE-NAME-OF-OUTPUTTED-FILE.tar.gz

Copy that file to your local host.
The next step varies depending on whether you're using a configuration file or environment variables:

If you're using a configuration file, configure it to read the file you saved in step 2. In the file, specify an OfflineMode section with the fileDataSource key and a value of the file's path.
If you're using environment variables, specify the file with the FILE_DATA_SOURCE environment variable.
```
[OfflineMode]
fileDataSource = "/path/to/file.tar.gz"
```

Start the Relay Proxy.

From now on, the Relay Proxy will serve flag values based on the contents of the file you downloaded, not by contacting LaunchDarkly for updates.

Updating flag rules in offline mode

After you configure the Relay Proxy to run in offline mode, you do not need to connect to a network to update flag rules. If your flag rules change, you can update the Relay Proxy by re-downloading the flag rules file and updating it on your filesystem.

To update the Relay Proxy in offline mode:

Make a request to https://sdk.launchdarkly.com/relay/latest-all to generate a file containing all your flag rules.
Replace the existing file on the Relay Proxy's filesystem with the newly-generated file. The Relay Proxy will detect that the file has changed and will reload it.

The Relay Proxy automatically updates when it detects changes to your flag rules.