Skip to main content

Environment Variables

The default configuration in GrowthBook is optimized for trying things out quickly on a local dev machine. Beyond that, you can customize behavior with Environment Variables.

Domains and Ports​

This is used to generate links to GrowthBook and enable CORS access to the API.

  • APP_ORIGIN - default http://localhost:3000
  • API_HOST - default http://localhost:3100

If you want to run GrowthBook on a different host than localhost, you need to add the above environment variables to your docker-compose.yml file.

growthbook:
  ...
  environment:
    - APP_ORIGIN=http://<my ip>:3000
    - API_HOST=http://<my ip>:3100
Unique ports on the same domain

The back-end and the front-end must run on unique ports if on the same domain.

The front-end has its own set of /api routes so currently we do not support running both the API and the front-end on the same port on the same domain.

Important

In order for authentication cookies to work correctly, both the app and api domains must be considered the "same site". They can be on different subdomains or ports, but the root domain must be the same.

  • Works: gb.example.com and gb-api.example.com
  • Breaks: gb-example.com and gb-api-example.com

If you need to change the ports on your local dev environment (e.g. if 3000 is already being used), you need to update the above variables AND change the port mapping in docker-compose.yml:

growthbook:
  ports:
    - "4000:3000" # example: use 4000 instead of 3000 for the app
    - "4100:3100" # example: use 4100 instead of 3100 for the api
  ...
  environment:
    - APP_ORIGIN=http://<my ip or url>:4000
    - API_HOST=http://<my ip or url>:4100

Production Settings​

  • NODE_ENV - Set to "production" to turn on additional optimizations and API request logging
  • MONGODB_URI - The MongoDB connection string
  • JWT_SECRET - Auth signing key (use a long random string)
  • ENCRYPTION_KEY - Data source credential encryption key (use a long random string)

If you change the ENCRYPTION_KEY, you will need to migrate any existing data sources using the following script:

# If you didn't have an ENCRYPTION_KEY before, leave OLD_KEY blank below
docker-compose run growthbook yarn migrate-encryption-key OLD_KEY
Important

When using GrowthBook in production, it is important to change the

NODE_ENV to to "production" and change theJWT_SECRET to a random string. Using the productionnode environment and the default JWT_SECRET will throw an error.

Email SMTP Settings​

This is required in order to send experiment alerts, team member invites, and reset password emails.

  • EMAIL_ENABLED ("true" or "false")
  • EMAIL_HOST
  • EMAIL_PORT
  • EMAIL_HOST_USER
  • EMAIL_HOST_PASSWORD
  • EMAIL_FROM

Google OAuth Settings​

Only required if using Google Analytics as a data source

  • GOOGLE_OAUTH_CLIENT_ID
  • GOOGLE_OAUTH_CLIENT_SECRET

File Uploads​

The UPLOAD_METHOD environment variable controls where to store uploaded files and screenshots. The supported values are local, s3, and google-cloud.

local​

This is the default value. Uploads are stored in the GrowthBook docker container at /usr/local/src/app/packages/back-end/uploads. In production, you should mount a volume here to persist uploads across container restarts.

s3​

