Self-Hosting

Flipswitch is designed to be self-hosted on your own infrastructure. This guide covers deployment options and configuration.

Requirements

Java 21+ - For running the backend server
PostgreSQL 14+ - Primary database
Redis (optional) - For distributed caching in multi-instance deployments

Quick Start with Docker

# Clone the repository
git clone https://github.com/flipswitch-io/flipswitch.git
cd flipswitch
 
# Start PostgreSQL
docker run -d \
  --name flipswitch-postgres \
  -e POSTGRES_USER=flipswitch \
  -e POSTGRES_PASSWORD=flipswitch \
  -e POSTGRES_DB=flipswitch \
  -p 5432:5432 \
  postgres:16
 
# Run the server
sbt admin-server/run

The server will be available at http://localhost:8080.

Configuration

Configure Flipswitch using environment variables:

Database

Variable	Default	Description
`DB_URL`	`jdbc:postgresql://localhost:5432/flipswitch`	PostgreSQL JDBC URL
`DB_USERNAME`	`flipswitch`	Database username
`DB_PASSWORD`	`flipswitch`	Database password

Server

Variable	Default	Description
`BIND_HOST`	`0.0.0.0`	Server bind host
`BIND_PORT`	`8080`	Server bind port
`CORS_ORIGINS`	`*`	Allowed CORS origins (comma-separated)

Authentication

Flipswitch supports multiple authentication modes:

# Password-based authentication (default for self-hosted)
AUTH_MODE=password

Users are stored in the database with bcrypt-hashed passwords.

Redis (Optional)

For multi-instance deployments with distributed caching:

Variable	Default	Description
`REDIS_URL`	(disabled)	Redis connection URL
`REDIS_PASSWORD`	(none)	Redis password

REDIS_URL=redis://localhost:6379

Docker Compose

Create a docker-compose.yml for a complete setup:

version: '3.8'
 
services:
  postgres:
    image: postgres:16
    environment:
      POSTGRES_USER: flipswitch
      POSTGRES_PASSWORD: flipswitch
      POSTGRES_DB: flipswitch
    volumes:
      - postgres_data:/var/lib/postgresql/data
    healthcheck:
      test: ["CMD-SHELL", "pg_isready -U flipswitch"]
      interval: 5s
      timeout: 5s
      retries: 5
 
  flipswitch:
    image: ghcr.io/flipswitch-io/flipswitch:latest
    environment:
      DB_URL: jdbc:postgresql://postgres:5432/flipswitch
      DB_USERNAME: flipswitch
      DB_PASSWORD: flipswitch
      BIND_PORT: 8080
    ports:
      - "8080:8080"
    depends_on:
      postgres:
        condition: service_healthy
 
volumes:
  postgres_data:

Kubernetes

Example Kubernetes deployment:

apiVersion: apps/v1
kind: Deployment
metadata:
  name: flipswitch
spec:
  replicas: 2
  selector:
    matchLabels:
      app: flipswitch
  template:
    metadata:
      labels:
        app: flipswitch
    spec:
      containers:
        - name: flipswitch
          image: ghcr.io/flipswitch-io/flipswitch:latest
          ports:
            - containerPort: 8080
          env:
            - name: DB_URL
              valueFrom:
                secretKeyRef:
                  name: flipswitch-secrets
                  key: db-url
            - name: DB_USERNAME
              valueFrom:
                secretKeyRef:
                  name: flipswitch-secrets
                  key: db-username
            - name: DB_PASSWORD
              valueFrom:
                secretKeyRef:
                  name: flipswitch-secrets
                  key: db-password
            - name: REDIS_URL
              value: redis://redis-service:6379
          readinessProbe:
            httpGet:
              path: /health
              port: 8080
            initialDelaySeconds: 10
            periodSeconds: 5
          livenessProbe:
            httpGet:
              path: /health
              port: 8080
            initialDelaySeconds: 30
            periodSeconds: 10

Database Migrations

Flipswitch automatically runs database migrations on startup using Flyway. No manual migration steps are required.

Ensure your database user has CREATE TABLE permissions for the initial setup.

High Availability

For production deployments, consider:

1. Multiple Instances

Run multiple Flipswitch instances behind a load balancer:

Use Redis for distributed caching
Ensure sticky sessions are NOT required (stateless design)
SSE connections are per-instance

2. Database Replication

Set up PostgreSQL with:

Primary for writes
Read replicas for flag evaluations
Connection pooling (PgBouncer)

3. Redis Cluster

For high-traffic deployments:

REDIS_URL=redis://redis-cluster:6379
REDIS_MODE=cluster

Monitoring

Prometheus Metrics

Flipswitch exposes Prometheus metrics at /metrics:

# Flag evaluations
flipswitch_flag_evaluations_total{flag="dark-mode",variant="enabled"}

# Cache hits/misses
flipswitch_cache_hits_total
flipswitch_cache_misses_total

# SSE connections
flipswitch_sse_connections_active

Health Checks

Endpoint	Description
`/health`	Basic health check
`/health/ready`	Readiness (database connected)
`/health/live`	Liveness (server running)

Security

API Key Management

Generate separate API keys per environment
Rotate keys regularly
Use server keys only on backend services

Network Security

Use TLS/HTTPS in production
Restrict database access to Flipswitch servers
Use private networking for Redis

CORS Configuration

# Allow specific origins
CORS_ORIGINS=https://app.example.com,https://admin.example.com

Backup & Recovery

Database Backups

# Backup
pg_dump -U flipswitch flipswitch > backup.sql
 
# Restore
psql -U flipswitch flipswitch < backup.sql

Point-in-Time Recovery

Configure PostgreSQL WAL archiving for point-in-time recovery capabilities.

Troubleshooting

Connection Refused

Check that PostgreSQL is running and accessible:

psql -h localhost -U flipswitch -d flipswitch

Migrations Failed

Check the Flyway migration history:

SELECT * FROM flyway_schema_history ORDER BY installed_rank DESC LIMIT 10;

SSE Not Working

Verify that your proxy/load balancer supports long-lived connections and has appropriate timeout settings.

Self-Hosting

On this page