Skip to content

Configuration Reference

Complete reference for configuring Fluxbase via configuration file or environment variables.

Create fluxbase.yaml in your working directory:

# Server Configuration
server:
port: 8080
host: 0.0.0.0
read_timeout: 30s
write_timeout: 30s
idle_timeout: 120s
max_header_bytes: 1048576 # 1MB
# Database Configuration
database:
url: postgres://user:password@localhost:5432/fluxbase?sslmode=disable
max_connections: 100
idle_connections: 10
connection_lifetime: 60m
connection_timeout: 10s
# JWT Authentication
jwt:
secret: your-secret-key-change-this-in-production
access_token_expiry: 15m
refresh_token_expiry: 7d
issuer: fluxbase
audience: authenticated
# Storage Configuration
storage:
provider: local # "local" or "s3"
local_path: ./storage
max_upload_size: 10485760 # 10MB in bytes
# S3 Configuration (when provider: s3)
s3_endpoint: s3.amazonaws.com
s3_access_key: ""
s3_secret_key: ""
s3_region: us-east-1
s3_bucket: fluxbase
s3_use_ssl: true
# Realtime Configuration
realtime:
enabled: true
heartbeat_interval: 30s
max_connections: 1000
read_buffer_size: 1024
write_buffer_size: 1024
# Admin UI
admin:
enabled: true
path: /admin
# Logging
logging:
level: info # debug, info, warn, error
format: json # json or text
output: stdout # stdout, stderr, or file path
# CORS Configuration
cors:
enabled: true
allowed_origins:
- http://localhost:4000
- http://localhost:5173
allowed_methods:
- GET
- POST
- PUT
- PATCH
- DELETE
- OPTIONS
allowed_headers:
- Authorization
- Content-Type
- Accept
exposed_headers:
- Content-Range
- X-Content-Range
allow_credentials: true
max_age: 86400 # 24 hours
# Rate Limiting (Upcoming)
rate_limit:
enabled: false
requests_per_minute: 100
burst: 200
# TLS/HTTPS (Upcoming)
tls:
enabled: false
cert_file: /path/to/cert.pem
key_file: /path/to/key.pem
auto_cert: false # Let's Encrypt
auto_cert_domain: example.com

Environment variables take precedence over configuration file values.

VariableDescriptionDefaultExample
PORTHTTP server port80808080
HOSTHTTP server host0.0.0.00.0.0.0
SERVER_READ_TIMEOUTRead timeout30s30s
SERVER_WRITE_TIMEOUTWrite timeout30s30s
SERVER_IDLE_TIMEOUTIdle timeout120s120s
VariableDescriptionDefaultExample
FLUXBASE_DATABASE_HOSTPostgreSQL hostlocalhostlocalhost
FLUXBASE_DATABASE_PORTPostgreSQL port54325432
FLUXBASE_DATABASE_USERRuntime database userpostgresfluxbase
FLUXBASE_DATABASE_PASSWORDRuntime user passwordpostgresyour-password
FLUXBASE_DATABASE_DATABASEDatabase namefluxbasefluxbase
FLUXBASE_DATABASE_SSL_MODESSL modedisablerequire
FLUXBASE_DATABASE_MAX_CONNECTIONSMax connection pool size25100
FLUXBASE_DATABASE_MIN_CONNECTIONSMin connections in pool55
FLUXBASE_DATABASE_MAX_CONN_LIFETIMEConnection max lifetime1h1h
FLUXBASE_DATABASE_MAX_CONN_IDLE_TIMEConnection max idle time30m30m
FLUXBASE_DATABASE_HEALTH_CHECK_PERIODHealth check interval1m1m
FLUXBASE_DATABASE_ADMIN_USERAdmin user for migrations (defaults to USER)""postgres
FLUXBASE_DATABASE_ADMIN_PASSWORDAdmin user password (defaults to PASSWORD)""admin-password
FLUXBASE_DATABASE_USER_MIGRATIONS_PATHPath to user-provided migrations/migrations/user/app/migrations

