Deploying GrowthBook

Introduction

GrowthBook is an open-source feature flagging and A/B testing platform that empowers teams to deploy features safely, run experiments, and make data-driven decisions. Built with modern development workflows in mind, GrowthBook provides a robust solution for managing feature rollouts, conducting experiments, and analyzing results—all while maintaining full control over your data.

Deploying GrowthBook on Klutch.sh provides a scalable, production-ready infrastructure for your feature management and experimentation platform, with support for persistent data storage, database integration, and flexible configuration options. This guide covers everything you need to deploy GrowthBook successfully, from initial setup to production best practices.

---

Prerequisites

Before deploying GrowthBook on Klutch.sh, ensure you have:

• A Klutch.sh account (sign up here)
• A GitHub repository for your GrowthBook deployment configuration
• A MongoDB database (either a managed service like MongoDB Atlas or a self-hosted instance)
• Basic familiarity with Docker and environment variables
• (Optional) A data warehouse connection for importing experiment results (BigQuery, Snowflake, Redshift, etc.)

---

Understanding GrowthBook Architecture

GrowthBook consists of two main components:

1. GrowthBook Application: The main web interface for managing features, experiments, and viewing results
2. MongoDB Database: Stores all application data including feature flags, experiment configurations, user accounts, and settings

For production deployments, you’ll also want to consider:

• Data Source Connections: Optional connections to your data warehouse for importing experiment results
• Redis Cache: Optional caching layer for improved performance at scale
• Persistent Storage: Required for uploaded files and media assets

---

Getting Started: Preparing Your Repository

1. Create a new directory for your GrowthBook deployment configuration:

   mkdir growthbook-klutch
   cd growthbook-klutch

2. Create a Dockerfile in the root of your repository. This ensures consistent, reproducible deployments:

   # Use the official GrowthBook Docker image
   FROM growthbook/growthbook:latest
   
   # Set working directory
   WORKDIR /usr/local/src/app
   
   # Expose the default GrowthBook port
   EXPOSE 3100
   
   # The base image already includes the start command
   # CMD ["yarn", "start"]

   Note: You can pin to a specific version for production stability, e.g., growthbook/growthbook:2.5.0. Check the Docker Hub tags for available versions.

3. (Optional) Create a .dockerignore file to exclude unnecessary files:

   .git
   .gitignore
   node_modules
   npm-debug.log
   README.md
   .env
   .env.local

4. Create a README.md file documenting your configuration and deployment notes:

   # GrowthBook Deployment on Klutch.sh
   
   This repository contains the configuration for deploying GrowthBook on Klutch.sh.
   
   ## Environment Variables
   
   See the Klutch.sh dashboard for the required environment variables.
   
   ## Deployment
   
   Push changes to the main branch to trigger automatic deployment on Klutch.sh.

5. Initialize a Git repository and push to GitHub:

   git init
   git add .
   git commit -m "Initial GrowthBook deployment configuration"
   git branch -M main
   git remote add origin https://github.com/your-username/growthbook-klutch.git
   git push -u origin main

---

Setting Up MongoDB

GrowthBook requires MongoDB for storing all application data. You have several options:

Option 1: MongoDB Atlas (Recommended)

