Skip to content
Klutch.sh Docs

Deploying Flipt

Introduction

Flipt is a modern, Git-native feature flag platform that brings feature management directly into your development workflow. Unlike traditional feature flag services that lock your flags in proprietary databases, Flipt treats feature flags as code—storing them in your Git repositories, enabling code reviews for flag changes, and deploying flags alongside your application code using the CI/CD pipelines you already trust.

Built for developers who value control and simplicity, Flipt offers a self-hosted alternative to expensive SaaS feature flag platforms. With zero external dependencies by default, real-time flag evaluation through Server-Sent Events (SSE), comprehensive REST and gRPC APIs, and an intuitive UI with dark mode support, Flipt makes feature flagging accessible for teams of any size without the billing shock that comes with per-seat or per-flag pricing models.

This comprehensive guide walks you through deploying Flipt on Klutch.sh using a Dockerfile, configuring Git-native storage, setting up multi-environment configurations, implementing persistent volumes for data storage, and establishing production-ready best practices for feature flag management that scales with your team.

Why Deploy Flipt on Klutch.sh

Deploying Flipt on Klutch.sh provides several compelling advantages for teams implementing feature flags:

  • Zero Infrastructure Overhead: Klutch.sh handles container orchestration, load balancing, and SSL/TLS termination automatically
  • Git-Native Workflows: Keep your feature flags in Git repositories while Flipt runs as a lightweight evaluation engine
  • Cost-Effective Scaling: No per-seat or per-flag pricing—scale your feature flag infrastructure without budget concerns
  • Persistent Storage Options: Attach volumes for SQLite storage or connect external databases for production workloads
  • Real-Time Performance: Co-locate Flipt with your services for microsecond flag evaluation latency
  • Multi-Environment Support: Deploy separate Flipt instances for dev, staging, and production with environment-specific configurations
  • Automated SSL: HTTPS endpoints for secure flag evaluation without certificate management hassle
  • Simple Rollbacks: Instant rollback capabilities through Klutch.sh’s deployment history
  • Monitoring Integration: Built-in health checks and observability through Prometheus and OpenTelemetry

Prerequisites

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

  • A Klutch.sh account (sign up here)
  • A GitHub repository for your Flipt deployment configuration
  • Access to the Klutch.sh dashboard
  • Basic understanding of Docker containers and feature flag concepts
  • (Optional) A PostgreSQL or MySQL database for production deployments (see PostgreSQL guide or MySQL guide)
  • (Optional) A Git repository for storing your feature flag configurations
  • (Optional) Redis instance for distributed caching (see Redis guide)

Understanding Flipt Architecture

Flipt v2 introduces a Git-native architecture that fundamentally changes how feature flags are managed:

Core Components

  • Flipt Server: Lightweight Go binary that evaluates feature flags and serves the management UI
  • Storage Backend: Supports Git repositories, local filesystem, object storage (S3), or traditional databases (PostgreSQL, MySQL, SQLite)
  • Evaluation Engine: High-performance flag evaluation with complex targeting rules and percentage-based rollouts
  • Management UI: Modern React-based interface for creating and managing flags
  • API Layer: REST and gRPC APIs for flag evaluation and management operations
  • Real-Time Updates: Server-Sent Events (SSE) streaming for instant flag synchronization to client SDKs

Deployment Architecture Options

Git-Native Mode (Recommended):

  • Feature flags stored in Git repositories
  • Flipt polls repository for updates
  • Changes deployed through Git workflows (PRs, merge requests)
  • Full version control history for all flag changes
  • Zero database requirements

Database Mode (Traditional):

  • Flags stored in PostgreSQL, MySQL, or SQLite
  • Direct flag management through UI/API
  • Requires persistent database storage
  • Better for teams not ready for Git-based workflows

When deployed on Klutch.sh, Flipt automatically detects your Dockerfile and builds a container image. The platform manages HTTP traffic routing to port 8080 (Flipt’s default UI/API port) and port 9000 (gRPC endpoint), provides SSL termination, and offers persistent volume options for SQLite or configuration data.

Project Structure

A minimal repository structure for deploying Flipt on Klutch.sh:

flipt-deployment/
├── Dockerfile
├── config.yml              # Flipt configuration file
├── .dockerignore
├── .gitignore
└── README.md

For Git-native deployments with feature flags in the same repository:

flipt-deployment/
├── Dockerfile
├── config.yml
├── .dockerignore
├── .gitignore
├── README.md
└── flags/                  # Feature flag definitions
    ├── production/
    │   ├── features.yml
    │   └── segments.yml
    ├── staging/
    │   ├── features.yml
    │   └── segments.yml
    └── development/
        ├── features.yml
        └── segments.yml

Creating Your Dockerfile

Klutch.sh automatically detects a Dockerfile in the root directory of your repository. Create a Dockerfile that uses the official Flipt image as the base:

Option 1: Simple Dockerfile (Quick Start)

FROM docker.flipt.io/flipt/flipt:v2


