Environment Variables
AppFlowy uses environment variables for configuration. All settings are defined in the .env file.
Core Application Settings
The base URL where your AppFlowy instance is accessible.APPFLOWY_CLOUD_BASE_URL=https://appflowy.yourdomain.com
Must use HTTPS in production. HTTP is only acceptable for local development.
APPFLOWY_CLOUD_WS_BASE_URL
WebSocket URL for real-time collaboration features.APPFLOWY_CLOUD_WS_BASE_URL=wss://appflowy.yourdomain.com
Use wss:// (secure WebSocket) for production. Must match your base URL domain.
APPFLOWY_CLOUD_GOTRUE_URL
GoTrue authentication service URL.APPFLOWY_CLOUD_GOTRUE_URL=https://appflowy.yourdomain.com/gotrue
APPFLOWY_ENABLE_SYNC_TRACE
Enable detailed sync tracing for debugging collaboration issues.APPFLOWY_ENABLE_SYNC_TRACE=true
Enabling this will generate verbose logs. Use only for troubleshooting.
Database Configuration
AppFlowy requires PostgreSQL 14 or later.
PostgreSQL server hostname. Database name for AppFlowy. Database password.POSTGRES_PASSWORD=your_secure_password_here
Use a strong, randomly generated password. Never use default passwords in production.
Maximum number of database connections.POSTGRES_MAX_CONNECTIONS=100
Redis Configuration
Redis is used for caching, session management, and real-time presence.
Redis password (optional but recommended).REDIS_PASSWORD=your_redis_password
Storage Configuration
AppFlowy uses S3-compatible object storage for files and attachments.
MinIO
Self-hosted S3-compatible storage (recommended for self-hosting)
AWS S3
Amazon S3 for cloud-based deployments
Cloudflare R2
Cost-effective S3-compatible alternative
DigitalOcean Spaces
Another S3-compatible option
S3 service endpoint URL.# MinIO (Docker Compose)
S3_ENDPOINT=http://minio:9000
# AWS S3
S3_ENDPOINT=https://s3.us-east-1.amazonaws.com
# Cloudflare R2
S3_ENDPOINT=https://[account-id].r2.cloudflarestorage.com
S3 access key ID.S3_ACCESS_KEY_ID=your_access_key
S3 secret access key.S3_SECRET_ACCESS_KEY=your_secret_key
Keep this secret secure. Never commit to version control.
S3 bucket name for storing files.S3_BUCKET=appflowy-storage
S3_REGION
string
default:"us-east-1"
S3 region (for AWS S3 or compatible services). Use path-style URLs (required for MinIO). Authentication Configuration
AppFlowy uses GoTrue for authentication.
Secret key for JWT token signing.GOTRUE_JWT_SECRET=your_64_character_random_string
This is critical for security. Use a cryptographically random value.
The URL where GoTrue is accessible.GOTRUE_SITE_URL=https://appflowy.yourdomain.com
JWT token expiration time in seconds.GOTRUE_JWT_EXP=3600 # 1 hour
Disable public user registration.GOTRUE_DISABLE_SIGNUP=true
Set to true in private deployments where you want to control user creation.
GOTRUE_MAILER_AUTOCONFIRM
Skip email confirmation for new users.GOTRUE_MAILER_AUTOCONFIRM=true
Email Configuration
Configure SMTP for sending authentication emails.
SMTP password.SMTP_PASS=your_smtp_password
Email address for outgoing emails. AI Configuration (Optional)
Configure AI features if you want to enable them.
OpenAI API key for AI features. Enable or disable AI features. Maximum tokens for AI responses. Advanced Configuration
Resource Limits
Configure resource limits in docker-compose.yml:
services:
appflowy-server:
deploy:
resources:
limits:
cpus: '2'
memory: 4G
reservations:
cpus: '1'
memory: 2G
Database Connection Pooling
Optimize database performance:
# Maximum pool size
DB_POOL_MAX_SIZE=20
# Minimum pool size
DB_POOL_MIN_SIZE=5
# Connection timeout (seconds)
DB_POOL_TIMEOUT=30
Logging Configuration
Application log level.LOG_LEVEL=info # debug, info, warn, error
Log output format.LOG_FORMAT=json # json or text
Database
Redis
Application
Optimize PostgreSQL for AppFlowy:-- Adjust shared_buffers (25% of RAM)
shared_buffers = 4GB
-- Increase effective_cache_size (50% of RAM)
effective_cache_size = 8GB
-- Optimize work_mem
work_mem = 64MB
-- Increase maintenance_work_mem
maintenance_work_mem = 512MB
-- Enable query planning optimization
random_page_cost = 1.1
effective_io_concurrency = 200
postgresql.conf or via environment:services:
postgres:
command:
- postgres
- -c
- shared_buffers=4GB
- -c
- effective_cache_size=8GB
Optimize Redis configuration:# Maximum memory
REDIS_MAXMEMORY=2gb
# Eviction policy
REDIS_MAXMEMORY_POLICY=allkeys-lru
# Persistence
REDIS_SAVE="900 1 300 10 60 10000"
docker-compose.yml:services:
redis:
command: redis-server --maxmemory 2gb --maxmemory-policy allkeys-lru
Tune application performance:# Worker threads
WORKER_THREADS=8
# Request timeout (seconds)
REQUEST_TIMEOUT=30
# Max request body size (MB)
MAX_REQUEST_SIZE=100
# Enable compression
ENABLE_GZIP=true
Configuration Examples
Small Team Setup
Optimal for 5-20 users:
# Application
APPFLOWY_CLOUD_BASE_URL=https://appflowy.company.com
APPFLOWY_CLOUD_WS_BASE_URL=wss://appflowy.company.com
# Database
POSTGRES_HOST=postgres
POSTGRES_DB=appflowy
POSTGRES_MAX_CONNECTIONS=50
# Redis
REDIS_HOST=redis
REDIS_MAXMEMORY=1gb
# Storage (MinIO)
S3_ENDPOINT=http://minio:9000
S3_BUCKET=appflowy-storage
# Security
GOTRUE_DISABLE_SIGNUP=true
GOTRUE_MAILER_AUTOCONFIRM=false
Enterprise Setup
Optimal for 100+ users:
# Application
APPFLOWY_CLOUD_BASE_URL=https://appflowy.enterprise.com
APPFLOWY_CLOUD_WS_BASE_URL=wss://appflowy.enterprise.com
# Database (external)
POSTGRES_HOST=postgres.internal.company.com
POSTGRES_DB=appflowy_prod
POSTGRES_MAX_CONNECTIONS=200
DB_POOL_MAX_SIZE=50
# Redis (cluster)
REDIS_HOST=redis-cluster.internal.company.com
REDIS_MAXMEMORY=8gb
# Storage (AWS S3)
S3_ENDPOINT=https://s3.us-east-1.amazonaws.com
S3_BUCKET=company-appflowy-prod
S3_REGION=us-east-1
S3_USE_PATH_STYLE=false
# Security
GOTRUE_DISABLE_SIGNUP=true
GOTRUE_JWT_EXP=7200
# Performance
WORKER_THREADS=16
LOG_LEVEL=warn
Validating Configuration
Verify your configuration is correct:
Check environment variables
Test database connection
docker compose exec postgres pg_isready -U appflowy
Verify Redis connection
docker compose exec redis redis-cli ping
Test S3 connectivity
docker compose exec appflowy-server s3-test
Configuration Best Practices
Use Secrets Management
Store sensitive values in Docker secrets or a secrets manager like HashiCorp Vault.
Environment Separation
Maintain separate configurations for development, staging, and production.
Version Control
Track configuration changes (excluding secrets) in version control.
Regular Audits
Review and update configurations periodically.
Never commit .env files with real credentials to version control. Use .env.example as a template.
Next Steps
Security Guide
Secure your AppFlowy deployment
Monitoring & Logs
Set up monitoring and alerting
