Configuration

Environment variables and settings for self-hosted Ballast.

Ballast is configured via environment variables. This reference covers all available settings.

Core Settings

VariableRequiredDefaultDescription
ENVIRONMENTNolocalEnvironment name (local, staging, production)
LOCAL_DEVELOPMENTNofalseEnable development mode (skips email verification)
AUTH_ENABLEDNotrueEnable authentication (disable for testing)

Database (PostgreSQL)

VariableRequiredDefaultDescription
POSTGRES_HOSTYes-PostgreSQL host
POSTGRES_PORTYes5432PostgreSQL port
POSTGRES_DBYesballastDatabase name
POSTGRES_USERYes-Database user
POSTGRES_PASSWORDYes-Database password
POSTGRES_SSLMODENodisableSSL mode (disable, require, verify-full)

Vector Database (Qdrant)

VariableRequiredDefaultDescription
QDRANT_HOSTYes-Qdrant host
QDRANT_PORTYes6334Qdrant gRPC port
QDRANT_API_KEYNo-Qdrant API key (if secured)
QDRANT_USE_TLSNofalseEnable TLS for Qdrant

Cache (Redis)

VariableRequiredDefaultDescription
REDIS_HOSTYes-Redis host
REDIS_PORTYes6379Redis port
REDIS_PASSWORDNo-Redis password

Background Jobs (Temporal)

VariableRequiredDefaultDescription
TEMPORAL_HOSTYes-Temporal server host
TEMPORAL_PORTYes7233Temporal server port
TEMPORAL_NAMESPACENodefaultTemporal namespace
TEMPORAL_TASK_QUEUENoballast-sync-queueTask queue name
TEMPORAL_ENABLEDNotrueEnable Temporal integration

Authentication

VariableRequiredDefaultDescription
JWT_SECRETYes-Secret for signing JWT tokens
ENCRYPTION_KEYYes-Key for encrypting credentials (32 bytes, base64)
STATE_SECRETYes-Secret for OAuth state tokens

AI Services

OpenAI (Required for embeddings)

VariableRequiredDefaultDescription
OPENAI_API_KEYYes-OpenAI API key

Anthropic (Optional, for AI features)

VariableRequiredDefaultDescription
ANTHROPIC_API_KEYNo-Anthropic API key

Cohere (Optional, for reranking)

VariableRequiredDefaultDescription
COHERE_API_KEYNo-Cohere API key

OAuth Providers

Configure OAuth credentials for each integration you want to enable:

Google Workspace

VariableRequiredDescription
GOOGLE_CLIENT_IDFor Google sourcesGoogle OAuth client ID
GOOGLE_CLIENT_SECRETFor Google sourcesGoogle OAuth client secret

Microsoft 365

VariableRequiredDescription
MICROSOFT_CLIENT_IDFor Microsoft sourcesAzure AD app client ID
MICROSOFT_CLIENT_SECRETFor Microsoft sourcesAzure AD app client secret

Slack

VariableRequiredDescription
SLACK_CLIENT_IDFor Slack sourceSlack app client ID
SLACK_CLIENT_SECRETFor Slack sourceSlack app client secret

GitHub

VariableRequiredDescription
GITHUB_CLIENT_IDFor GitHub sourceGitHub OAuth app client ID
GITHUB_CLIENT_SECRETFor GitHub sourceGitHub OAuth app client secret

Salesforce

VariableRequiredDescription
SALESFORCE_CLIENT_IDFor Salesforce sourceSalesforce connected app client ID
SALESFORCE_CLIENT_SECRETFor Salesforce sourceSalesforce connected app client secret

Notion

VariableRequiredDescription
NOTION_CLIENT_IDFor Notion sourceNotion integration client ID
NOTION_CLIENT_SECRETFor Notion sourceNotion integration client secret

Email (SMTP)

VariableRequiredDefaultDescription
SMTP_HOSTFor email-SMTP server host
SMTP_PORTFor email587SMTP server port
SMTP_USERFor email-SMTP username
SMTP_PASSWORDFor email-SMTP password
EMAIL_FROM_ADDRESSFor email-From email address
EMAIL_FROM_NAMENoBallastFrom display name

Alternative email provider:

VariableRequiredDescription
RESEND_API_KEYAlternative to SMTPResend API key

Billing (Optional)

VariableRequiredDescription
STRIPE_API_KEYFor billingStripe API key
STRIPE_WEBHOOK_SECRETFor billingStripe webhook signing secret

URLs

VariableRequiredDefaultDescription
FRONTEND_URLYes-Public URL for the web app
BACKEND_URLNoSame as FRONTEND_URLURL for API (if different)

Initial Admin

VariableRequiredDescription
SUPERUSER_EMAILRecommendedEmail for initial admin account
SUPERUSER_PASSWORDRecommendedPassword for initial admin account

Example Configuration

Minimal production configuration:

# Core
ENVIRONMENT=production
JWT_SECRET=your-secure-random-string-at-least-32-chars
ENCRYPTION_KEY=base64-encoded-32-byte-key
STATE_SECRET=another-secure-random-string

# Database
POSTGRES_HOST=your-postgres-host
POSTGRES_PORT=5432
POSTGRES_DB=ballast
POSTGRES_USER=ballast
POSTGRES_PASSWORD=secure-password
POSTGRES_SSLMODE=require

# Qdrant
QDRANT_HOST=your-qdrant-host
QDRANT_PORT=6334
QDRANT_USE_TLS=true
QDRANT_API_KEY=your-qdrant-api-key

# Redis
REDIS_HOST=your-redis-host
REDIS_PORT=6379
REDIS_PASSWORD=redis-password

# Temporal
TEMPORAL_HOST=your-temporal-host
TEMPORAL_PORT=7233

# AI
OPENAI_API_KEY=sk-...

# URLs
FRONTEND_URL=https://ballast.yourcompany.com

# Admin
SUPERUSER_EMAIL=admin@yourcompany.com
SUPERUSER_PASSWORD=secure-initial-password

Generating Secrets

Generate a secure JWT secret:

openssl rand -base64 32

Generate an encryption key:

openssl rand -base64 32

Generate a state secret:

openssl rand -hex 32