Skip to main content

How to run the Unleash Proxy

Placeholders

Placeholders in the code samples below are delimited by angle brackets (i.e. <placeholder-name>). You will need to replace them with the values that are correct in your situation for the code samples to run properly.

The Unleash Proxy provides a way for you to consume feature toggles in front-end clients, such as the JavaScript Proxy client and React Proxy client.

Depending on your setup, the Proxy is most easily run in one of two ways, depending on your situation:

If you're using a hosted version of Unleash, we can also run the proxy for you.

Prerequisites​

This is what you need before you can run the proxy:

  • A running Unleash server to connect to. You'll need its API path (e.g. https://app.unleash-hosted.com/demo/api) to connect the proxy to it.
  • A client API token for the proxy to use.
  • If you're running the Proxy via Docker: the docker command line tool.
  • If you're running the Proxy as a Node.js app: Node.js and its command line tools.
  • A Proxy client key. This can be any arbitrary string (for instance: proxy-client-key). Use this key when connecting a client SDK to the Proxy.

How to run the Proxy via Docker​

We provide a Docker image (available on on Docker Hub) that you can use to run the proxy.

1. Pull the Proxy image​

Use the docker command to pull the Proxy image:

Pull the Unleash Proxy docker image
docker pull unleashorg/unleash-proxy

2. Start the Proxy​

When running the Proxy, you'll need to provide it with at least the configuration options listed below. Check the reference docs for the full list of configuration options.

Run the Unleash Proxy via Docker
docker run \
    -e UNLEASH_PROXY_CLIENT_KEYS=<proxy-client-key> \
    -e UNLEASH_URL='<unleash-api-url>' \
    -e UNLEASH_API_TOKEN=<client-api-token> \
    -p 3000:3000 \
    unleashorg/unleash-proxy

If the proxy starts up successfully, you should see the following output:

Unleash-proxy is listening on port 3000!

How to run the Proxy as a Node.js app​

To run the Proxy via Node.js, you'll have to create your own Node.js project and use the Unleash Proxy as a dependency.

1. initialize the project​

If you don't already have an existing Node.js project, create one:

npm init

2. Install the Unleash Proxy package​

Install the Unleash Proxy as a dependency:

npm install @unleash/proxy

3. Configure and start the proxy​

Import the createApp function from @unleash/proxy and configure the proxy. You'll need to provide at least the configuration options highlighted below. Check the reference docs for the full list of configuration options.

Here is an example of what running the Proxy as a Node.js app might look like:

Sample app running the Unleash Proxy
const port = 3000;

const { createApp } = require('@unleash/proxy');

const app = createApp({
    unleashUrl: '<unleash-api-url>',
    unleashApiToken: '<client-api-token>',
    clientKeys: ['<proxy-client-key>'],
    proxyPort: 3000,
});

app.listen(port, () =>
    console.log(`Unleash Proxy listening on http://localhost:${port}/proxy`),
);

Verify that the proxy is working​

When the proxy process has started up correctly, you can start querying its /proxy endpoint. If it's running correctly, you'll get back a JSON object with a list of toggles. The list may be empty if you haven't added any toggles for the corresponding project/environment yet.

Request toggles from the Unleash Proxy
GET <proxy-url>/proxy
Authorization: <proxy-client-key>
content-type: application/json