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.

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

Cloud Customers​

For cloud customers who self-host a proxy server, you must configure each SDK Connection to use a custom proxy webhook URL. 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