Store uploads in an AWS S3 bucket.

  • S3_BUCKET
  • S3_REGION (defaults to us-east-1)
  • S3_DOMAIN (defaults to https://${S3_BUCKET}.s3.amazonaws.com/)
  • AWS_ACCESS_KEY_ID (not required when deployed to AWS with an instance role)
  • AWS_SECRET_ACCESS_KEY (not required when deployed to AWS with an instance role)

google-cloud​

Store uploads in a Google Cloud Storage bucket.

  • GCS_BUCKET_NAME
  • GCS_DOMAIN (defaults to https://storage.googleapis.com/${GCS_BUCKET_NAME}/)
  • GOOGLE_APPLICATION_CREDENTIALS (not required when deployed to GCP with an instance service account)

Enterprise Settings​

Some features in self-hosted GrowthBook are only available with a commercial license key. You can get a trial Enterprise key from your self-hosted version of GrowthBook, or reach out to sales@alphalang.ai to learn more.

License Keys​

If you have a license key, you can activate it in GrowthBook two different ways:

  1. Navigate to Settings > General and look for the License section of the page. There you can input or edit your license key string. (Recommended)
  2. Alternately, set the environment variable LICENSE_KEY to your license key string. If using Docker, go to docker-compose.yml and add the variable to the growthbook > environment section.

Enterprise SSO​

To enable SSO on your self hosted GrowthBook instance, you will need an active license key (see above section), and then you may add the SSO settings for your provider. If your provider is not listed below, you can use the generic Open ID Connect below. The JSON object with the settings will need to be JSON encoded and then set to the environment variable SSO_CONFIG.

Generic Open ID Connect​

  • LICENSE_KEY - Your signed license key provided by the GrowthBook team
  • SSO_CONFIG - A JSON-encoded string that configures SSO (using OpenID Connect). It should be an object with the following keys:
    • clientId (string)
    • clientSecret (string)
    • emailDomains (string[], optional) - Allow auto-joining from only specified email domains
    • metadata (object)
      • issuer (string)
      • authorization_endpoint (string)
      • jwks_uri (string)
      • id_token_signing_alg_values_supported (array of strings)
      • token_endpoint (string)
      • code_challenge_methods_supported (array of strings)
      • logout_endpoint (string, optional)
    • extraQueryParams (object, optional) - Dictionary of extra query params to be passed along with the /authorize OAuth call
    • additionalScope (string, optional) - Additional scopes to include, along with the default value: openid profile email

For SSO, make sure the following callback URL is whitelisted:

  • {APP_ORIGIN}/oauth/callback

For the best SSO user experience, enable offline access and refresh tokens in your Identity Provder.

Note

With all the SSO providers listed below, replace the all caps values with values from the provider, JSON encode the object, and set to the SSO_CONFIG environment variable for GrowthBook.

Okta​

{
    "clientId": "CLIENT_ID",
    "clientSecret": "CLIENT_SECRET",
    "emailDomains": ["EMAIL_DOMAIN"],
    "additionalScope": "offline_access",
    "metadata": {
        "issuer": "BASE_URL",
        "authorization_endpoint": "BASE_URL/oauth2/v1/authorize",
        "id_token_signing_alg_values_supported": [
            "RS256"
        ],
        "jwks_uri": "BASE_URL/oauth2/v1/keys",
        "token_endpoint": "BASE_URL/oauth2/v1/token",
        "code_challenge_methods_supported": [
            "S256"
        ]
    }
}
See complete Okta instructions
  1. Create an OIDC Web application:
  2. Allow refresh tokens and specify callback URLs. If you are using the cloud, you can use the following values:
    • Sign-in redirect URIs - https://app.alphalang.ai/oauth/callback
    • Sign-out redirect URIs (optional) - https://app.alphalang.ai

    If you are self-hosting, replace with https://app.alphalang.ai with the value from your API_HOST

  3. Require PKCE as additional verification(optional)

    You will need the following in order to configure SSO in GrowthBook:
    • CLIENT_ID
    • CLIENT_SECRET
    • BASE_URL
    • EMAIL_DOMAIN

    If using GrowthBook Cloud, first sign up for an account at https://app.alphalang.ai, then send us the above and we will enable SSO on your account.

    If self-hosting, add the environment settings at the beginning of this section to enable SSO on your instance.

Google​

{
    "clientId": "CLIENT_ID",
    "clientSecret": "CLIENT_SECRET",
    "emailDomains": ["EMAIL_DOMAIN"],
    "metadata": {
        "issuer": "https://accounts.google.com",
        "authorization_endpoint": "https://accounts.google.com/o/oauth2/v2/auth",
        "token_endpoint": "https://oauth2.googleapis.com/token",
        "jwks_uri": "https://www.googleapis.com/oauth2/v3/certs",
        "id_token_signing_alg_values_supported": [
            "RS256"
        ],
        "code_challenge_methods_supported": [
            "S256"
        ]
    },
    "extraQueryParams": {
        "access_type": "offline",
        "prompt": "consent"
    }
}

Auth0​

{
    "clientId": "CLIENT_ID",
    "clientSecret": "CLIENT_SECRET",
    "emailDomains": ["EMAIL_DOMAIN"],
    "additionalScope": "offline_access",
    "metadata": {
        "issuer": "https://TENANT.auth0.com/",
        "authorization_endpoint": "https://TENANT.auth0.com/authorize",
        "logout_endpoint": "https://TENANT.auth0.com/v2/logout?client_id=CLIENT_ID",
        "id_token_signing_alg_values_supported": [
            "HS256",
            "RS256"
        ],
        "jwks_uri": "https://TENANT.auth0.com/.well-known/jwks.json",
        "token_endpoint": "https://TENANT.auth0.com/oauth/token",
        "code_challenge_methods_supported": [
            "S256",
            "plain"
        ],
        "audience": "AUDIENCE"
    }
}
note

When setting up Auth0, please ensure that you've enabled offline access, and check the OIDC Compliant checkbox.

Azure AD​

{
  "clientId": "CLIENT_ID",
  "clientSecret": "CLIENT_SECRET",
  "emailDomains": ["EMAIL_DOMAIN"],
  "additionalScope": "offline_access",
  "metadata": {
    "token_endpoint": "https://login.microsoftonline.com/TENANT_ID/oauth2/v2.0/token",
    "jwks_uri": "https://login.microsoftonline.com/TENANT_ID/discovery/v2.0/keys",
    "id_token_signing_alg_values_supported": ["RS256"],
    "code_challenge_methods_supported": ["S256"],
    "issuer": "https://login.microsoftonline.com/TENANT_ID/v2.0",
    "authorization_endpoint": "https://login.microsoftonline.com/TENANT_ID/oauth2/v2.0/authorize",
    "logout_endpoint": "https://login.microsoftonline.com/TENANT_ID/oauth2/v2.0/logout",
  }
}
note

In Azure, register an Application, instead of Enterprise, as we use OpenID Connect, not SAML.

See complete Azure instructions
  1. Register an Application (we use OpenID Connect, so choose regular app, not Enterprise)
  2. Enter the redirect URL as APP_HOST/oauth/callback
  3. Take note of your Application Id (CLIENT_ID) and Directory Id (TENANT_ID). You will need it later
  4. Generate a new Client Secret
  5. Take note of the Secret Value (CLIENT_SECRET). You will need it in the next step
  6. Construct the JSON configuration for GrowthBook. Replace CLIENT_ID, CLIENT_SECRET, EMAIL_DOMAIN, and TENANT_ID, as into the JSON object above.
  7. Pass the JSON string into the environment variable SSO_CONFIG of your GrowthBook container

Observability (OpenTelemetry)​

The GrowthBook API is instrumented with OpenTelemetry to publish observability metrics, traces, and logs.

To enable, you must change the Docker CMD from the default yarn start to yarn start:with-tracing.

The standard OTEL_* Environment Variables are supported, such as OTEL_SERVICE_NAME and OTEL_EXPORTER_OTLP_ENDPOINT.

Other Settings​

  • EXPERIMENT_REFRESH_FREQUENCY - Default update schedule for experiment results. Update when stale for X hours (default 6).
  • QUERY_CACHE_TTL_MINS - How long (in minutes) to cache and re-use SQL query results (default 60)
  • DEFAULT_CONVERSION_WINDOW_HOURS - How many hours after being put into an experiment does a user have to convert. Can be overridden on a per-metric basis. (default 72)
  • DISABLE_TELEMETRY - We collect anonymous telemetry data to help us improve GrowthBook. Set to "true" to disable.
  • STORE_SEGMENTS_IN_MONGO - If using the config.yml file, set to true if you want to store segments in Mongo. This is also useful if you have existing segments stored in Mongo that you need to access. When set, GrowthBook will ignore segments in the config.yml file and only use Segments stored in Mongo.
  • CDN_HOST - When set, this will update the implementation instructions within GrowthBook to override the API_HOST in cases where a CDN is used.
  • EXPRESS_TRUST_PROXY_OPTS - Express' trust proxy setting value. Supports boolean (true/false), string values, and integer values for trusting the nth hop from the front-facing proxy server as the client. Leavy empty or specify false to use Express' default behavior. If you are running GrowthBook behind a proxy or load balancer, this is required to track the correct user IP for audit log events.