# Expose Flipt's default ports
EXPOSE 8080 9000


# Flipt runs as non-root user by default
CMD ["flipt"]

Option 2: Production Dockerfile with Custom Configuration

FROM docker.flipt.io/flipt/flipt:v2.4.0


# Set working directory
WORKDIR /opt/flipt


# Copy configuration file
COPY config.yml /etc/flipt/config/config.yml


# Create directories for data and logs
RUN mkdir -p /var/opt/flipt /var/log/flipt && \
    chown -R flipt:flipt /var/opt/flipt /var/log/flipt


# Expose HTTP (UI/REST API) and gRPC ports
EXPOSE 8080 9000


# Health check for monitoring
HEALTHCHECK --interval=30s --timeout=10s --start-period=30s --retries=3 \
  CMD wget --no-verbose --tries=1 --spider http://localhost:8080/api/v1/health || exit 1


# Run as non-root user
USER flipt


# Start Flipt server with custom config
CMD ["flipt", "--config", "/etc/flipt/config/config.yml"]

Option 3: Advanced Dockerfile with Git-Native Storage

FROM docker.flipt.io/flipt/flipt:v2.4.0


# Install git for repository cloning and polling
USER root
RUN apk add --no-cache git openssh-client ca-certificates


# Create necessary directories
RUN mkdir -p /etc/flipt/config /var/opt/flipt /var/log/flipt && \
    chown -R flipt:flipt /etc/flipt /var/opt/flipt /var/log/flipt


# Copy Flipt configuration
COPY config.yml /etc/flipt/config/config.yml


# Switch to flipt user for security
USER flipt


WORKDIR /opt/flipt


# Expose HTTP (8080) and gRPC (9000) ports
EXPOSE 8080 9000


# Health check endpoint
HEALTHCHECK --interval=30s --timeout=10s --start-period=30s --retries=3 \
  CMD wget --no-verbose --tries=1 --spider http://localhost:8080/api/v1/health || exit 1


# Start Flipt with custom configuration
CMD ["flipt", "--config", "/etc/flipt/config/config.yml"]

Important Notes:

  • Flipt’s default HTTP/REST API and UI run on port 8080
  • The gRPC API runs on port 9000 (optional, can be disabled)
  • The official image runs as a non-root user (flipt) for security
  • Configuration can be provided via file, environment variables, or both
  • Git support requires git binary for repository operations

Configuration Options

Create a config.yml file to customize Flipt’s behavior. Here are configuration examples for common scenarios:

Basic Configuration (In-Memory Storage)

version: "1.0"


# Server configuration
server:
  http:
    # HTTP server address
    host: 0.0.0.0
    port: 8080
  grpc:
    # gRPC server address (optional)
    host: 0.0.0.0
    port: 9000


# Logging configuration
log:
  level: info
  encoding: json


# Storage backend (in-memory for testing)
storage:
  type: local
  local:
    path: /var/opt/flipt


# UI configuration
ui:
  enabled: true

Git-Native Storage Configuration

version: "1.0"


server:
  http:
    host: 0.0.0.0
    port: 8080
  grpc:
    host: 0.0.0.0
    port: 9000


log:
  level: info
  encoding: json


# Git-native storage
storage:
  type: git
  git:
    # Repository URL (public or private)
    repository: "https://github.com/your-org/feature-flags.git"


    # Branch or tag to track
    ref: "main"


    # Poll interval for updates
    poll_interval: "30s"


    # Optional: Authentication for private repositories
    authentication:
      token:
        # Use environment variable for security
        access_token: ${FLIPT_GIT_TOKEN}


# Enable environments
environments:
  enabled: true


  # Define environments
  default:
    storage:
      type: git
      git:
        directory: "production"


  staging:
    storage:
      type: git
      git:
        directory: "staging"


  development:
    storage:
      type: git
      git:
        directory: "development"


ui:
  enabled: true

Database Storage Configuration (PostgreSQL)

version: "1.0"


server:
  http:
    host: 0.0.0.0
    port: 8080
  grpc:
    host: 0.0.0.0
    port: 9000


log:
  level: info
  encoding: json


# PostgreSQL storage backend
storage:
  type: database
  database:
    url: "postgres://${FLIPT_DB_USER}:${FLIPT_DB_PASSWORD}@${FLIPT_DB_HOST}:${FLIPT_DB_PORT}/${FLIPT_DB_NAME}?sslmode=disable"


    # Connection pool settings
    max_idle_conn: 2
    max_open_conn: 20
    conn_max_lifetime: 60m


# Database migrations run automatically
db:
  migrate: true


ui:
  enabled: true

Production Configuration with Authentication

version: "1.0"


server:
  http:
    host: 0.0.0.0
    port: 8080
  grpc:
    host: 0.0.0.0
    port: 9000


log:
  level: info
  encoding: json
  grpc_level: error


