Environment Variables

Configure FlagFlow using environment variables for different deployment scenarios

Overview

FlagFlow uses environment variables for configuration, making it easy to deploy across different environments. The application automatically loads .env files in development using @dotenvx/dotenvx and supports direct environment variable configuration in production.

Core Configuration

General Settings

Variable	Default	Description
LOGLEVEL	info	Logging level (debug, info, warn, error)
ENVIRONMENT	"" (empty)	Current environment (dev, staging, prod) displayed in the UI Visible in the migration file and used for environment-specific logic

etcd Configuration (Optional)

Configure the etcd key-value store connection. If these variables are not set, FlagFlow will use filesystem storage instead.

💡 Note: As of FlagFlow 1.5.0, etcd is optional due to the new PersistentService abstraction layer. Leave these variables unset to use filesystem storage, which is suitable for small companies and simple deployments. The dual-engine architecture provides seamless switching between storage types. See Filesystem Storage documentation for more details.

Variable	Default	Description
ETCD_SERVER	"" (empty)	etcd server endpoint If empty, FlagFlow uses filesystem storage. Set to "hostname:2379" to enable etcd.
ETCD_USERNAME	"" (empty)	etcd authentication username Only required when using etcd with authentication
ETCD_PASSWORD	"" (empty)	etcd authentication password Only required when using etcd with authentication
ETCD_NAMESPACE	default	etcd key namespace for data isolation Every FlagFlow instance should use a unique namespace in the same etcd cluster to avoid data collisions

Keycloak Authentication

Configure Keycloak for user authentication and authorization:

Variable	Default	Description
KEYCLOAK_HOST	-	Keycloak server URL If this value is set, FlagFlow will allow Keycloak for authentication. See authentication methods for details on configuring different authentication providers.
KEYCLOAK_REALM	master	Keycloak realm name
KEYCLOAK_CLIENT	flagflow-frontend	Keycloak client ID

Session Management

Configure user session behavior:

Variable	Default	Description
SESSION_USERS_ENABLED	true	Enable/disable user session management This allows in-built user management and session handling. When enabled, this provides the built-in authentication method as an alternative to external providers. See authentication methods for comparison of available options.
SESSION_DEFAULT_USERNAME	-	Default user username created at startup Only used when SESSION_USERS_ENABLED is true
SESSION_DEFAULT_PASSWORD	-	Default user password created at startup Only used when SESSION_USERS_ENABLED is true
SESSION_TIMEOUT_SEC	1800	Session timeout in seconds (30 minutes)

Metrics and Monitoring

Configure application metrics collection and audit logging:

Variable	Default	Description
METRICS_ENABLED	false	Enable Prometheus metrics collection and endpoint
AUDITLOG_ENABLED	false	Enable audit logging system with structured logging New in 1.5.0: Provides detailed audit trails for flag changes and user actions. See Audit Log documentation for complete setup and usage details.

Data Migration

Configure data migration from other FlagFlow instances:

Variable	Default	Description
MIGRATION_SOURCE_URL	"" (empty)	Source FlagFlow instance URL for remote migration This allows migrating data from another FlagFlow instance. See Migration documentation for setup.
MIGRATION_SOURCE_ENVIRONMENT	"" (empty)	Source environment name for migration See Migration documentation for remote migration setup

Development Settings

Development and debugging configuration:

Variable	Default	Description
DEV_RPC_SLOWDOWN_MS	-	Add artificial delay to RPC calls (development only!)

Configuration Examples

Development .env file

Create a .env file in your project root for local development:

Option 1: Filesystem Storage (Recommended for Development)

.env (Filesystem Storage)

# Core Configuration
LOGLEVEL=debug
ENVIRONMENT=development

# Storage: Use filesystem storage (no etcd required)
# ETCD_SERVER=  # Leave empty for filesystem storage

# Keycloak Authentication (optional)
# KEYCLOAK_HOST=https://your-keycloak.com
# KEYCLOAK_REALM=flagflow
# KEYCLOAK_CLIENT=flagflow-frontend

# Session Configuration
SESSION_USERS_ENABLED=true
SESSION_DEFAULT_USERNAME=admin
SESSION_DEFAULT_PASSWORD=dev_password
SESSION_TIMEOUT_SEC=3600

# Metrics and Logging
METRICS_ENABLED=true
AUDITLOG_ENABLED=true

# Development Settings
DEV_RPC_SLOWDOWN_MS=100

Option 2: etcd Storage (For Distributed Development)

.env (etcd Storage)

# Core Configuration
LOGLEVEL=debug
ENVIRONMENT=development