SSL Modes:

  • disable - No SSL (development only)
  • allow - Prefer SSL if available
  • prefer - Use SSL if available (default for many clients)
  • require - Require SSL connection
  • verify-ca - Require SSL and verify CA certificate
  • verify-full - Require SSL and verify CA + hostname
VariableDescriptionDefaultExample
FLUXBASE_AUTH_JWT_SECRETJWT signing key (min 32 chars)(required)openssl rand -base64 32
FLUXBASE_AUTH_JWT_EXPIRYAccess token expiration15m15m, 1h
FLUXBASE_AUTH_REFRESH_EXPIRYRefresh token expiration168h (7 days)168h, 720h
FLUXBASE_AUTH_MAGIC_LINK_EXPIRYMagic link expiration15m15m
FLUXBASE_AUTH_PASSWORD_RESET_EXPIRYPassword reset expiration1h1h
FLUXBASE_AUTH_PASSWORD_MIN_LENGTHMinimum password length88
FLUXBASE_AUTH_BCRYPT_COSTBcrypt cost factor (4-31)1010
FLUXBASE_AUTH_SIGNUP_ENABLEDEnable user registrationtruetrue, false
FLUXBASE_AUTH_MAGIC_LINK_ENABLEDEnable magic link authtruetrue, false
FLUXBASE_AUTH_TOTP_ISSUER2FA TOTP issuer nameFluxbaseMyApp

OAuth/OIDC Providers:

VariableDescriptionDefaultExample
FLUXBASE_AUTH_GOOGLE_CLIENT_IDGoogle OAuth client ID""Your Google client ID
FLUXBASE_AUTH_APPLE_CLIENT_IDApple Sign In client ID""Your Apple Services ID
FLUXBASE_AUTH_MICROSOFT_CLIENT_IDMicrosoft/Azure AD client ID""Your Microsoft client ID

Security Best Practices:

  • Use a strong, random JWT secret (min 32 characters): openssl rand -base64 32
  • Rotate JWT secrets periodically
  • Use short access token expiry (15-30 minutes)
  • Use longer refresh token expiry (7-30 days)
VariableDescriptionDefaultExample
STORAGE_PROVIDERStorage backendlocallocal, s3
STORAGE_LOCAL_PATHLocal storage path./storage/var/lib/fluxbase/storage
STORAGE_MAX_UPLOAD_SIZEMax upload size (bytes)1048576010485760 (10MB)
STORAGE_S3_ENDPOINTS3 endpoints3.amazonaws.coms3.amazonaws.com
STORAGE_S3_ACCESS_KEYS3 access key-AKIAIOSFODNN7EXAMPLE
STORAGE_S3_SECRET_KEYS3 secret key-wJalrXUtnFEMI/K7MDENG/bPxRfiCYEXAMPLEKEY
STORAGE_S3_REGIONS3 regionus-east-1us-west-2
STORAGE_S3_BUCKETS3 bucket namefluxbasemy-bucket
STORAGE_S3_USE_SSLUse SSL for S3truetrue, false

S3-Compatible Services:

  • AWS S3
  • MinIO (local development): http://localhost:9000
  • DigitalOcean Spaces: https://nyc3.digitaloceanspaces.com
  • Wasabi: https://s3.wasabisys.com
  • Backblaze B2: https://s3.us-west-002.backblazeb2.com
