Skip to main content

GrowthBook Proxy

The GrowthBook Proxy server sits between your application and GrowthBook (both Cloud or Self-hosted instances). It turbocharges your GrowthBook implementation by providing speed, scalability, security, and real-time feature rollouts.

The GrowthBook Proxy does require spinning up infrastructure and all of the maintenance/devops costs associated with that. If you are looking for a simpler hands-off alternative, you can use a CDN instead.

Features​

  • Caching - Significantly faster feature lookups!
    • In-memory cache plus an optional distributed layer (Redis or MongoDB)
    • Automatic cache invalidation when features change in GrowthBook (using WebHooks)
  • Streaming - Updates your application in real-time as features are changed or toggled in GrowthBook (Javascript and React only)
  • Remote Evaluation - Hide your features' business logic in insecure environments
  • Security - Private-key authentication between GrowthBook and GrowthBook Proxy
  • Scalability - Support millions of concurrent users

Installation​

Using docker-compose​

If you are already using docker-compose to run GrowthBook, we have a pre-configured setup that includes a GrowthBook Proxy instance.

Just run

docker-compose -f docker-compose.proxy.yml up -d

This will start the proxy server on port 3300. Check http://localhost:3300/healthcheck to ensure it's working correctly.

Standalone​

You can also run the GrowthBook Proxy as a standalone Docker container.

First, pull the latest image

docker pull growthbook/proxy:latest

Then, run a GrowthBook Proxy instance on port 3300

docker run -d -p 3300:3300 \
  -e "GROWTHBOOK_API_HOST=https://growthbook-api.example.com" \
  -e "SECRET_API_KEY=something_secret" \
  --name gbproxy growthbook/proxy

Check http://localhost:3300/healthcheck to ensure it's running correctly.

Authentication​

You will need to create a "readonly" secret API key in GrowthBook by going to Settings → API Keys (you can also use a Personal Access Token if preferred). Or you can use a custom SECRET_API_KEY of your choosing. Whichever method you choose, this key will be used to authenticate your proxy server with the GrowthBook app.

Lastly, for self-hosted customers, add environment variables your main GrowthBook API server to enable the proxy:

PROXY_ENABLED=1
PROXY_HOST_PUBLIC=https://growthbook-proxy.example.com

# OPTIONAL: You can either create the secret key in the GrowthBook UI or define one here or
SECRET_API_KEY=something_secret

Note: Setting PROXY_HOST_PUBLIC is not strictly required, but is considered a best practice. Setting it enables faster rollouts by allowing GrowthBook to push updates to your proxy whenever feature definitions change.

Cloud Customers​

For cloud customers who self-host a proxy server, you must configure each SDK Connection to use the proxy server.

You may optionally enter your proxy server's public host URL. This enables faster rollouts by allowing GrowthBook to push updates to your proxy whenever your feature definitions change. If you do not provide a proxy host URL, your proxy server the proxy will fall back to a pull-based stale-while-revalidate caching strategy.

Go to SDK Configuration → SDK Connections in the GrowthBook app to configure the proxy server per each connection.

Using with the SDKs​

The GrowthBook Proxy has the same public feature endpoints as GrowthBook, so all you need to do is change the API host your SDK clients connect to:

// Before
const gb = new GrowthBook({
  apiHost: "https://growthbook-api.example.com",
  clientKey: "sdk-abc123"
});

// After (clientKey remains the same)
const gb = new GrowthBook({
  apiHost: "https://growthbook-proxy.example.com",
  clientKey: "sdk-abc123"
});

Configuration​

The GrowthBook Proxy supports a number of configuration options available via environment variables. Some of the more common options are:

  • GROWTHBOOK_API_HOST - Set this to the host and port of your GrowthBook API instance
  • SECRET_API_KEY - Create a secret API key in GrowthBook by going to Settings → API Keys
  • NODE_ENV - Set to "production" to hide debug and informational log messages
  • CACHE_ENGINE - One of - memory, redis, or mongo
  • CACHE_CONNECTION_URL - The URL of your redis or mongo cluster (if using)
  • CACHE_STALE_TTL - Number of seconds until a cache entry is considered stale
  • CACHE_EXPIRES_TTL - Number of seconds until a cache entry is expired

You can also configure the GrowthBook Proxy to handle SSL termination. It supports HTTP/2 by default, which is required for high performance streaming.

  • USE_HTTP2 - Set to "true" or "1" to enable
  • HTTPS_CERT - The SSL certificate
  • HTTPS_KEY - The SSL key

For more complete configuration documentation, please see the GrowthBook Proxy GitHub page: https://github.com/growthbook/growthbook-proxy

Best Practices​

In high-traffic production scenarios, there are a few best practices to follow

  • Auto-scale GrowthBook Proxy instances based on number of active connections or memory
  • Run the instances in the same region as your application servers for the lowest latency
  • Add a load balancer in-front that supports HTTP/2 and streaming responses (AWS ALB, HAProxy, etc.)
  • Use Redis (or MongoDB) as the cache engine for more consistent feature releases
  • Use the /healthcheck endpoint to determine if the instances are running correctly