# etcd Configuration
ETCD_SERVER=localhost:2379
ETCD_USERNAME=root
ETCD_PASSWORD=your-etcd-password
ETCD_NAMESPACE=flagflow-dev

# Keycloak Authentication (optional)
# KEYCLOAK_HOST=https://your-keycloak.com
# KEYCLOAK_REALM=flagflow
# KEYCLOAK_CLIENT=flagflow-frontend

# Session Configuration
SESSION_USERS_ENABLED=true
SESSION_DEFAULT_USERNAME=admin
SESSION_DEFAULT_PASSWORD=dev_password
SESSION_TIMEOUT_SEC=3600

# Metrics and Logging
METRICS_ENABLED=true
AUDITLOG_ENABLED=true

# Development Settings
DEV_RPC_SLOWDOWN_MS=100

Production Environment Variables

For production deployment, choose your storage option:

Small Companies: Filesystem Storage

Production - Filesystem Storage

# Core Configuration
LOGLEVEL=info
ENVIRONMENT=production

# Storage: Filesystem (ensure /data volume is mounted!)
# ETCD_SERVER=  # Leave empty for filesystem storage

# Keycloak Authentication (optional)
KEYCLOAK_HOST=https://auth.yourcompany.com
KEYCLOAK_REALM=company
KEYCLOAK_CLIENT=flagflow

# Session Configuration
SESSION_USERS_ENABLED=true
SESSION_DEFAULT_USERNAME=admin
SESSION_DEFAULT_PASSWORD=secure-password-here
SESSION_TIMEOUT_SEC=1800

# Metrics and Audit
METRICS_ENABLED=true
AUDITLOG_ENABLED=true

Enterprise/Distributed: etcd Storage

Production - etcd Storage

# Core Configuration
LOGLEVEL=info
ENVIRONMENT=production

# etcd Configuration
ETCD_SERVER=etcd.production.internal:2379
ETCD_USERNAME=flagflow-prod
ETCD_PASSWORD=secure-password-here
ETCD_NAMESPACE=flagflow-prod

# Keycloak Authentication
KEYCLOAK_HOST=https://auth.yourcompany.com
KEYCLOAK_REALM=company
KEYCLOAK_CLIENT=flagflow

# Session Configuration
SESSION_USERS_ENABLED=true
SESSION_DEFAULT_USERNAME=admin
SESSION_DEFAULT_PASSWORD=secure-password-here
SESSION_TIMEOUT_SEC=1800

# Metrics and Audit
METRICS_ENABLED=true
AUDITLOG_ENABLED=true

Docker Environment Variables

Example for Docker Compose or Kubernetes deployment:

Filesystem Storage (remember to mount /data volume!)

docker-compose.yml - Filesystem Storage

environment:
  - LOGLEVEL=info
  - ENVIRONMENT=prod
  # No etcd configuration = filesystem storage
  - SESSION_USERS_ENABLED=true
  - SESSION_DEFAULT_USERNAME=admin
  - SESSION_DEFAULT_PASSWORD=secure-password
  - SESSION_TIMEOUT_SEC=1800
  - METRICS_ENABLED=true
  - AUDITLOG_ENABLED=true

etcd Storage

docker-compose.yml - etcd Storage

environment:
  - LOGLEVEL=info
  - ENVIRONMENT=prod
  - ETCD_SERVER=etcd:2379
  - ETCD_USERNAME=root
  - ETCD_PASSWORD=pw_flagflow
  - ETCD_NAMESPACE=flagflow
  - SESSION_USERS_ENABLED=true
  - SESSION_DEFAULT_USERNAME=admin
  - SESSION_DEFAULT_PASSWORD=secure-password
  - SESSION_TIMEOUT_SEC=1800
  - METRICS_ENABLED=true
  - AUDITLOG_ENABLED=true

Variable Validation

FlagFlow uses the env-var library for environment variable validation:

Required variables: Application will fail to start if missing
Type validation: Boolean, integer, and string validation
Default values: Sensible defaults for optional variables
Positive integers: Variables like SESSION_TIMEOUT_SEC must be positive

If a required variable is missing or invalid, you'll see a clear error message during startup:

Example validation error

EnvVarError: "ETCD_SERVER" is required
    at /app/node_modules/env-var/dist/env-var.js:142:23
    at EnvVar.required (/app/node_modules/env-var/dist/env-var.js:171:19)

Security Considerations

When working with environment variables containing sensitive data:

Use secrets management in production (Kubernetes Secrets, AWS Secrets Manager, etc.)
Rotate passwords regularly, especially etcd and Keycloak credentials
Use strong passwords for etcd authentication
Limit access to environment configuration in deployment systems

On this page