# Authentication configuration
authentication:
  required: true


  methods:
    # Token-based authentication
    token:
      enabled: true
      bootstrap:
        # Generate token on first startup
        token: ${FLIPT_AUTH_TOKEN}
        expiration: never


    # OIDC authentication
    oidc:
      enabled: true
      providers:
        google:
          issuer_url: "https://accounts.google.com"
          client_id: ${OIDC_CLIENT_ID}
          client_secret: ${OIDC_CLIENT_SECRET}
          redirect_address: "https://example-app.klutch.sh"
          scopes:
            - openid
            - email
            - profile


storage:
  type: git
  git:
    repository: "https://github.com/your-org/feature-flags.git"
    ref: "main"
    poll_interval: "30s"
    authentication:
      token:
        access_token: ${FLIPT_GIT_TOKEN}


# Cache configuration for performance
cache:
  enabled: true
  backend: memory
  ttl: 60s


# Observability
tracing:
  enabled: true
  exporter: otlp
  otlp:
    endpoint: "localhost:4317"


metrics:
  enabled: true
  exporter: prometheus


ui:
  enabled: true


cors:
  enabled: true
  allowed_origins:
    - "https://example-app.klutch.sh"
    - "https://www.example-app.klutch.sh"

Deploying to Klutch.sh

Follow these steps to deploy Flipt on Klutch.sh with persistent storage and proper configuration.

Deployment Steps

    1. Create Your Repository

      Create a new GitHub repository and add your Dockerfile and configuration:

      Terminal window
      mkdir flipt-deployment
      cd flipt-deployment
      

      # Create basic Dockerfile
      cat > Dockerfile << 'EOF'
      FROM docker.flipt.io/flipt/flipt:v2.4.0
      

      WORKDIR /opt/flipt
      

      # Copy configuration
      COPY config.yml /etc/flipt/config/config.yml
      

      # Expose HTTP and gRPC ports
      EXPOSE 8080 9000
      

      # Health check
      HEALTHCHECK --interval=30s --timeout=10s --start-period=30s --retries=3 \
        CMD wget --no-verbose --tries=1 --spider http://localhost:8080/api/v1/health || exit 1
      

      CMD ["flipt", "--config", "/etc/flipt/config/config.yml"]
      EOF
      

      # Create basic configuration
      cat > config.yml << 'EOF'
      version: "1.0"
      

      server:
        http:
          host: 0.0.0.0
          port: 8080
        grpc:
          host: 0.0.0.0
          port: 9000
      

      log:
        level: info
        encoding: json
      

      storage:
        type: local
        local:
          path: /var/opt/flipt
      

      ui:
        enabled: true
      EOF
      

      # Create .gitignore
      cat > .gitignore << 'EOF'
      *.db
      *.sqlite3
      .env
      .DS_Store
      /var/
      EOF
      

      # Initialize git and push
      git init
      git add .
      git commit -m "Initial Flipt deployment setup"
      git remote add origin https://github.com/YOUR_USERNAME/flipt-deployment.git
      git push -u origin main

    2. Access the Klutch.sh Dashboard

      Navigate to klutch.sh/app and log in to your account.

    3. Create a New Project

      • Click “New Project” in the dashboard
      • Enter a project name (e.g., “Feature Flags”)
      • Select your preferred region for deployment

    4. Create a New Application

      • Within your project, click “New App”
      • Name your application (e.g., “Flipt”)
      • Connect your GitHub repository containing the Dockerfile

    5. Configure Traffic Settings

      • In the app settings, select HTTP as the traffic type
      • Flipt serves web traffic on HTTP for both the UI and API
      • Set the internal port to 8080 (Flipt’s default HTTP port)

      Note: If you need gRPC access, you’ll need to configure additional routing for port 9000.

    6. Set Up Persistent Storage (Recommended)

      For production deployments using SQLite or local storage, attach a persistent volume:

      • In the app settings, navigate to the “Volumes” section
      • Click “Add Volume”
      • Set the mount path to /var/opt/flipt
      • Set the volume size (recommended: 5GB for typical workloads)
      • Click “Add” to attach the volume

      Important: The /var/opt/flipt directory stores:

      • SQLite database files (if using local storage)
      • Local flag definitions
      • Cache data
      • Application state

      Alternative: For Git-native storage, persistent volumes are not strictly required since flags are stored in your Git repository.

    7. Configure Environment Variables

      Add environment variables for Flipt configuration:

      For Git-Native Storage:

      Terminal window
      # Git repository authentication token
      FLIPT_GIT_TOKEN=ghp_your_github_token_here
      

      # Log level
      FLIPT_LOG_LEVEL=info

      For Database Storage (PostgreSQL Example):

      Terminal window
      # Database connection details
      FLIPT_DB_HOST=postgres-app.klutch.sh
      FLIPT_DB_PORT=8000
      FLIPT_DB_NAME=flipt
      FLIPT_DB_USER=flipt_user
      FLIPT_DB_PASSWORD=your-secure-database-password
      

      # Log level
      FLIPT_LOG_LEVEL=info

      For Authentication:

      Terminal window
      # Generate with: openssl rand -hex 32
      FLIPT_AUTH_TOKEN=your-auth-token-here
      

      # OIDC configuration (optional)
      OIDC_CLIENT_ID=your-google-client-id
      OIDC_CLIENT_SECRET=your-google-client-secret

      Performance Tuning:

      Terminal window
      # Cache settings
      FLIPT_CACHE_ENABLED=true
      FLIPT_CACHE_TTL=60s
      

      # Database connection pool (if using database storage)
      FLIPT_DB_MAX_IDLE_CONN=2
      FLIPT_DB_MAX_OPEN_CONN=20

    8. Deploy the Application

      • Review all configuration settings
      • Click “Deploy” to start the build process
      • Klutch.sh will automatically detect your Dockerfile, build the container, and deploy it
      • Monitor the build logs for any errors

    9. Verify Deployment

      Once deployment completes:

      • Access your Flipt UI at the provided Klutch.sh URL (e.g., https://flipt-abc123.klutch.sh)
      • You should see the Flipt dashboard and welcome screen
      • Check the health endpoint: https://flipt-abc123.klutch.sh/api/v1/health

    10. Initial Setup

      On first access:

      • If authentication is disabled, you’ll have immediate access to the UI
      • If authentication is enabled, log in with your configured method (token or OIDC)
      • Create your first namespace and feature flag through the UI

Creating Feature Flags

Once Flipt is deployed, you can create feature flags through the UI or via configuration files.

Via UI

  1. Navigate to your Flipt dashboard
  2. Create a new namespace (e.g., “production”, “staging”)
  3. Click “Create Flag”
  4. Configure your flag:
    • Key: Unique identifier (e.g., new-checkout-flow)
    • Name: Display name (e.g., “New Checkout Flow”)
    • Description: Purpose of the flag
    • Type: Boolean or Variant
    • Enabled: Toggle flag state

Via Configuration File (Git-Native)

Create a features.yml file in your Git repository:

# features.yml - Feature flag definitions
version: "1.0"


namespace: production


flags:
  - key: new-checkout-flow
    name: New Checkout Flow
    description: Enable redesigned checkout experience
    enabled: true
    type: boolean


  - key: payment-provider
    name: Payment Provider
    description: Select payment processing provider
    enabled: true
    type: variant
    variants:
      - key: stripe
        name: Stripe
        description: Process payments via Stripe
      - key: paypal
        name: PayPal
        description: Process payments via PayPal
      - key: square
        name: Square
        description: Process payments via Square


segments:
  - key: beta-users
    name: Beta Users
    description: Users enrolled in beta program
    constraints:
      - type: string
        property: user_tier
        operator: eq
        value: beta


  - key: premium-users
    name: Premium Users
    description: Users with premium subscriptions
    constraints:
      - type: string
        property: subscription
        operator: eq
        value: premium


rules:
  - flag: new-checkout-flow
    segment: beta-users
    distributions:
      - variant: enabled
        rollout: 100


  - flag: payment-provider
    segment: premium-users
    distributions:
      - variant: stripe
        rollout: 80
      - variant: paypal
        rollout: 20

Commit and push this file to your Git repository—Flipt will automatically pick up the changes based on your configured poll interval.

Integrating with Your Application

Flipt provides multiple ways to evaluate feature flags in your applications:

REST API Example

Terminal window
# Evaluate a boolean flag
curl -X POST https://flipt-abc123.klutch.sh/api/v1/evaluate \
  -H "Content-Type: application/json" \
  -d '{
    "namespace": "production",
    "flag": "new-checkout-flow",
    "entity_id": "user-123",
    "context": {
      "user_tier": "premium"
    }
  }'


