Aller au contenu
1337skills 1337skills - Aide-mémoires

Flagsmith Cheat Sheet

Overview

Flagsmith is an open-source feature flag and remote configuration platform that gives teams full control over feature releases without redeploying code. It supports boolean flags, multivariate flags, remote configuration values, and user segmentation with complex targeting rules. Flagsmith can be self-hosted for complete data sovereignty or used as a managed cloud service, making it attractive to organizations with strict compliance requirements.

The platform provides SDKs for all major languages and frameworks, a REST API for programmatic management, and integrations with analytics platforms for measuring flag impact. Flagsmith’s architecture supports both server-side and client-side evaluation modes, with an edge proxy for high-performance deployments that need minimal latency. Its open-source core ensures transparency and extensibility while the enterprise tier adds audit logs, SAML SSO, and role-based access controls.

Installation

Self-Hosted via Docker

# Run Flagsmith with Docker Compose
git clone https://github.com/Flagsmith/flagsmith-docker.git
cd flagsmith-docker

# Start all services (API, frontend, PostgreSQL)
docker compose up -d

# Access dashboard at http://localhost:8000
# Create initial admin account through the UI

# Or run standalone with Docker
docker run -d \
  --name flagsmith \
  -p 8000:8000 \
  -e DATABASE_URL=postgresql://user:pass@db:5432/flagsmith \
  -e DJANGO_ALLOWED_HOSTS=* \
  flagsmith/flagsmith:latest

Kubernetes via Helm

# Add Flagsmith Helm repo
helm repo add flagsmith https://flagsmith.github.io/flagsmith-charts/
helm repo update

# Install Flagsmith
helm install flagsmith flagsmith/flagsmith \
  --namespace flagsmith \
  --create-namespace \
  --set postgresql.enabled=true \
  --set api.replicaCount=2 \
  --set frontend.replicaCount=2

# Verify installation
kubectl get pods -n flagsmith

SDK Installation

# Python
pip install flagsmith

# Node.js
npm install flagsmith-nodejs

# JavaScript (client-side)
npm install flagsmith

# Go
go get github.com/Flagsmith/flagsmith-go-client/v3

# Java
# Maven: com.flagsmith:flagsmith-java-client:7.0.0

# Ruby
gem install flagsmith

# .NET
dotnet add package Flagsmith

Core Commands — Flag Management

REST API

# Set API credentials
export FLAGSMITH_API="https://edge.api.flagsmith.com/api/v1"
export FLAGSMITH_TOKEN="your-api-token"
export FLAGSMITH_ENV_KEY="your-environment-key"

# List all feature flags
curl -s "$FLAGSMITH_API/features/" \
  -H "Authorization: Token $FLAGSMITH_TOKEN" | jq '.results[] | {id, name, type}'

# Create a boolean feature flag
curl -X POST "$FLAGSMITH_API/features/" \
  -H "Authorization: Token $FLAGSMITH_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "new_dashboard",
    "type": "FLAG",
    "description": "Enable the redesigned dashboard",
    "default_enabled": false,
    "tags": [1, 2],
    "is_server_key_only": false
  }'

# Create a remote config (key-value)
curl -X POST "$FLAGSMITH_API/features/" \
  -H "Authorization: Token $FLAGSMITH_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "max_upload_size_mb",
    "type": "CONFIG",
    "description": "Maximum file upload size in MB",
    "default_enabled": true,
    "initial_value": "50"
  }'

# Toggle flag in an environment
curl -X PATCH "$FLAGSMITH_API/environments/$FLAGSMITH_ENV_KEY/featurestates/FEATURE_STATE_ID/" \
  -H "Authorization: Token $FLAGSMITH_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"enabled": true}'

# Update remote config value
curl -X PATCH "$FLAGSMITH_API/environments/$FLAGSMITH_ENV_KEY/featurestates/FEATURE_STATE_ID/" \
  -H "Authorization: Token $FLAGSMITH_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"enabled": true, "feature_state_value": "100"}'

SDK Usage — Node.js

const Flagsmith = require('flagsmith-nodejs');

const flagsmith = new Flagsmith({
  environmentKey: 'your-server-environment-key',
});

await flagsmith.init();

