Flagsmith Deployment & Usage Guide

1. Prerequisites

Before deploying Flagsmith, ensure you have the following installed:

Runtime & Tools:

Docker and Docker Compose (for containerized deployment)
Python 3.8+ (if running the Python API directly)
PostgreSQL 11+ (primary database)
Redis 5+ (for caching and task queue)

Optional for Development:

Node.js 16+ (for frontend development)
Git

Accounts (Optional):

Docker Hub account (for pulling official images)
AWS/GCP/Azure account (for cloud deployment)
LaunchDarkly account (if importing data from LaunchDarkly)

2. Installation

Quick Start with Docker Compose (Recommended)

The fastest way to get started is using Docker Compose:

# Download the docker-compose.yml file
curl -o docker-compose.yml https://raw.githubusercontent.com/Flagsmith/flagsmith/main/docker-compose.yml

# Start all services
docker-compose -f docker-compose.yml up

This will start:

PostgreSQL database
Redis cache
Flagsmith API server
Flagsmith frontend
Celery worker for background tasks

Manual Installation (Development)

For development or custom deployment:

# Clone the repository
git clone https://github.com/Flagsmith/flagsmith.git
cd flagsmith

# Install Python dependencies
pip install -r requirements.txt

# Install frontend dependencies
cd frontend
npm install

3. Configuration

Environment Variables

Create a .env file or set these environment variables:

Required Database Settings:

DATABASE_URL=postgres://flagsmith:password@localhost:5432/flagsmith
REDIS_URL=redis://localhost:6379/0

Optional Settings:

# Django settings
DJANGO_SECRET_KEY=your-secret-key-here
DEBUG=False  # Set to True for development
ALLOWED_HOSTS=localhost,127.0.0.1,yourdomain.com

# Email settings (for password resets)
EMAIL_HOST=smtp.gmail.com
EMAIL_PORT=587
EMAIL_HOST_USER=your-email@gmail.com
EMAIL_HOST_PASSWORD=your-password

# Feature flags
ENABLE_DANGEROUS_FEATURES=False

Initial Setup

When running for the first time, Flagsmith will:

Create a superuser with email admin@example.com
Create a default organization and project
Generate API keys for the default environment

Check the logs for the password reset link:

docker-compose logs api | grep "password-reset"

You'll see output like:

Superuser "admin@example.com" created successfully.
Please go to the following page and choose a password: http://localhost:8000/password-reset/confirm/.../...

4. Build & Run

Development Mode

Backend API:

cd api
python manage.py migrate
python manage.py runserver 0.0.0.0:8000

Frontend:

cd frontend
npm run dev

Celery Worker (for background tasks):

cd api
celery -A app worker -l info

Production Build with Docker

Build the Docker images:

# Build API image
docker build -t flagsmith/api -f docker/api/Dockerfile .

# Build frontend image
docker build -t flagsmith/frontend -f docker/frontend/Dockerfile .

Or use the pre-built images from Docker Hub:

docker pull flagsmith/flagsmith-api:latest
docker pull flagsmith/flagsmith-frontend:latest

Production Deployment with Docker Compose

Use the production docker-compose file:

curl -o docker-compose.prod.yml https://raw.githubusercontent.com/Flagsmith/flagsmith/main/docker-compose.prod.yml
docker-compose -f docker-compose.prod.yml up -d

5. Deployment

Platform Recommendations

For Self-Hosting:

Docker Swarm/Kubernetes: For scalable, production deployments
AWS ECS/EKS: Managed container orchestration
Google Cloud Run: Serverless container deployment
DigitalOcean App Platform: Simplified container deployment

Database Requirements:

PostgreSQL: Use managed services like AWS RDS, Google Cloud SQL, or Azure Database for PostgreSQL
Redis: Use managed services like AWS ElastiCache, Google Memorystore, or Redis Labs

Kubernetes Deployment

Example deployment manifest:

apiVersion: apps/v1
kind: Deployment
metadata:
  name: flagsmith-api
spec:
  replicas: 3
  selector:
    matchLabels:
      app: flagsmith-api
  template:
    metadata:
      labels:
        app: flagsmith-api
    spec:
      containers:
      - name: api
        image: flagsmith/flagsmith-api:latest
        env:
        - name: DATABASE_URL
          valueFrom:
            secretKeyRef:
              name: flagsmith-secrets
              key: database-url
        - name: REDIS_URL
          value: "redis://flagsmith-redis:6379/0"
        ports:
        - containerPort: 8000

Scaling Considerations

API Servers: Scale horizontally based on request volume
Celery Workers: Scale based on background task volume
Database: Use read replicas for high-traffic deployments
Cache: Use Redis cluster for distributed caching

6. Troubleshooting

Common Issues

Issue: Database connection errors

# Check if PostgreSQL is running
docker ps | grep postgres

# Test database connection
python manage.py dbshell

Solution: Ensure DATABASE_URL is correctly set and PostgreSQL is accessible.

Issue: Redis connection errors

# Check Redis connection
redis-cli ping

Solution: Verify REDIS_URL and ensure Redis is running.

Issue: "Superuser already exists" error

# Reset the database (development only)
python manage.py reset_db
python manage.py migrate

Issue: Frontend not connecting to API

# Check API is running
curl http://localhost:8000/api/v1/health/

Solution: Ensure the API_URL environment variable is set correctly in the frontend.

Issue: Feature flags not updating in real-time

# Check Celery worker is running
docker-compose ps | grep worker

# Check task queue
redis-cli -n 0 LLEN celery

Solution: Ensure Celery worker is running and connected to Redis.

Logs and Monitoring

View logs:

# Docker Compose logs
docker-compose logs -f api
docker-compose logs -f worker

# Kubernetes logs
kubectl logs deployment/flagsmith-api

Health checks:

# API health endpoint
curl http://localhost:8000/api/v1/health/

# Database health
python manage.py check --database default

Performance Issues

Database optimization:

-- Check for slow queries
SELECT query, calls, total_time, rows FROM pg_stat_statements ORDER BY total_time DESC LIMIT 10;

Cache issues:

# Clear Redis cache
redis-cli FLUSHALL

# Check cache stats
redis-cli INFO stats | grep keyspace_hits

Getting Help

Documentation: https://docs.flagsmith.com/
Discord Community: https://discord.com/invite/hFhxNtXzgm
GitHub Issues: https://github.com/Flagsmith/flagsmith/issues

For production issues, ensure you have:

Enabled proper logging (DEBUG=False in production)
Set up monitoring (Prometheus metrics available at /metrics)
Configured alerting for critical services
Regular database backups enabled

How to Deploy & Use flagsmith