# Response:
{
  "flag_key": "new-checkout-flow",
  "match": true,
  "segment_keys": ["premium-users"],
  "reason": "MATCH_EVALUATION_REASON",
  "request_duration_millis": 2
}

Node.js SDK (Server-Side Evaluation)

const { FliptEvaluationClient } = require('@flipt-io/flipt');


const client = new FliptEvaluationClient({
  url: 'https://flipt-abc123.klutch.sh',
  auth_token: 'your-auth-token' // If authentication is enabled
});


async function checkFeature(userId) {
  try {
    const result = await client.boolean({
      namespace: 'production',
      flag_key: 'new-checkout-flow',
      entity_id: userId,
      context: {
        user_tier: 'premium',
        country: 'US'
      }
    });


    if (result.enabled) {
      console.log('New checkout flow is enabled for user');
      return true;
    } else {
      console.log('Using legacy checkout flow');
      return false;
    }
  } catch (error) {
    console.error('Flag evaluation error:', error);
    return false; // Fail safe to default behavior
  }
}


// Use in your application
async function processCheckout(userId) {
  const useNewFlow = await checkFeature(userId);


  if (useNewFlow) {
    // Execute new checkout logic
  } else {
    // Execute legacy checkout logic
  }
}

Python SDK (Server-Side Evaluation)

from flipt import FliptClient


client = FliptClient(
    url="https://flipt-abc123.klutch.sh",
    auth_token="your-auth-token"  # If authentication is enabled
)