// Get flags for an identity (user)
const flags = await flagsmith.getIdentityFlags('user-123', {
  plan: 'enterprise',
  region: 'us-east',
});

// Check if feature is enabled
const dashboardEnabled = flags.isFeatureEnabled('new_dashboard');

// Get remote config value
const maxUpload = flags.getFeatureValue('max_upload_size_mb');

// Get all flags for environment (no identity)
const envFlags = await flagsmith.getEnvironmentFlags();
console.log(envFlags.isFeatureEnabled('maintenance_mode'));

SDK Usage — Python

from flagsmith import Flagsmith

flagsmith = Flagsmith(
    environment_key="your-server-environment-key"
)

# Get flags for a user
flags = flagsmith.get_identity_flags(
    identifier="user-123",
    traits={"plan": "enterprise", "region": "us-east"}
)

# Check feature
if flags.is_feature_enabled("new_dashboard"):
    print("New dashboard enabled")

# Get config value
max_upload = flags.get_feature_value("max_upload_size_mb")
print(f"Max upload: {max_upload}MB")

# Environment-level flags (no user targeting)
env_flags = flagsmith.get_environment_flags()
maintenance = env_flags.is_feature_enabled("maintenance_mode")

Configuration

Segments (User Targeting)

# Create a segment
curl -X POST "$FLAGSMITH_API/projects/PROJECT_ID/segments/" \
  -H "Authorization: Token $FLAGSMITH_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Enterprise Users",
    "description": "Users on enterprise plan",
    "rules": [
      {
        "type": "ALL",
        "conditions": [
          {
            "property": "plan",
            "operator": "EQUAL",
            "value": "enterprise"
          }
        ],
        "rules": []
      }
    ]
  }'

# Create segment with multiple conditions
curl -X POST "$FLAGSMITH_API/projects/PROJECT_ID/segments/" \
  -H "Authorization: Token $FLAGSMITH_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "US Enterprise Beta",
    "rules": [
      {
        "type": "ALL",
        "conditions": [
          {"property": "plan", "operator": "EQUAL", "value": "enterprise"},
          {"property": "region", "operator": "EQUAL", "value": "us-east"},
          {"property": "beta_opt_in", "operator": "EQUAL", "value": "true"}
        ],
        "rules": []
      }
    ]
  }'

# Add segment override to a feature flag
curl -X POST "$FLAGSMITH_API/features/featurestates/FEATURE_STATE_ID/segmentoverrides/" \
  -H "Authorization: Token $FLAGSMITH_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "segment": SEGMENT_ID,
    "enabled": true,
    "feature_state_value": "premium",
    "priority": 1
  }'

Docker Compose Configuration

# docker-compose.yml
version: "3.8"
services:
  postgres:
    image: postgres:15
    environment:
      POSTGRES_DB: flagsmith
      POSTGRES_USER: flagsmith
      POSTGRES_PASSWORD: "${POSTGRES_PASSWORD}"
    volumes:
      - pgdata:/var/lib/postgresql/data

  flagsmith:
    image: flagsmith/flagsmith:latest
    ports:
      - "8000:8000"
    environment:
      DATABASE_URL: "postgresql://flagsmith:${POSTGRES_PASSWORD}@postgres:5432/flagsmith"
      DJANGO_ALLOWED_HOSTS: "*"
      ENABLE_ADMIN_ACCESS_USER_PASS: "true"
      FLAGSMITH_DOMAIN: "flags.company.com"
      SENTRY_SDK_DSN: "${SENTRY_DSN}"
      ENABLE_FLAGSMITH_REALTIME: "true"
      SSE_SERVER_BASE_URL: "https://realtime.flagsmith.com"
      CACHE_FLAGS_SECONDS: 60
    depends_on:
      - postgres

  edge-proxy:
    image: flagsmith/edge-proxy:latest
    ports:
      - "8063:8000"
    environment:
      FLAGSMITH_SERVER_URL: "http://flagsmith:8000/api/v1"
      FLAGSMITH_SERVER_KEY: "${SERVER_SIDE_KEY}"
      FLAGSMITH_POLLING_INTERVAL: 10

volumes:
  pgdata:

Helm Values

