Configuration

Environment Variables

AppFlowy uses environment variables for configuration. All settings are defined in the .env file.

Core Application Settings

string

required

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.

string

required

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.

string

required

GoTrue authentication service URL.

APPFLOWY_CLOUD_GOTRUE_URL=https://appflowy.yourdomain.com/gotrue

boolean

default:"false"

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.

string

required

PostgreSQL server hostname.

POSTGRES_HOST=postgres

integer

default:"5432"

PostgreSQL server port.

POSTGRES_PORT=5432

string

required

Database name for AppFlowy.

POSTGRES_DB=appflowy

string

required

Database username.

POSTGRES_USER=appflowy

string

required

Database password.

POSTGRES_PASSWORD=your_secure_password_here

Use a strong, randomly generated password. Never use default passwords in production.

integer

default:"100"

Maximum number of database connections.

POSTGRES_MAX_CONNECTIONS=100

Redis Configuration

Redis is used for caching, session management, and real-time presence.

string

required

Redis server hostname.

REDIS_HOST=redis

integer

default:"6379"

Redis server port.

REDIS_PORT=6379

string

Redis password (optional but recommended).

REDIS_PASSWORD=your_redis_password

integer

default:"0"

Redis database number.

REDIS_DB=0

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

string

required

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

string

required

S3 access key ID.

S3_ACCESS_KEY_ID=your_access_key

string

required

S3 secret access key.

S3_SECRET_ACCESS_KEY=your_secret_key

Keep this secret secure. Never commit to version control.

string

required

S3 bucket name for storing files.

S3_BUCKET=appflowy-storage

string

default:"us-east-1"

S3 region (for AWS S3 or compatible services).

S3_REGION=us-east-1

boolean

default:"true"

Use path-style URLs (required for MinIO).

S3_USE_PATH_STYLE=true

Authentication Configuration

AppFlowy uses GoTrue for authentication.

string

required

Secret key for JWT token signing.

GOTRUE_JWT_SECRET=your_64_character_random_string

Generate with:

openssl rand -hex 32

This is critical for security. Use a cryptographically random value.

string

required

The URL where GoTrue is accessible.

GOTRUE_SITE_URL=https://appflowy.yourdomain.com

integer

default:"3600"

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.

boolean

default:"false"

Skip email confirmation for new users.

GOTRUE_MAILER_AUTOCONFIRM=true

Email Configuration

Configure SMTP for sending authentication emails.

string

SMTP server hostname.

SMTP_HOST=smtp.gmail.com

integer

default:"587"

SMTP server port.

SMTP_PORT=587

string

SMTP username.

SMTP_USER=noreply@yourdomain.com

string

SMTP password.

SMTP_PASS=your_smtp_password

string

Email address for outgoing emails.

SMTP_FROM_EMAIL=AppFlowy <noreply@yourdomain.com>

AI Configuration (Optional)

Configure AI features if you want to enable them.

string

OpenAI API key for AI features.

OPENAI_API_KEY=sk-...

string

default:"gpt-4"

AI model to use.

AI_MODEL=gpt-4-turbo

boolean

default:"false"

Enable or disable AI features.

AI_ENABLED=true

integer

default:"2000"

Maximum tokens for AI responses.

AI_MAX_TOKENS=2000

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

string

default:"info"

Application log level.

LOG_LEVEL=info  # debug, info, warn, error

string

default:"json"

Log output format.

LOG_FORMAT=json  # json or text

Performance Tuning

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

Apply in 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"

In 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

docker compose config

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.

Overview

Getting Started

Core Features

AI Features

Collaboration

Self-Hosting

Mobile

Advanced

Environment Variables

Core Application Settings

Database Configuration

Redis Configuration

Storage Configuration

MinIO

AWS S3

Cloudflare R2

DigitalOcean Spaces

Authentication Configuration

Email Configuration

AI Configuration (Optional)

Advanced Configuration

Resource Limits

Database Connection Pooling

Logging Configuration

Performance Tuning

Configuration Examples

Small Team Setup

Enterprise Setup

Validating Configuration

Configuration Best Practices

Use Secrets Management

Environment Separation

Version Control

Regular Audits

Next Steps

Security Guide

Monitoring & Logs

​Environment Variables

​Core Application Settings

​Database Configuration

​Redis Configuration

​Storage Configuration

MinIO

AWS S3

Cloudflare R2

DigitalOcean Spaces

​Authentication Configuration

​Email Configuration

​AI Configuration (Optional)

​Advanced Configuration

​Resource Limits

​Database Connection Pooling

​Logging Configuration

​Performance Tuning

​Configuration Examples

​Small Team Setup

​Enterprise Setup

​Validating Configuration

​Configuration Best Practices

Use Secrets Management

Environment Separation

Version Control

Regular Audits

​Next Steps

Security Guide

Monitoring & Logs

Environment Variables

Core Application Settings

Database Configuration

Redis Configuration

Storage Configuration

Authentication Configuration

Email Configuration

AI Configuration (Optional)

Advanced Configuration

Resource Limits

Database Connection Pooling

Logging Configuration

Performance Tuning

Configuration Examples

Small Team Setup

Enterprise Setup

Validating Configuration

Configuration Best Practices

Next Steps