def check_feature(user_id: str) -> bool:
    try:
        result = client.evaluate_boolean(
            namespace="production",
            flag_key="new-checkout-flow",
            entity_id=user_id,
            context={
                "user_tier": "premium",
                "country": "US"
            }
        )
        return result.enabled
    except Exception as e:
        print(f"Flag evaluation error: {e}")
        return False  # Fail safe to default behavior


# Use in your application
def process_checkout(user_id: str):
    use_new_flow = check_feature(user_id)


    if use_new_flow:
        # Execute new checkout logic
        pass
    else:
        # Execute legacy checkout logic
        pass

Go SDK (Server-Side Evaluation)

package main


import (
    "context"
    "fmt"
    "log"


    flipt "go.flipt.io/flipt/sdk/go"
    "go.flipt.io/flipt/sdk/go/grpc"
)


func main() {
    ctx := context.Background()


    // Create Flipt client
    client := grpc.NewGRPCClient("flipt-abc123.klutch.sh:443",
        grpc.WithHTTPS(), // Use HTTPS
    )


    // Evaluate boolean flag
    result, err := client.Boolean(ctx, &flipt.EvaluationRequest{
        NamespaceKey: "production",
        FlagKey:      "new-checkout-flow",
        EntityId:     "user-123",
        Context: map[string]string{
            "user_tier": "premium",
            "country":   "US",
        },
    })


    if err != nil {
        log.Printf("Flag evaluation error: %v", err)
        // Fail safe to default behavior
        return
    }


    if result.Enabled {
        fmt.Println("New checkout flow is enabled")
        // Execute new checkout logic
    } else {
        fmt.Println("Using legacy checkout flow")
        // Execute legacy checkout logic
    }
}

Client-Side SDK (React Example)

For real-time flag updates in browser applications:

import React, { useEffect, useState } from 'react';


function useFeatureFlag(flagKey, userId) {
  const [enabled, setEnabled] = useState(false);
  const [loading, setLoading] = useState(true);


  useEffect(() => {
    const evaluateFlag = async () => {
      try {
        const response = await fetch('https://flipt-abc123.klutch.sh/api/v1/evaluate', {
          method: 'POST',
          headers: {
            'Content-Type': 'application/json',
            'Authorization': 'Bearer your-auth-token'
          },
          body: JSON.stringify({
            namespace: 'production',
            flag: flagKey,
            entity_id: userId,
            context: {
              user_tier: 'premium'
            }
          })
        });


        const result = await response.json();
        setEnabled(result.match);
      } catch (error) {
        console.error('Flag evaluation error:', error);
        setEnabled(false);
      } finally {
        setLoading(false);
      }
    };


    evaluateFlag();
  }, [flagKey, userId]);


  return { enabled, loading };
}


function CheckoutButton({ userId }) {
  const { enabled, loading } = useFeatureFlag('new-checkout-flow', userId);


  if (loading) {
    return <div>Loading...</div>;
  }


  return (
    <button>
      {enabled ? 'Checkout (New Experience)' : 'Checkout'}
    </button>
  );
}


export default CheckoutButton;

Database Storage Setup

For production deployments requiring centralized flag storage, configure Flipt with a database backend.

PostgreSQL Setup

  1. Deploy PostgreSQL on Klutch.sh

    Follow the PostgreSQL deployment guide to create a database instance.

  2. Create Database and User

    CREATE DATABASE flipt;
    CREATE USER flipt_user WITH ENCRYPTED PASSWORD 'secure-password';
    GRANT ALL PRIVILEGES ON DATABASE flipt TO flipt_user;

  3. Update Configuration

    Modify your config.yml:

    version: "1.0"
    

    storage:
      type: database
      database:
        url: "postgres://flipt_user:secure-password@postgres-app.klutch.sh:8000/flipt?sslmode=disable"
        max_idle_conn: 2
        max_open_conn: 20
        conn_max_lifetime: 60m
    

    db:
      migrate: true  # Run migrations automatically

  4. Set Environment Variables

    Terminal window
    FLIPT_DB_HOST=postgres-app.klutch.sh
    FLIPT_DB_PORT=8000
    FLIPT_DB_NAME=flipt
    FLIPT_DB_USER=flipt_user
    FLIPT_DB_PASSWORD=secure-password

MySQL Setup

  1. Deploy MySQL on Klutch.sh

    Follow the MySQL deployment guide to create a database instance.

  2. Create Database and User

    CREATE DATABASE flipt CHARACTER SET utf8mb4 COLLATE utf8mb4_unicode_ci;
    CREATE USER 'flipt_user'@'%' IDENTIFIED BY 'secure-password';
    GRANT ALL PRIVILEGES ON flipt.* TO 'flipt_user'@'%';
    FLUSH PRIVILEGES;

  3. Update Configuration

    version: "1.0"
    

    storage:
      type: database
      database:
        url: "mysql://flipt_user:secure-password@tcp(mysql-app.klutch.sh:8000)/flipt?parseTime=true"
        max_idle_conn: 2
        max_open_conn: 20
        conn_max_lifetime: 60m
    

    db:
      migrate: true

