How to run the Unleash Proxy
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 flags 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:
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.
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
- Yarn
- pnpm
npm init
yarn init
pnpm init
2. Install the Unleash Proxy package
Install the Unleash Proxy as a dependency:
- npm
- Yarn
- pnpm
npm install @unleash/proxy
yarn add @unleash/proxy
pnpm add @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:
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 flags. The list may be empty if you haven't added any flags for the corresponding project/environment yet.
- HTTP
- cURL
- HTTPie
GET <proxy-url>/proxy
Authorization: <proxy-client-key>
content-type: application/json
curl -H "Content-Type: application/json" \
-H "Authorization: <proxy-client-key>" \
-X GET \
<proxy-url>/proxy
http GET \
<proxy-url>/proxy \
Authorization:<proxy-client-key> \