# flagsmith-values.yaml
api:
  replicaCount: 3
  resources:
    requests:
      memory: "512Mi"
      cpu: "250m"
    limits:
      memory: "1Gi"
      cpu: "500m"
  env:
    DJANGO_ALLOWED_HOSTS: "*"
    CACHE_FLAGS_SECONDS: "30"

frontend:
  replicaCount: 2

postgresql:
  enabled: true
  auth:
    postgresPassword: "secure-password"
    database: flagsmith

ingress:
  enabled: true
  className: nginx
  hosts:
    - host: flags.company.com
      paths:
        - path: /
          pathType: Prefix
  tls:
    - secretName: flagsmith-tls
      hosts:
        - flags.company.com

Advanced Usage

Percentage Rollout

# Set percentage rollout (multivariate)
curl -X POST "$FLAGSMITH_API/features/FEATURE_ID/mv-options/" \
  -H "Authorization: Token $FLAGSMITH_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "type": "unicode",
    "string_value": "variant-a",
    "default_percentage_allocation": 30
  }'

# Configure percentage split for a feature
curl -X PUT "$FLAGSMITH_API/environments/$FLAGSMITH_ENV_KEY/featurestates/FEATURE_STATE_ID/" \
  -H "Authorization: Token $FLAGSMITH_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "enabled": true,
    "multivariate_feature_state_values": [
      {"multivariate_feature_option": MV_OPTION_ID_1, "percentage_allocation": 20},
      {"multivariate_feature_option": MV_OPTION_ID_2, "percentage_allocation": 30}
    ]
  }'

Edge Proxy (High-Performance Local Evaluation)

# Run Edge Proxy
docker run -d \
  --name flagsmith-edge \
  -p 8063:8000 \
  -e FLAGSMITH_SERVER_URL="https://edge.api.flagsmith.com/api/v1" \
  -e FLAGSMITH_SERVER_KEY="ser.your-server-key" \
  -e FLAGSMITH_POLLING_INTERVAL=10 \
  flagsmith/edge-proxy:latest

# Point SDKs to edge proxy instead of cloud
# Node.js:
# const flagsmith = new Flagsmith({
#   environmentKey: 'your-key',
#   apiUrl: 'http://localhost:8063/api/v1',
# });

# Health check
curl http://localhost:8063/health

Webhooks and Integrations

# Create a webhook for flag changes
curl -X POST "$FLAGSMITH_API/environments/$FLAGSMITH_ENV_KEY/webhooks/" \
  -H "Authorization: Token $FLAGSMITH_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://hooks.slack.com/services/T00/B00/xxx",
    "enabled": true
  }'

# Webhook payload format:
# {
#   "event_type": "FLAG_UPDATED",
#   "data": {
#     "changed_by": "admin@company.com",
#     "new_state": {"enabled": true, "value": "..."},
#     "previous_state": {"enabled": false, "value": "..."},
#     "feature": {"name": "new_dashboard", "id": 123}
#   }
# }

Troubleshooting

IssueCauseSolution
Flags returning defaultsEnvironment key wrongVerify environment key matches target environment
Identity flags not matching segmentTraits not sent correctlyEnsure trait names/values match segment conditions
Self-hosted API slowDatabase not indexedRun Django migrations and check PostgreSQL indexes
Edge proxy stale flagsPolling interval too highReduce FLAGSMITH_POLLING_INTERVAL to 5-10 seconds
Webhook not firingURL unreachableVerify webhook URL is accessible from Flagsmith server
Multivariate not distributing evenlySmall sample sizePercentage allocation is probabilistic; needs significant traffic
Docker container crashingInsufficient memoryIncrease container memory limit to at least 512MB
CORS errors on client SDKAPI domain not allowedSet DJANGO_ALLOWED_HOSTS and configure CORS headers
# Check API health
curl http://localhost:8000/health

# Debug: list environments
curl -s "$FLAGSMITH_API/environments/" \
  -H "Authorization: Token $FLAGSMITH_TOKEN" | jq '.results[] | {id, name, api_key}'

# Debug: get all flags for a specific identity
curl -s "$FLAGSMITH_API/identities/?identifier=user-123" \
  -H "X-Environment-Key: $FLAGSMITH_ENV_KEY" | jq '.flags[] | {feature: .feature.name, enabled, value: .feature_state_value}'

# Check Docker logs
docker logs flagsmith --tail=50