Multi-Environment Configuration

Flipt v2’s multi-environment support allows you to manage flags across dev, staging, and production from a single instance.

Environment per Git Directory

version: "1.0"


storage:
  type: git
  git:
    repository: "https://github.com/your-org/feature-flags.git"
    ref: "main"
    poll_interval: "30s"
    authentication:
      token:
        access_token: ${FLIPT_GIT_TOKEN}


# Define environments
environments:
  enabled: true


  # Production environment
  production:
    storage:
      type: git
      git:
        directory: "production"


  # Staging environment
  staging:
    storage:
      type: git
      git:
        directory: "staging"


  # Development environment
  development:
    storage:
      type: git
      git:
        directory: "development"

Environment per Git Branch

version: "1.0"


environments:
  enabled: true


  production:
    storage:
      type: git
      git:
        repository: "https://github.com/your-org/feature-flags.git"
        ref: "production"
        poll_interval: "30s"


  staging:
    storage:
      type: git
      git:
        repository: "https://github.com/your-org/feature-flags.git"
        ref: "staging"
        poll_interval: "30s"


  development:
    storage:
      type: git
      git:
        repository: "https://github.com/your-org/feature-flags.git"
        ref: "development"
        poll_interval: "30s"

Environment per Repository

version: "1.0"


environments:
  enabled: true


  production:
    storage:
      type: git
      git:
        repository: "https://github.com/your-org/flags-production.git"
        ref: "main"


  staging:
    storage:
      type: git
      git:
        repository: "https://github.com/your-org/flags-staging.git"
        ref: "main"


  development:
    storage:
      type: git
      git:
        repository: "https://github.com/your-org/flags-development.git"
        ref: "main"

Authentication and Security

Token-Based Authentication

authentication:
  required: true


  methods:
    token:
      enabled: true
      bootstrap:
        token: ${FLIPT_AUTH_TOKEN}
        expiration: never

Generate a secure token:

Terminal window
openssl rand -hex 32

Use the token in API requests:

Terminal window
curl -X POST https://flipt-abc123.klutch.sh/api/v1/evaluate \
  -H "Authorization: Bearer your-auth-token" \
  -H "Content-Type: application/json" \
  -d '{"namespace": "production", "flag": "feature-key", "entity_id": "user-123"}'

OIDC Authentication (Google Example)

authentication:
  required: true


  methods:
    oidc:
      enabled: true
      providers:
        google:
          issuer_url: "https://accounts.google.com"
          client_id: ${OIDC_CLIENT_ID}
          client_secret: ${OIDC_CLIENT_SECRET}
          redirect_address: "https://flipt-abc123.klutch.sh"
          scopes:
            - openid
            - email
            - profile

Set up OAuth 2.0 credentials in Google Cloud Console and configure the environment variables.

Performance Optimization

Enable Caching

cache:
  enabled: true
  backend: memory
  ttl: 60s


  # For distributed caching with Redis
  # backend: redis
  # redis:
  #   host: redis-app.klutch.sh
  #   port: 8000
  #   password: ${REDIS_PASSWORD}

Database Connection Pooling

storage:
  type: database
  database:
    url: "postgres://user:pass@host:port/db"
    # Optimize connection pool for your workload
    max_idle_conn: 10
    max_open_conn: 100
    conn_max_lifetime: 60m

Client-Side Evaluation

For ultra-low latency requirements, use Flipt’s client-side evaluation SDKs that cache flags locally and update via Server-Sent Events:

import { FliptClient } from '@flipt-io/flipt-client-browser';


const client = new FliptClient({
  url: 'https://flipt-abc123.klutch.sh',
  namespace: 'production',
  // Flags are cached locally and updated in real-time via SSE
});


// Instant evaluation with zero network latency
const isEnabled = client.boolean('new-checkout-flow', 'user-123', {
  user_tier: 'premium'
});

Monitoring and Observability

Health Checks

Flipt provides a health check endpoint:

Terminal window
curl https://flipt-abc123.klutch.sh/api/v1/health

Expected response:

{
  "status": "ok"
}

Prometheus Metrics

Enable Prometheus metrics in your configuration:

metrics:
  enabled: true
  exporter: prometheus
  prometheus:
    port: 9090

Access metrics at https://flipt-abc123.klutch.sh/metrics

Key metrics to monitor:

  • flipt_flag_evaluation_duration_seconds: Flag evaluation latency
  • flipt_flag_evaluation_total: Total flag evaluations
  • flipt_flag_evaluation_errors_total: Failed evaluations
  • flipt_storage_read_duration_seconds: Storage backend read latency

OpenTelemetry Tracing

tracing:
  enabled: true
  exporter: otlp
  otlp:
    endpoint: "otel-collector:4317"
  sampling:
    ratio: 0.1  # Sample 10% of requests

Application Logs

