> For the complete documentation index, see [llms.txt](https://developer.harness.io/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://developer.harness.io/feature-flags/use-feature-flags/use-ff/relay-proxy/deploy-relay-proxy.md).

# Deploy the Relay Proxy

The Relay Proxy enables your apps to connect directly to Feature Flag services without having to make a significant number of outbound connections to FF services. The Relay Proxy establishes a connection to the Feature Flags configuration data and relays that connection to clients in an organization's network.

This topic describes how to deploy and start the Relay Proxy. For an overview, go to the [Relay Proxy Overview](/feature-flags/use-feature-flags/use-ff/relay-proxy/relay-proxy.md).

### Requirements <a href="#requirements" id="requirements"></a>

* API key:
  * When the proxy starts up, if an API key does not exist in Feature Flags, the proxy cannot validate that API key during authentication, because the proxy only retrieves API keys at startup and does not check for new ones.
  * If you start the proxy and then later create a new API key in Feature Flags, you must restart the proxy and pass the new API key in its configuration.
* Enable Rosetta 2 for M1 Macs running docker.
* You must set `DOCKER_DEFAULT_PLATFORM=linux/amd64`

in their environment.

### Configure the Relay Proxy <a href="#configure-the-relay-proxy" id="configure-the-relay-proxy"></a>

To configure the Relay Proxy:

1. Pull the latest [Harness Relay Proxy image](https://hub.docker.com/r/harness/ff-proxy) from Docker.

   `docker pull harness/ff-proxy`
2. View all the configuration variables.

   `docker run harness/ff-proxy`

<details>

<summary>Details of /app/ff-proxy Configuration variables:</summary>

```
account-identifier string
```

An account identifier to load remote config.

```
admin-service string
```

The URL of the ff admin service (default `https://harness.io/gateway/cf`).

```
admin-service-token string
```

Token to use with the ff service.

```
api-keys value
```

API keys to connect with ff-server for each environment.

```
 auth-secret string
```

The secret used for signing the authentication token generated by the proxy.

```
bypass-auth
```

Bypasses authentication.

```
client-service string
```

The URL of the ff client service (default `https://config.ff.harness.io/api/1.0`).

```
debug
```

Enables debug logging.

```
offline
```

Enables side loading of data from the config directory.

```
org-identifier string
```

An org identifier to load remote config.

```
port int
```

Port that the proxy service is exposed on (default 7000).

```
redis-address string
```

Redis host:port address.

```
redis-db int
```

Database to be selected after connecting to the server.

```
redis-password string
```

(Optional) Redis password.

```
sdk-base-url string
```

URL for the SDK to connect to (default `https://config.ff.harness.io/api/1.0`).

```
sdk-events-url string
```

URL for the SDK to send metrics to (default `https://events.ff.harness.io/api/1.0`).

```
generate-offline-config boolean
```

If set to `true`, the proxy produces an offline configuration in the mounted `/config` directory, then terminates.

```
config-dir string
```

Specifies a path for the offline config directory. The default is `/config`.

</details>

3. Specify your configuration details and Docker run the proxy image.

   The Relay Proxy obtains a list of all Environments and associated API keys for the given Account and Organization when it first starts up, which it will use to validate authentication requests and generate tokens.

   The following are the required configuration variables to connect to the Feature Flags service:

   * **admin-service-token**: Enter the Service Account details. An auth token that lets the proxy communicate with Feature Flags. For information on how to create a service account, go to [Manage service accounts](/harness-ai/use-harness-platform/platform-access-control/add-and-manage-service-account.md).
   * **account-identifier**: Enter your account identifier for which you want to retrieve the config. You can copy the account ID from the Harness Manager. In Harness Manager's address bar, copy the **Harness account ID** from your Harness URL. The Harness account ID comes after `account` in the URL. For example in the following URL, the account ID is `1a2b3c`: `https://app.harness.io/#/account/1a2b3c`.
   * **org-identifier**: Enter your organization identifier for which you want to retrieve the config. For more information, go to [Create a Harness Organization](/harness-ai/new-to-harness-platform/get-started.md).
   * **api-keys**: Enter your server SDK key. For more information, go to [Create an SDK key](/feature-flags/use-feature-flags/use-ff/ff-creating-flag/create-a-project.md#create-an-sdk-key).
   * **auth-secret**: Enter your authentication secret details. A secret that is used by the proxy to sign the [JWTs](https://jwt.io/) that it sends to the SDKs. For more information, go to [Add a Secrets Manager](/harness-ai/troubleshooting-and-resources/tutorials/add-secrets-manager.md).

   **Examples**

   * This is an example of a Docker Relay Proxy image with the required configuration details:

     ```
     docker run -d -p 7000:7000 harness/ff-proxy -admin-service-token $MY_SERVICE_TOKEN -account-identifier $MY_ACCOUNT_IDENTIFIER -org-identifier $MY_ORG_IDENTIFIER -api-keys $ENV_1_KEY,$ENV_2_KEY,$ENV_3_KEY... -auth-secret $ANY_AUTH_SECRET
     ```
   * This example uses a `.env` file. Create a `.env` file with the following environment variables:

     ```
     // Create a .env file with these envs   
     DEBUG=false   
     OFFLINE=false   
     PORT=7000   
     ACCOUNT_IDENTIFIER=<string>   
     ORG_IDENTIFIER=<string>   
     ADMIN_SERVICE_TOKEN=<string>   
     AUTH_SECRET=<string>   
     REDIS_ADDRESS=<host:port>   
     API_KEYS=6cfe5e7b-e264-4fa7-b163-befab9fd1223,9e4ec55f-3d11-4621-88c7-5ca0aa8b868b
     ```

     Then use the `.env` file with `docker run`.

     ```
     docker run -d -p 7000:7000 --env-file .env harness/ff-proxy
     ```

     For more information, go to [Configuration options](/feature-flags/use-feature-flags/use-ff/relay-proxy/configuration.md#configuration-options).
4. (Optional) You can provide config for a [Redis](/feature-flags/use-feature-flags/use-ff/relay-proxy/relay-proxy.md#redis-cache) instance used to store flag data using the `redis-address`, `redis-db` (optional), and `redis-password` (optional).

   For more information, go to [Configure Relay Proxy with Redis](#configure-relay-proxy-with-redis) below.

   <div data-gb-custom-block data-tag="hint" data-style="info" class="hint hint-info"><p><strong>NOTE</strong></p><p>If you do not use <a href="/pages/OJ004YvCLYF9HQ47kULn#redis-cache">Redis</a>, the flag data is stored in the memory. In-memory is the default option.</p></div>

### Configure Relay Proxy with Redis <a href="#configure-relay-proxy-with-redis" id="configure-relay-proxy-with-redis"></a>

You can run Redis locally and configure the proxy to work with it. Perform the following steps to configure proxy with Redis.

1. Start Redis.

   ```
    docker run --rm --name redis -d -p 6379:6379 redis:latest
   ```
2. Start the proxy and configure using a `.env`.

   ```
    docker run -d -p 7000:7000 --env-file .online.uat.env harness/ff-proxy:latest
   ```
3. Start the proxy and configure using flags.

   ```
   docker run -d -p 7000:7000 harness/ff-proxy -redis-address $REDIS_ADDRESS -admin-service-token $MY_SERVICE_TOKEN -account-identifier $MY_ACCOUNT_IDENTIFIER -org-identifier $MY_ORG_IDENTIFIER -api-keys $ENV_1_KEY,$ENV_2_KEY,$ENV_3_KEY... -auth-secret $ANY_AUTH_SECRET
   ```

### Configure SDKs to work With the Relay Proxy <a href="#configure-sdks-to-work-with-the-relay-proxy" id="configure-sdks-to-work-with-the-relay-proxy"></a>

The SDKs do not require any additional configuration to work with the proxy. The only difference is that instead of supplying the Feature Flags URL when starting up an SDK, you supply the proxy URL.

For example, if you wanted your SDK to work without the proxy, you'd give it the following URLs (if using the default URLs):

```
baseURL:   https://config.ff.harness.io/api/1.0
```

```
eventsURL: https://events.ff.harness.io/api/1.0
```

But if you have the proxy running locally on localhost:7000 and it’s connected to Harness, then pass the following URLs to the SDK:

```
baseURL:   http://localhost:7000
```

```
eventsURL: http://localhost:7000
```

#### SDK examples with Relay Proxy <a href="#sdk-examples-with-relay-proxy" id="sdk-examples-with-relay-proxy"></a>

The following examples show how to point an SDK at the Relay Proxy:

**Go SDK**

```
  
  
go  
proxyURL := "http://localhost:7000"  
apiKey := "your API Key"  
  
target := dto.NewTargetBuilder("your-target").  
    Name("your-target-name").  
    Build()  
  
client, err := harness.NewCfClient(apiKey,  
    harness.WithURL(proxyURL),  
    harness.WithEventsURL(proxyURL),  
    harness.WithTarget(target),  
)  
if err != nil {  
    log.Fatal(err)  
}
```

**.NET SDK**

```
String API_KEY = "YOUR_API_KEY";  
String proxyURL = "http://localhost:7000";  
  
config = Config.Builder()  
                .SetPollingInterval(60000)  
                .SetAnalyticsEnabled()  
                .SetStreamEnabled(true)  
                .EventUrl(proxyURL)  
                .ConfigUrl(proxyURL)  
                .Build();  
  
await CfClient.Instance.Initialize(API_KEY, config);  
  
/**  
 * Define you target on which you would like to evaluate   
 * the featureFlag  
 */  
                Target target =  
                io.harness.cfsdk.client.dto.Target.builder()  
                .Name("User1") //can change with your target name  
                .Identifier("user1@example.com") //can change with your target identifier  
                .build();
```

**JavaScript SDK**

```
javascript  
apiKey = "your API Key"  
proxyURL = "http://localhost:7000"  
  
var cf = initialize(apiKey,  
        {  
            baseUrl: proxyURL,  
            eventUrl: proxyURL,  
        }  
)
```

### Run the Relay Proxy in offline mode <a href="#run-the-relay-proxy-in-offline-mode" id="run-the-relay-proxy-in-offline-mode"></a>

You can configure the Relay Proxy to load and use configuration data that is stored offline. The following configuration data from your Project is stored in a configuration directory:

* Flags
* Targets
* Target Groups
* Hashed data of your SDK keys

This stored configuration is then loaded from this directory when you enable the `offline` Flag.

To use offline mode:

1. [Generate the offline configuration directory](#generate-the-offline-configuration-directory)
2. [Run the proxy in offline mode when needed](#run-the-proxy-in-offline-mode-when-needed)

#### Generate the offline configuration directory <a href="#generate-the-offline-configuration-directory" id="generate-the-offline-configuration-directory"></a>

You need to generate the configuration directory that contains your Project data before you can run the proxy in offline mode. To do this you run the proxy using your usual configuration, but also:

1. Include the variable for generating an offline configuration.
2. Mount your configuration directory to the docker container.

How you add these depends on whether you use Flags or a `.env` file:

**Docker command when using flags**

As well as your usual variables, include the `generate-offline-config` variable and add the directory path in place of `{YOUR_ABSOLUTE_PATH}`:

```
docker run -d -p 7000:7000 -v {YOUR_ABSOLUTE_PATH}/config:/config ff-proxy -generate-offline-config -admin-service-token $MY_SERVICE_TOKEN -account-identifier $MY_ACCOUNT_IDENTIFIER -org-identifier $MY_ORG_IDENTIFIER -api-keys $ENV_1_KEY,$ENV_2_KEY,$ENV_3_KEY... -auth-secret $ANY_AUTH_SECRET
```

**Docker command when using a .env file**

Add `GENERATE_OFFLINE_CONFIG=true` to your .env file, and add the directory path in place of `{YOUR_ABSOLUTE_PATH}`:

```
docker run -d -p 7000:7000 --env-file .env -v {YOUR_ABSOULUTE_PATH}/config:/config ff-proxy
```

This generates the configuration you need to run the proxy in offline mode, then terminates. To then use the offline configuration you store, you need to run the proxy in offline mode.

#### Run the proxy in offline mode when needed <a href="#run-the-proxy-in-offline-mode-when-needed" id="run-the-proxy-in-offline-mode-when-needed"></a>

After you have generated a configuration directory, you can load the data from it any time you need to run the proxy offline. To use the stored configuration when the proxy is offline you run the proxy using your usual configuration, but also:

1. Include the variable for running offline.
2. Mount your configuration directory to the docker container.

When you run the proxy in offline mode, it remains offline until you run the proxy in online mode again. This means that the proxy won't send metrics data or connect to the Harness servers.How you run the proxy in offline mode depends on whether you use flags or a .env file:

**Docker command when using flags**

Run the following Docker command and add the directory path in place of `{YOUR_ABSOLUTE_PATH}`as well as your usual variables:

```
docker run -d -p 7000:7000 -v {YOUR_ABSOULUTE_PATH}/config:/config ff-proxy -offline -admin-service-token $MY_SERVICE_TOKEN -account-identifier $MY_ACCOUNT_IDENTIFIER -org-identifier $MY_ORG_IDENTIFIER -api-keys $ENV_1_KEY,$ENV_2_KEY,$ENV_3_KEY... -auth-secret $ANY_AUTH_SECRET
```

**Docker command when using a .env file**

Add `OFFLINE=true` to your .env file and add the directory path in place of `{YOUR_ABSOLUTE_PATH}`:

```
docker run -d -p 7000:7000 --env-file .env -v {YOUR_ABSOULUTE_PATH}/config:/config ff-proxy

## More information <a href="#more-information" id="more-information"></a>

For more information
```