VariableDescriptionDefaultExample
REALTIME_ENABLEDEnable realtimetruetrue, false
REALTIME_HEARTBEAT_INTERVALHeartbeat interval30s30s
REALTIME_MAX_CONNECTIONSMax WebSocket connections10001000
REALTIME_READ_BUFFER_SIZEWebSocket read buffer10241024
REALTIME_WRITE_BUFFER_SIZEWebSocket write buffer10241024
VariableDescriptionDefaultExample
ADMIN_ENABLEDEnable Admin UItruetrue, false
ADMIN_PATHAdmin UI path/admin/admin, /dashboard
VariableDescriptionDefaultExample
LOG_LEVELLog levelinfodebug, info, warn, error
LOG_FORMATLog formatjsonjson, text
LOG_OUTPUTLog outputstdoutstdout, stderr, /var/log/fluxbase.log
VariableDescriptionDefaultExample
CORS_ENABLEDEnable CORStruetrue, false
CORS_ALLOWED_ORIGINSAllowed origins (comma-separated)*http://localhost:3000,https://app.com
CORS_ALLOWED_METHODSAllowed HTTP methodsAllGET,POST,PUT,DELETE
CORS_ALLOW_CREDENTIALSAllow credentialstruetrue, false
CORS_MAX_AGEPreflight cache time (seconds)8640086400
VariableDescriptionDefaultExample
FLUXBASE_SECURITY_SETUP_TOKENToken for admin dashboard setup (required to enable dashboard)""openssl rand -base64 32
FLUXBASE_ENCRYPTION_KEYKey for AES-256-GCM encryption of sensitive data (OAuth tokens, client keys). Must be exactly 32 bytes.""openssl rand -base64 32 | head -c 32
FLUXBASE_SECURITY_ENABLE_GLOBAL_RATE_LIMITEnable global API rate limitingfalsetrue, false
FLUXBASE_SECURITY_ADMIN_SETUP_RATE_LIMITMax attempts for admin setup55
FLUXBASE_SECURITY_ADMIN_SETUP_RATE_WINDOWTime window for admin setup rate limit15m15m
FLUXBASE_SECURITY_AUTH_LOGIN_RATE_LIMITMax attempts for auth login1010
FLUXBASE_SECURITY_AUTH_LOGIN_RATE_WINDOWTime window for auth login rate limit1m1m
FLUXBASE_SECURITY_ADMIN_LOGIN_RATE_LIMITMax attempts for admin login1010
FLUXBASE_SECURITY_ADMIN_LOGIN_RATE_WINDOWTime window for admin login rate limit1m1m
VariableDescriptionDefaultExample
FLUXBASE_AI_ENABLEDEnable AI chatbot functionalitytruetrue, false
FLUXBASE_AI_CHATBOTS_DIRDirectory for chatbot definitions./chatbots./chatbots
FLUXBASE_AI_AUTO_LOAD_ON_BOOTLoad chatbots from filesystem at boottruetrue, false
FLUXBASE_AI_DEFAULT_MAX_TOKENSDefault max tokens per request40964096
FLUXBASE_AI_QUERY_TIMEOUTSQL query execution timeout30s30s
FLUXBASE_AI_MAX_ROWS_PER_QUERYMax rows returned per query10001000
FLUXBASE_AI_CONVERSATION_CACHE_TTLTTL for conversation cache30m1h
FLUXBASE_AI_MAX_CONVERSATION_TURNSMax turns per conversation5050

AI Provider Configuration:

VariableDescriptionDefaultExample
FLUXBASE_AI_PROVIDER_ENABLEDEnable config-based providerfalsetrue, false
FLUXBASE_AI_PROVIDER_TYPEProvider type""openai, azure, ollama
FLUXBASE_AI_PROVIDER_NAMEDisplay name for provider""Default Provider
FLUXBASE_AI_PROVIDER_MODELDefault model""gpt-4-turbo

OpenAI Settings:

VariableDescriptionDefaultExample
FLUXBASE_AI_OPENAI_API_KEYOpenAI API key""sk-...
FLUXBASE_AI_OPENAI_ORGANIZATION_IDOpenAI organization ID""org-...
FLUXBASE_AI_OPENAI_BASE_URLCustom base URL (for compatible APIs)""https://api.openai.com/v1

Azure OpenAI Settings:

VariableDescriptionDefaultExample
FLUXBASE_AI_AZURE_API_KEYAzure OpenAI API key""Your API key
FLUXBASE_AI_AZURE_ENDPOINTAzure OpenAI endpoint""https://your-resource.openai.azure.com
FLUXBASE_AI_AZURE_DEPLOYMENT_NAMEAzure deployment name""gpt-4-deployment
FLUXBASE_AI_AZURE_API_VERSIONAzure API version""2024-02-15-preview

Ollama Settings:

VariableDescriptionDefaultExample
FLUXBASE_AI_OLLAMA_ENDPOINTOllama endpoint""http://localhost:11434
FLUXBASE_AI_OLLAMA_MODELOllama model name""llama2, mistral
VariableDescriptionDefaultExample
FLUXBASE_RPC_ENABLEDEnable RPC functionalitytruetrue, false
FLUXBASE_RPC_PROCEDURES_DIRDirectory for RPC procedure definitions./rpc./rpc
FLUXBASE_RPC_AUTO_LOAD_ON_BOOTLoad procedures from filesystem at boottruetrue, false
FLUXBASE_RPC_DEFAULT_MAX_EXECUTION_TIMEDefault max execution time30s30s
FLUXBASE_RPC_MAX_MAX_EXECUTION_TIMEMaximum allowed execution time5m5m
FLUXBASE_RPC_DEFAULT_MAX_ROWSDefault max rows returned10001000
VariableDescriptionDefaultExample
FLUXBASE_JOBS_ENABLEDEnable background jobstruetrue, false
FLUXBASE_JOBS_DIRDirectory for job definitions./jobs./jobs
FLUXBASE_JOBS_AUTO_LOAD_ON_BOOTLoad jobs from filesystem at boottruetrue, false
FLUXBASE_JOBS_WORKER_MODEWorker modeembeddedembedded, standalone, disabled
FLUXBASE_JOBS_EMBEDDED_WORKER_COUNTNumber of embedded workers44
FLUXBASE_JOBS_MAX_CONCURRENT_PER_WORKERMax concurrent jobs per worker55
FLUXBASE_JOBS_MAX_CONCURRENT_PER_NAMESPACEMax concurrent jobs per namespace2020
FLUXBASE_JOBS_DEFAULT_MAX_DURATIONDefault job timeout5m5m
FLUXBASE_JOBS_MAX_MAX_DURATIONMaximum allowed job timeout1h1h
FLUXBASE_JOBS_DEFAULT_PROGRESS_TIMEOUTProgress reporting timeout5m5m
FLUXBASE_JOBS_POLL_INTERVALWorker poll interval1s1s
FLUXBASE_JOBS_WORKER_HEARTBEAT_INTERVALWorker heartbeat interval10s10s
FLUXBASE_JOBS_WORKER_TIMEOUTWorker considered dead after30s30s
VariableDescriptionDefaultExample
FLUXBASE_SCALING_BACKENDDistributed state backendlocallocal, postgres, redis
FLUXBASE_SCALING_REDIS_URLRedis/Dragonfly connection URL""redis://dragonfly:6379
FLUXBASE_SCALING_ENABLE_SCHEDULER_LEADER_ELECTIONEnable scheduler leader electionfalsetrue, false

Backend Options:

  • local - In-memory storage (single instance only, default)
  • postgres - Uses PostgreSQL for distributed state (no extra dependencies)
  • redis - Uses Redis-compatible backend (Dragonfly recommended for performance)

What’s Distributed:

FeatureDescription
Rate limitingShared counters across all instances
Realtime broadcastsCross-instance pub/sub for application events
Scheduler coordinationLeader election prevents duplicate cron jobs
Nonce validationPostgreSQL-backed for stateless auth flows

CLI Flags:

FlagDescription
--worker-onlyDisable API server, only run background job workers
--disable-schedulerDisable cron job scheduler on this instance
--disable-realtimeDisable realtime/WebSocket listener
--enable-leader-electionEnable PostgreSQL advisory lock leader election

Example Production Configuration:

Terminal window
# Multi-instance with PostgreSQL backend
FLUXBASE_SCALING_BACKEND=postgres
FLUXBASE_SCALING_ENABLE_SCHEDULER_LEADER_ELECTION=true
# Or with Redis/Dragonfly for high-scale (1000+ req/s)
FLUXBASE_SCALING_BACKEND=redis
FLUXBASE_SCALING_REDIS_URL=redis://:password@dragonfly:6379
FLUXBASE_SCALING_ENABLE_SCHEDULER_LEADER_ELECTION=true
VariableDescriptionDefaultExample
FLUXBASE_TRACING_ENABLEDEnable OpenTelemetry tracingfalsetrue, false
FLUXBASE_TRACING_ENDPOINTOTLP gRPC endpointlocalhost:4317jaeger:4317
FLUXBASE_TRACING_SERVICE_NAMEService name for tracesfluxbasefluxbase
FLUXBASE_TRACING_ENVIRONMENTEnvironment namedevelopmentproduction
FLUXBASE_TRACING_SAMPLE_RATESample rate (0.0-1.0)1.00.1 (10%)
FLUXBASE_TRACING_INSECUREUse insecure connectiontruefalse
VariableDescriptionDefaultExample
FLUXBASE_API_MAX_PAGE_SIZEMax rows per request (-1 = unlimited)10001000
FLUXBASE_API_MAX_TOTAL_RESULTSMax total retrievable rows (-1 = unlimited)1000010000
FLUXBASE_API_DEFAULT_PAGE_SIZEAuto-applied limit when not specified (-1 = no default)1000100
VariableDescriptionDefaultExample
TLS_ENABLEDEnable TLSfalsetrue, false
TLS_CERT_FILEPath to certificate-/etc/certs/tls.crt
TLS_KEY_FILEPath to private key-/etc/certs/tls.key
TLS_AUTO_CERTEnable Let’s Encryptfalsetrue, false
TLS_AUTO_CERT_DOMAINDomain for auto cert-example.com
server:
port: 443 # HTTPS
host: 0.0.0.0
read_timeout: 30s
write_timeout: 30s
database:
url: postgres://fluxbase:password@postgres:5432/fluxbase?sslmode=require
max_connections: 200
idle_connections: 20
connection_lifetime: 30m
jwt:
secret: ${JWT_SECRET} # From environment
access_token_expiry: 15m
refresh_token_expiry: 7d
storage:
provider: s3
max_upload_size: 52428800 # 50MB
s3_endpoint: s3.amazonaws.com
s3_access_key: ${S3_ACCESS_KEY}
s3_secret_key: ${S3_SECRET_KEY}
s3_region: us-east-1
s3_bucket: my-production-bucket
realtime:
enabled: true
heartbeat_interval: 30s
max_connections: 5000
admin:
enabled: false # Disable in production or protect behind VPN
logging:
level: info
format: json
output: /var/log/fluxbase/app.log
cors:
enabled: true
allowed_origins:
- https://app.example.com
- https://www.example.com
allow_credentials: true
rate_limit:
enabled: true
requests_per_minute: 1000
burst: 2000
tls:
enabled: true
auto_cert: true
auto_cert_domain: api.example.com
.env.production
DATABASE_URL=postgres://fluxbase:${DB_PASSWORD}@postgres:5432/fluxbase?sslmode=require
JWT_SECRET=${JWT_SECRET}
STORAGE_PROVIDER=s3
STORAGE_S3_ACCESS_KEY=${S3_ACCESS_KEY}
STORAGE_S3_SECRET_KEY=${S3_SECRET_KEY}
STORAGE_S3_BUCKET=production-bucket
LOG_LEVEL=info
LOG_FORMAT=json
CORS_ALLOWED_ORIGINS=https://app.example.com,https://www.example.com
RATE_LIMIT_ENABLED=true
RATE_LIMIT_REQUESTS_PER_MINUTE=1000
TLS_ENABLED=true
TLS_AUTO_CERT=true
TLS_AUTO_CERT_DOMAIN=api.example.com
server:
port: 8080
host: 127.0.0.1
database:
url: postgres://fluxbase:fluxbase@localhost:5432/fluxbase?sslmode=disable
max_connections: 20
idle_connections: 5
jwt:
secret: dev-secret-change-in-production
access_token_expiry: 24h # Longer for development
refresh_token_expiry: 30d
storage:
provider: local
local_path: ./storage
max_upload_size: 10485760 # 10MB
realtime:
enabled: true
max_connections: 100
admin:
enabled: true
path: /admin
logging:
level: debug
format: text
output: stdout
cors:
enabled: true
allowed_origins:
- http://localhost:3000
- http://localhost:5173
- http://127.0.0.1:3000
allow_credentials: true
rate_limit:
enabled: false # Disable in development
tls:
enabled: false # Use HTTP in development
version: "3.8"
services:
fluxbase:
image: ghcr.io/fluxbase-eu/fluxbase:latest
environment:
# Database
DATABASE_URL: postgres://fluxbase:password@postgres:5432/fluxbase?sslmode=disable
# JWT
JWT_SECRET: ${JWT_SECRET}
JWT_ACCESS_TOKEN_EXPIRY: 15m
JWT_REFRESH_TOKEN_EXPIRY: 7d
# Storage (MinIO)
STORAGE_PROVIDER: s3
STORAGE_S3_ENDPOINT: http://minio:9000
STORAGE_S3_ACCESS_KEY: minioadmin
STORAGE_S3_SECRET_KEY: minioadmin
STORAGE_S3_BUCKET: fluxbase
STORAGE_S3_USE_SSL: false
STORAGE_S3_REGION: us-east-1
# Realtime
REALTIME_ENABLED: true
REALTIME_MAX_CONNECTIONS: 1000
# Logging
LOG_LEVEL: info
LOG_FORMAT: json
# CORS
CORS_ALLOWED_ORIGINS: http://localhost:3000
ports:
- "8080:8080"
depends_on:
postgres:
condition: service_healthy
volumes:
- ./fluxbase.yaml:/app/fluxbase.yaml
postgres:
image: ghcr.io/fluxbase-eu/fluxbase-postgres:18
environment:
POSTGRES_DB: fluxbase
POSTGRES_USER: fluxbase
POSTGRES_PASSWORD: password
volumes:
- postgres_data:/var/lib/postgresql
healthcheck:
test: ["CMD-SHELL", "pg_isready -U fluxbase"]
interval: 5s
timeout: 5s
retries: 5
minio:
image: minio/minio:latest
command: server /data --console-address ":9001"
environment:
MINIO_ROOT_USER: minioadmin
MINIO_ROOT_PASSWORD: minioadmin
ports:
- "9000:9000"
- "9001:9001"
volumes:
- minio_data:/data
volumes:
postgres_data:
minio_data:

Helm chart configuration will be available in a future release.

Configuration is loaded in the following order (later sources override earlier ones):

  1. Default values (built-in)
  2. Configuration file (fluxbase.yaml)
  3. Environment variables
  4. Command-line flags (if applicable)

Fluxbase validates configuration on startup and will fail fast if:

  • Required values are missing (e.g., DATABASE_URL, JWT_SECRET)
  • Values are invalid (e.g., negative numbers, invalid formats)
  • Database connection fails
  • Storage backend is unreachable

Currently, Fluxbase does not support hot reloading of configuration. Restart the server after making configuration changes.

Never commit secrets to version control!

Use environment variables or secret management tools:

Terminal window
# Good: Load from environment
export JWT_SECRET=$(openssl rand -hex 32)
export DATABASE_URL="postgres://user:$(cat /run/secrets/db_password)@localhost/fluxbase"
# Bad: Hardcode in config file
jwt:
secret: my-secret-key # ❌ Don't do this!

Use a secrets management solution:

  • Kubernetes: Use Secrets and ConfigMaps
  • Docker Swarm: Use Docker Secrets
  • AWS: Use AWS Secrets Manager or Parameter Store
  • HashiCorp Vault: Enterprise secret management
  • Environment: Use .env files (not in git) with proper permissions
Terminal window
# Check if file exists
ls -la fluxbase.yaml
# Validate YAML syntax
yamllint fluxbase.yaml
# Check environment variables
env | grep FLUXBASE
Terminal window
# Test connection
psql "$DATABASE_URL"
# Check connection string format
echo $DATABASE_URL

If you see CORS errors in the browser:

  1. Check CORS_ALLOWED_ORIGINS includes your frontend URL
  2. Ensure CORS_ALLOW_CREDENTIALS is true if sending cookies
  3. Check browser console for specific CORS error