Monitor Flipt logs through Klutch.sh dashboard or configure structured logging:

log:
  level: info
  encoding: json
  grpc_level: error

Backup and Recovery

With Git-native storage, your flags are already backed up in your Git repository. To recover:

  1. Ensure your Git repository has proper backup strategy
  2. For disaster recovery, deploy a new Flipt instance pointing to the same repository
  3. All flag configurations are automatically restored

Database Storage

For database-backed deployments, implement regular backups:

PostgreSQL Backup:

Terminal window
# Backup
pg_dump -h postgres-app.klutch.sh -p 8000 -U flipt_user flipt > flipt-backup-$(date +%Y%m%d).sql


# Restore
psql -h postgres-app.klutch.sh -p 8000 -U flipt_user flipt < flipt-backup-20231222.sql

SQLite Backup:

Terminal window
# Backup (requires access to volume)
sqlite3 /var/opt/flipt/flipt.db ".backup '/backup/flipt-backup.db'"


# Restore
cp /backup/flipt-backup.db /var/opt/flipt/flipt.db

Troubleshooting

Common Issues

Issue: Cannot access Flipt UI

  • Verify the app is running in Klutch.sh dashboard
  • Check port 8080 is correctly configured as the internal port
  • Review application logs for startup errors
  • Verify health check endpoint: curl https://your-app.klutch.sh/api/v1/health

Issue: Git repository authentication fails

Error: authentication required
  • Verify FLIPT_GIT_TOKEN environment variable is set correctly
  • Ensure the token has read access to the repository
  • For private repositories, confirm the repository URL is correct
  • Test token: git clone https://TOKEN@github.com/org/repo.git

Issue: Database connection errors

Error: failed to connect to database
  • Verify database credentials in environment variables
  • Check database host and port are correct (remember Klutch.sh databases use port 8000)
  • Ensure database exists: psql -h host -p 8000 -U user -d flipt -c "SELECT 1;"
  • Check database firewall/network rules

Issue: Flags not updating from Git repository

  • Check poll_interval configuration (default 30s)
  • Verify Git repository URL and branch are correct
  • Review logs for Git sync errors
  • Manually trigger refresh via API: POST /api/v1/storage/refresh

Issue: High latency in flag evaluations

  • Enable caching with appropriate TTL
  • Consider client-side evaluation SDKs
  • Optimize database connection pool settings
  • Review segment and rule complexity
  • Check network latency between app and Flipt

Issue: Authentication not working

  • Verify authentication is enabled in configuration
  • Check token is correctly set via environment variable
  • Ensure OIDC redirect URL matches your domain
  • Review authentication logs for specific errors

Debug Mode

Enable debug logging for troubleshooting:

log:
  level: debug
  encoding: json

Or via environment variable:

Terminal window
FLIPT_LOG_LEVEL=debug

Testing Configuration

Validate your configuration locally before deploying:

Terminal window
# Test configuration syntax
docker run --rm -v $(pwd)/config.yml:/etc/flipt/config/config.yml \
  docker.flipt.io/flipt/flipt:v2 validate --config /etc/flipt/config/config.yml


# Run locally to test
docker run --rm -p 8080:8080 \
  -v $(pwd)/config.yml:/etc/flipt/config/config.yml \
  docker.flipt.io/flipt/flipt:v2 --config /etc/flipt/config/config.yml

Production Best Practices

Configuration Management

  • Use environment variables for all secrets and credentials
  • Never commit authentication tokens, database passwords, or API keys to Git
  • Separate configurations for dev, staging, and production environments
  • Version control your configuration templates (without secrets)

Storage Strategy

  • Git-native for most teams: Provides version control, code review, and GitOps workflows
  • Database for rapid changes: Use when you need frequent flag updates outside Git workflows
  • Hybrid approach: Git for long-lived flags, database for short-lived experiments

Authentication and Authorization

  • Always enable authentication in production
  • Use OIDC for team-based access control
  • Rotate tokens regularly (set expiration dates)
  • Implement least privilege: Create read-only tokens for client applications

High Availability

  • Run multiple instances: Deploy multiple Flipt replicas behind a load balancer
  • Use external database: Avoid SQLite for multi-instance deployments
  • Enable caching: Reduce database load and improve performance
  • Monitor health checks: Set up alerting for instance failures

Monitoring and Alerting

  • Track evaluation latency: Alert on P99 latency above threshold
  • Monitor error rates: Set alerts for failed evaluations
  • Watch storage sync: Alert on Git repository sync failures
  • Resource utilization: Monitor CPU, memory, and database connections

Flag Management Hygiene

  • Document flags: Include clear descriptions and ownership information
  • Set expiration dates: Plan to remove temporary flags
  • Regular cleanup: Archive or delete unused flags
  • Naming conventions: Use consistent key naming (e.g., feature-name or experiment-name)
  • Change reviews: Implement PR/MR workflows for flag changes (Flipt Pro feature)