1. Create a free account at MongoDB Atlas
2. Create a new cluster (the free M0 tier works well for getting started)
3. Create a database user with read/write permissions
4. Add 0.0.0.0/0 to the IP whitelist (or specific Klutch.sh IPs if available)
5. Get your connection string (it should look like: mongodb+srv://username:password@cluster.mongodb.net/growthbook)

Option 2: Self-Hosted MongoDB on Klutch.sh

1. Deploy a MongoDB instance on Klutch.sh (see the MongoDB deployment guide)
2. Configure persistent volumes for MongoDB data
3. Note the internal connection details for GrowthBook to connect

---

Deploying GrowthBook on Klutch.sh

Klutch.sh automatically detects the Dockerfile in your repository and uses it to build and deploy your application.

1. Log in to Klutch.sh

2. Create a new project (if you haven’t already) and give it a descriptive name like “GrowthBook Production”

3. Create a new app within your project:

   • Name: Choose a name like “growthbook”
   • Repository: Select your GitHub repository containing the Dockerfile
   • Branch: Select main or your preferred deployment branch
   • Traffic Type: Select HTTP
   • Internal Port: Set to 3100 (GrowthBook’s default port)

4. Configure compute resources based on your expected usage:

   • Region: Choose the region closest to your users or data sources
   • Compute: Start with 1 CPU and 2GB RAM, scale up as needed
   • Instances: Start with 1 instance, increase for high availability

5. Configure environment variables (see next section for details)

6. Click Create to deploy

Klutch.sh will automatically detect your Dockerfile, build the image, and deploy your GrowthBook instance. Your application will be available at a URL like example-app.klutch.sh.

---

Required Environment Variables

Configure these environment variables in your Klutch.sh app settings:

Core Configuration

# MongoDB Connection
MONGODB_URI=mongodb+srv://username:password@cluster.mongodb.net/growthbook

# Application URL (your Klutch.sh app URL)
APP_ORIGIN=https://example-app.klutch.sh

# Secret key for JWT tokens (generate a secure random string)
JWT_SECRET=your-secure-random-string-here

# Secret key for encryption (generate a secure random string)
ENCRYPTION_KEY=your-secure-encryption-key-here

Optional Configuration

# Email Configuration (for user invitations and notifications)
EMAIL_ENABLED=true
EMAIL_HOST=smtp.sendgrid.net
EMAIL_PORT=587
EMAIL_HOST_USER=apikey
EMAIL_HOST_PASSWORD=your-sendgrid-api-key
EMAIL_FROM=noreply@yourdomain.com

# Data Source Connections (for experiment analysis)
# Example for BigQuery
BIGQUERY_PROJECT_ID=your-project-id
BIGQUERY_DATASET=your-dataset

# Redis (for caching and improved performance)
REDIS_URL=redis://your-redis-host:6379

# Enable multi-organization mode
IS_MULTI_ORG=false

# License key (for Enterprise features)
LICENSE_KEY=your-license-key-here

Security Notes

• Always store sensitive values like JWT_SECRET, ENCRYPTION_KEY, and database credentials as secrets in Klutch.sh
• Generate secure random strings for JWT_SECRET and ENCRYPTION_KEY using: openssl rand -hex 32
• Never commit secrets to your Git repository
• Rotate secrets periodically for enhanced security

---

Setting Up Persistent Storage

GrowthBook needs persistent storage for uploaded files, media assets, and local file-based caching.

1. In your Klutch.sh app settings, navigate to the Volumes section

2. Add a persistent volume:

   • Mount Path: /usr/local/src/app/uploads
   • Size: Start with 5GB, increase based on your usage

3. (Optional) Add additional volumes for caching:

   • Mount Path: /usr/local/src/app/.cache
   • Size: 2GB

Persistent volumes ensure that uploaded files and cached data survive app restarts and redeployments.

---

Initial Setup and Configuration

1. Once your GrowthBook app is deployed, navigate to your app URL (e.g., https://example-app.klutch.sh)

2. Complete the initial setup wizard:

   • Create your admin account
   • Set up your organization name
   • Configure your data source connections (if using)

3. Create your first feature flag:

   • Click Features in the navigation
   • Click Add Feature
   • Give it a name and description
   • Set the default value
   • Click Save

4. Generate SDK connections:

   • Click SDK Connections in the navigation
   • Click Add SDK Connection
   • Choose your language/platform
   • Copy the SDK endpoint and client key
   • Integrate into your application

5. Configure team access:

   • Click Settings → Team
   • Invite team members via email
   • Assign appropriate roles (Admin, Engineer, Analyst, etc.)

---

Integrating GrowthBook into Your Application

After deployment, integrate GrowthBook into your application to use feature flags and run experiments.

Example: JavaScript/Node.js Integration

1. Install the GrowthBook SDK:

   npm install @growthbook/growthbook

2. Initialize GrowthBook in your application:

   import { GrowthBook } from '@growthbook/growthbook';
   
   // Create a GrowthBook instance
   const growthbook = new GrowthBook({
     apiHost: 'https://example-app.klutch.sh',
     clientKey: 'sdk-abc123xyz',
     enableDevMode: true, // Set to false in production
   
     // User attributes for targeting
     attributes: {
       id: user.id,
       email: user.email,
       country: user.country,
       // Add any other user attributes
     }
   });
   
   // Load features from the API
   await growthbook.loadFeatures();
   
   // Check if a feature is enabled
   if (growthbook.isOn('new-checkout-flow')) {
     // Show new checkout flow
   } else {
     // Show old checkout flow
   }
   
   // Get a feature value with a fallback
   const buttonColor = growthbook.getFeatureValue('button-color', 'blue');

3. Use feature flags in your components:

   function CheckoutButton() {
     const buttonColor = growthbook.getFeatureValue('button-color', 'blue');
     const isEnabled = growthbook.isOn('new-checkout-button');
   
     if (!isEnabled) return null;
   
     return (
       <button style={{ backgroundColor: buttonColor }}>
         Complete Purchase
       </button>
     );
   }

Example: React Integration

1. Install the React SDK:

   npm install @growthbook/growthbook-react

2. Set up the GrowthBook provider:

   import { GrowthBook, GrowthBookProvider } from '@growthbook/growthbook-react';
   
   const growthbook = new GrowthBook({
     apiHost: 'https://example-app.klutch.sh',
     clientKey: 'sdk-abc123xyz',
     attributes: {
       id: user.id,
       loggedIn: !!user,
     }
   });
   
   function App() {
     useEffect(() => {
       growthbook.loadFeatures();
     }, []);
   
     return (
       <GrowthBookProvider growthbook={growthbook}>
         <YourApp />
       </GrowthBookProvider>
     );
   }

3. Use hooks in components:

   import { useFeature, useFeatureValue } from '@growthbook/growthbook-react';
   
   function NewFeatureComponent() {
     const feature = useFeature('new-dashboard');
     const theme = useFeatureValue('theme', 'light');
   
     if (!feature.on) return <OldDashboard />;
   
     return <NewDashboard theme={theme} />;
   }

---

Running A/B Tests and Experiments

GrowthBook makes it easy to run A/B tests and analyze results:

1. Create an Experiment:

   • Navigate to Experiments in GrowthBook
   • Click Add Experiment
   • Define your hypothesis and metrics
   • Set up variations (A, B, C, etc.)
   • Configure targeting rules

2. Implement in Your Application:

   const { value } = growthbook.run({
     key: 'checkout-button-text',
     variations: ['Buy Now', 'Complete Purchase', 'Checkout']
   });
   
   // Use the variation in your UI
   <button>{value}</button>

3. Connect Your Data Source:

   • Configure BigQuery, Snowflake, Redshift, or another data warehouse
   • Set up event tracking in your analytics platform
   • Map experiment events to metrics in GrowthBook

4. Analyze Results:

   • View real-time results in the GrowthBook dashboard
   • Monitor statistical significance
   • Make data-driven decisions to roll out winning variations

---

Local Development with Docker Compose

For local development and testing, use Docker Compose to run GrowthBook alongside MongoDB:

1. Create a docker-compose.yml file:

   version: '3.8'
   
   services:
     mongodb:
       image: mongo:7
       container_name: growthbook-mongo
       restart: unless-stopped
       ports:
         - "27017:27017"
       environment:
         - MONGO_INITDB_ROOT_USERNAME=root
         - MONGO_INITDB_ROOT_PASSWORD=password
       volumes:
         - mongodb_data:/data/db
   
     growthbook:
       image: growthbook/growthbook:latest
       container_name: growthbook-app
       restart: unless-stopped
       ports:
         - "3100:3100"
       depends_on:
         - mongodb
       environment:
         - MONGODB_URI=mongodb://root:password@mongodb:27017/growthbook?authSource=admin
         - APP_ORIGIN=http://localhost:3100
         - JWT_SECRET=dev-secret-key-change-in-production
         - ENCRYPTION_KEY=dev-encryption-key-change-in-production
         - NODE_ENV=development
       volumes:
         - growthbook_uploads:/usr/local/src/app/uploads
   
   volumes:
     mongodb_data:
     growthbook_uploads:

2. Start the services:

   docker-compose up -d

3. Access GrowthBook at http://localhost:3100

4. When ready to deploy, push your Dockerfile to GitHub and deploy on Klutch.sh

Note: Docker Compose is for local development only. Klutch.sh does not support Docker Compose for deployments.

---

Production Best Practices

Security

• Enable HTTPS: Klutch.sh provides automatic HTTPS for all apps
• Use Strong Secrets: Generate cryptographically secure random strings for JWT and encryption keys
• Enable Authentication: Configure email/password authentication or integrate with OAuth providers (Google, GitHub, etc.)
• Regular Backups: Back up your MongoDB database regularly
• Role-Based Access: Use GrowthBook’s role system to limit permissions appropriately

Performance

• Enable Redis Caching: Add a Redis instance for improved performance with large feature flag sets
• Optimize Database: Index frequently queried fields in MongoDB
• Monitor Resources: Use Klutch.sh monitoring to track CPU, memory, and network usage
• Scale Horizontally: Add more instances during high-traffic periods

Reliability

• Database Replication: Use MongoDB replica sets for high availability
• Health Checks: Configure health check endpoints if supported
• Monitoring and Alerts: Set up monitoring for your GrowthBook instance
• Regular Updates: Keep GrowthBook updated to the latest stable version

Configuration Management

• Environment-Specific Settings: Use different configurations for staging and production
• Feature Flag Organization: Use tags and folders to organize features logically
• Documentation: Document your feature flags and experiments in GrowthBook
• Change Management: Implement a review process for production feature changes

---

Troubleshooting Common Issues

GrowthBook Won’t Start

• Check MongoDB Connection: Verify your MONGODB_URI is correct and the database is accessible
• Verify Environment Variables: Ensure all required environment variables are set correctly
• Check Logs: View application logs in the Klutch.sh dashboard for specific error messages
• Port Configuration: Confirm the internal port is set to 3100

Features Not Loading in SDK

• Verify SDK Endpoint: Ensure your SDK is pointing to the correct GrowthBook URL
• Check Client Key: Confirm you’re using the correct SDK client key
• CORS Configuration: If calling from a browser, ensure CORS is configured properly
• Network Connectivity: Verify your application can reach the GrowthBook instance

Performance Issues

• Enable Redis: Add Redis caching to reduce database queries
• Database Optimization: Add indexes to frequently queried MongoDB collections
• Scale Vertically: Increase CPU and RAM if the instance is under-resourced
• Scale Horizontally: Add more instances and use load balancing

Data Source Connection Failures

• Check Credentials: Verify data warehouse credentials are correct
• Network Access: Ensure GrowthBook can reach your data warehouse
• Query Permissions: Confirm the database user has necessary query permissions
• SQL Syntax: Test queries manually in your data warehouse first

---

Upgrading GrowthBook

1. Check the GrowthBook releases page for the latest version

2. Update your Dockerfile to use the new version:

   FROM growthbook/growthbook:2.6.0

3. Review the changelog for breaking changes or required migrations

4. Test in a staging environment first

5. Push the changes to GitHub:

   git add Dockerfile
   git commit -m "Update GrowthBook to v2.6.0"
   git push origin main

6. Klutch.sh will automatically rebuild and redeploy your app

7. Monitor the deployment and verify everything works correctly

---

Advanced Configuration

Custom Domain Setup

1. Configure a custom domain in Klutch.sh (see Custom Domains guide)

2. Update the APP_ORIGIN environment variable to match your custom domain:

   APP_ORIGIN=https://growthbook.yourdomain.com

3. Update SDK endpoints in your applications to use the custom domain

Multi-Organization Setup

Enable multi-organization mode if you need to support multiple teams or clients:

IS_MULTI_ORG=true

This allows you to create separate organizations within a single GrowthBook instance, each with isolated features, experiments, and users.

Webhook Integration

Configure webhooks to receive notifications when features or experiments change:

1. Navigate to Settings → Webhooks in GrowthBook
2. Add a webhook endpoint URL
3. Select the events you want to receive
4. Use webhooks to trigger CI/CD pipelines, send notifications, or update external systems

---

Monitoring and Analytics

Monitor your GrowthBook instance to ensure optimal performance:

• Application Metrics: Use Klutch.sh built-in monitoring to track CPU, memory, and network usage
• MongoDB Metrics: Monitor database performance, query times, and connection pool usage
• API Response Times: Track SDK endpoint response times to ensure fast feature flag evaluation
• Feature Usage: Use GrowthBook’s analytics to see which features are most active
• Experiment Results: Monitor experiment metrics and statistical significance in real-time

---

Resources

• GrowthBook Documentation
• GrowthBook GitHub Repository
• GrowthBook Docker Hub
• Klutch.sh Documentation
• Klutch.sh Volumes Guide
• Klutch.sh Deployments Guide

---

Deploying GrowthBook on Klutch.sh provides a robust, scalable platform for feature management and experimentation. With automatic Dockerfile detection, persistent storage, and easy scaling, you can focus on building great features and running successful experiments without worrying about infrastructure management.