Performance Optimization

  • Enable caching: Reduces database queries and improves response time
  • Optimize rules: Keep segment and rule complexity reasonable
  • Client-side evaluation: For high-throughput applications, evaluate flags locally
  • Connection pooling: Configure appropriate database connection limits
  • Regional deployment: Deploy Flipt close to your application servers

Migration from Other Platforms

Migrating from LaunchDarkly

Export flags from LaunchDarkly and convert to Flipt format:

// LaunchDarkly flag
{
  "key": "new-feature",
  "on": true,
  "variations": [
    {"value": false},
    {"value": true}
  ]
}


// Flipt equivalent (features.yml)
flags:
  - key: new-feature
    name: New Feature
    enabled: true
    type: boolean

Migrating from Unleash

Flipt’s flag structure is similar to Unleash. Export your flags and adjust the YAML format:

# Unleash format
name: new-feature
type: release
enabled: true
strategies:
  - name: default


# Flipt equivalent
flags:
  - key: new-feature
    name: New Feature
    enabled: true
    type: boolean

Migrating from Split

Convert Split experiments to Flipt variant flags:

flags:
  - key: checkout-experiment
    name: Checkout Experiment
    type: variant
    enabled: true
    variants:
      - key: control
        name: Control
      - key: treatment
        name: Treatment


rules:
  - flag: checkout-experiment
    distributions:
      - variant: control
        rollout: 50
      - variant: treatment
        rollout: 50

Cost Optimization

Resource Sizing Recommendations

Flipt resource requirements (based on workload):

  • Small deployments (< 1M evaluations/day): 0.5 vCPU, 512MB RAM
  • Medium deployments (1-10M evaluations/day): 1 vCPU, 1GB RAM
  • Large deployments (10M+ evaluations/day): 2+ vCPU, 2GB+ RAM
  • Storage: 5GB persistent volume for SQLite; external database for high availability

Cost-Saving Strategies

  • Use Git-native storage: Eliminates database costs for flag storage
  • Client-side evaluation: Reduces server load and evaluation API calls
  • Efficient caching: Decreases database queries and improves performance
  • Regional deployment: Deploy Flipt in the same region as your applications
  • Self-hosting: One-time deployment cost vs. recurring SaaS per-seat fees

Advanced Features

Audit Logging

Track all flag changes with built-in audit logs:

audit:
  enabled: true
  sinks:
    - type: log
      log:
        encoding: json
    - type: webhook
      webhook:
        url: "https://your-logging-service.com/events"
        signing_secret: ${AUDIT_WEBHOOK_SECRET}

Percentage-Based Rollouts

Gradually roll out features to a percentage of users:

rules:
  - flag: new-checkout-flow
    distributions:
      - variant: enabled
        rollout: 25  # Enable for 25% of users
      - variant: disabled
        rollout: 75

User Segmentation

Create sophisticated targeting rules:

segments:
  - key: premium-us-users
    name: Premium US Users
    constraints:
      - type: string
        property: country
        operator: eq
        value: US
      - type: string
        property: subscription
        operator: eq
        value: premium
      - type: number
        property: account_age_days
        operator: gte
        value: 30


rules:
  - flag: premium-feature
    segment: premium-us-users
    distributions:
      - variant: enabled
        rollout: 100

A/B Testing

Configure experiments with distribution tracking:

flags:
  - key: checkout-button-color
    name: Checkout Button Color Experiment
    type: variant
    enabled: true
    variants:
      - key: blue
        name: Blue Button
        attachment: '{"color": "#0066CC"}'
      - key: green
        name: Green Button
        attachment: '{"color": "#00CC66"}'
      - key: red
        name: Red Button
        attachment: '{"color": "#CC0000"}'


rules:
  - flag: checkout-button-color
    distributions:
      - variant: blue
        rollout: 33
      - variant: green
        rollout: 33
      - variant: red
        rollout: 34

Getting Started Checklist

Before going to production with Flipt on Klutch.sh:

  • Choose storage backend (Git-native recommended)
  • Set up persistent volume (for SQLite) or external database
  • Configure authentication (token or OIDC)
  • Enable HTTPS in production (automatic with Klutch.sh)
  • Set up monitoring and health checks
  • Configure caching for performance
  • Document flag naming conventions
  • Establish flag lifecycle process (creation, rollout, removal)
  • Test flag evaluation in staging environment
  • Implement fallback logic in application code
  • Set up backup strategy for database storage
  • Configure appropriate log levels
  • Review and test disaster recovery procedures
  • Set up alerts for critical metrics
  • Document rollback procedures
  • Train team on Flipt workflows
  • Implement flag cleanup process

Resources

Conclusion

Deploying Flipt on Klutch.sh provides a powerful, cost-effective feature flag platform that integrates seamlessly with your Git workflows. By following this guide, you’ve set up a production-ready feature flag service with proper data persistence, authentication, and performance optimization. Your team can now safely deploy features behind flags, conduct A/B tests, and manage feature rollouts with confidence—all while maintaining full control of your infrastructure and avoiding the pricing traps of traditional SaaS feature flag platforms.