Environment Variables

Complete reference of all environment variables for self-hosting Databuddy

Database Configuration

Core database connections required for Databuddy to function.

PostgreSQL

DATABASE_URL · string · required

PostgreSQL connection string for user data, configuration, and authentication.

Format: postgres://username:password@host:port/database

Example:

DATABASE_URL="postgres://databuddy:password@localhost:5432/databuddy"

ClickHouse

CLICKHOUSE_URL · string · required

ClickHouse connection string for analytics events and metrics.

Format: http://username:password@host:port/database

Example:

CLICKHOUSE_URL="http://default:@localhost:8123/databuddy_analytics"

Leave password empty if ClickHouse has no authentication configured.

Redis

REDIS_URL · string · required

Redis connection string for caching and session management.

Format: redis://[:password@]host:port[/database]

Examples:

# Without password
REDIS_URL="redis://localhost:6379"

# With password
REDIS_URL="redis://:mypassword@localhost:6379"

# With database number
REDIS_URL="redis://localhost:6379/0"

Application Configuration

Environment Mode

NODE_ENV · string · default: "development"

Runtime environment mode.

Options:

• development - Local development (enables debug logging, disables some integrations)
• production - Production deployment (JSON logs, all features enabled)
• test - Test environment

Example:

NODE_ENV=production

Application URLs

BETTER_AUTH_URL · string · required

Base URL where your Databuddy dashboard is hosted.

Used for:

• OAuth callback URLs
• Email verification links
• Password reset links

Examples:

# Development
BETTER_AUTH_URL="http://localhost:3000"

# Production
BETTER_AUTH_URL="https://analytics.yourcompany.com"

NEXT_PUBLIC_API_URL · string · required

API server URL accessible from the browser.

Note: The NEXT_PUBLIC_ prefix makes this available to client-side code.

Examples:

# Development
NEXT_PUBLIC_API_URL="http://localhost:3001"

# Production
NEXT_PUBLIC_API_URL="https://api.yourcompany.com"

Authentication

Better Auth Secret

BETTER_AUTH_SECRET · string · required

Secret key for signing JWTs and encrypting session data.

Generate a secure secret:

openssl rand -base64 32

Example:

BETTER_AUTH_SECRET="wSl7AHwHRxm6HVi0rSLcvFnn0SiZG+thg9IAF/vBkHs="

Keep this secret secure! If compromised, all sessions will be invalidated and you must generate a new one.

OAuth Providers

GITHUB_CLIENT_ID · string

GitHub OAuth application client ID.

Setup:

1. Go to https://github.com/settings/developers
2. Create a new OAuth app
3. Set callback URL to {BETTER_AUTH_URL}/api/auth/callback/github

Example:

GITHUB_CLIENT_ID="Iv1.a629723000000000"
GITHUB_CLIENT_SECRET="a0b1c2d3e4f5g6h7i8j9k0l1m2n3o4p5q6r7s8t9"

GITHUB_CLIENT_SECRET · string

GitHub OAuth application client secret.

Never commit this to version control. Use environment-specific configuration.

GOOGLE_CLIENT_ID · string

Google OAuth 2.0 client ID.

Setup:

1. Go to https://console.cloud.google.com/apis/credentials
2. Create OAuth 2.0 credentials
3. Add authorized redirect URI: {BETTER_AUTH_URL}/api/auth/callback/google

Example:

GOOGLE_CLIENT_ID="123456789-abc123def456.apps.googleusercontent.com"
GOOGLE_CLIENT_SECRET="GOCSPX-abc123def456ghi789"

GOOGLE_CLIENT_SECRET · string

Google OAuth 2.0 client secret.

Email Configuration

RESEND_API_KEY · string

Resend API key for sending transactional emails.

Used for:

• Email verification
• Password reset
• Team invitations
• Usage alerts

Get an API key: https://resend.com/api-keys

Example:

RESEND_API_KEY="re_123456789_AbCdEfGhIjKlMnOpQrStUvWxYz"

Email functionality is optional but highly recommended for production deployments.

Storage Configuration

R2_ACCESS_KEY_ID · string

Cloudflare R2 access key ID for storing organization images.

Example:

R2_ACCESS_KEY_ID="abc123def456ghi789jkl"
R2_SECRET_ACCESS_KEY="xyz789uvw456rst123opq"
R2_BUCKET="databuddy-uploads"
R2_ENDPOINT="https://1234567890abcdef.r2.cloudflarestorage.com"

Image uploads are optional. Organizations will function without custom images if not configured.

R2_SECRET_ACCESS_KEY · string

Cloudflare R2 secret access key.

R2_BUCKET · string

R2 bucket name for file storage.

R2_ENDPOINT · string

R2 endpoint URL for your account.

AI Features (Optional)

AI_API_KEY · string

OpenRouter API key for AI assistant features.

Used for:

• Analytics insights and recommendations
• Natural language queries
• Automated report generation

Get an API key: https://openrouter.ai/

Example:

AI_API_KEY="sk-or-v1-abc123def456ghi789jkl0mno1pqr2stu3vwx4yz"

AI features are entirely optional. Core analytics work without this configuration.

External Integrations (Optional)

Domain Ranking

OPR_API_KEY · string

OpenPageRank API key for domain authority metrics.

Get an API key: https://www.domcop.com/openpagerank/

Example:

OPR_API_KEY="abc123def456"

Not required for basic analytics operations.

Background Jobs

UPSTASH_QSTASH_TOKEN · string

Upstash QStash token for scheduled background jobs.

Used for:

• Scheduled reports
• Data exports
• Cleanup tasks

Example:

UPSTASH_QSTASH_TOKEN="eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..."

Content Management

MARBLE_WORKSPACE_KEY · string

Marble CMS workspace key for blog functionality.

Example:

MARBLE_WORKSPACE_KEY="ws_abc123def456"
MARBLE_API_URL="https://api.marblecms.com"

Only needed if using the built-in blog feature.

MARBLE_API_URL · string · default: "https://api.marblecms.com"

Marble CMS API endpoint.

Logging Configuration (Optional)

LOGTAIL_SOURCE_TOKEN · string

Logtail source token for centralized logging.

Example:

LOGTAIL_SOURCE_TOKEN="abc123def456ghi789"
LOGTAIL_ENDPOINT="https://in.logtail.com"

Logtail integration is automatically disabled when NODE_ENV=development.

LOGTAIL_ENDPOINT · string · default: "https://in.logtail.com"

Logtail ingestion endpoint.

Advanced Configuration

Security

AUTUMN_SECRET_KEY · string

Autumn.js secret key for request signing.

Example:

AUTUMN_SECRET_KEY="your-secret-key-here"

Disabled when NODE_ENV=development.

Event Streaming (Optional)

For high-scale deployments using Redpanda:

REDPANDA_ADVERTISED_HOST · string

Host/IP where Redpanda is accessible.

Example:

REDPANDA_ADVERTISED_HOST="redpanda.internal.company.com"
REDPANDA_LOG_LEVEL="warn"
REDPANDA_USER="databuddy"
REDPANDA_PASSWORD="secure-password"

REDPANDA_LOG_LEVEL · string · default: "warn"

Redpanda logging verbosity.

Options: error, warn, info, debug, trace

REDPANDA_USER · string

Redpanda SASL authentication username.

REDPANDA_PASSWORD · string

Redpanda SASL authentication password.

VECTOR_KAFKA_USER · string

Vector (data pipeline) Kafka username for Redpanda integration.

VECTOR_KAFKA_PASSWORD · string

Vector Kafka password.

Example Configuration Files

Development Environment

.env.development

# Databases
DATABASE_URL="postgres://databuddy:databuddy_dev_password@localhost:5432/databuddy"
CLICKHOUSE_URL="http://default:@localhost:8123/databuddy_analytics"
REDIS_URL="redis://localhost:6379"

# Application
NODE_ENV=development
BETTER_AUTH_URL="http://localhost:3000"
NEXT_PUBLIC_API_URL="http://localhost:3001"

# Auth (generate with: openssl rand -base64 32)
BETTER_AUTH_SECRET="wSl7AHwHRxm6HVi0rSLcvFnn0SiZG+thg9IAF/vBkHs="

# Optional: OAuth
GITHUB_CLIENT_ID=""
GITHUB_CLIENT_SECRET=""
GOOGLE_CLIENT_ID=""
GOOGLE_CLIENT_SECRET=""

# Optional: Email
RESEND_API_KEY=""

# Optional: AI
AI_API_KEY=""

Production Environment

.env.production

# Databases
DATABASE_URL="postgres://databuddy:[e-mail]:5432/databuddy"
CLICKHOUSE_URL="http://default:[e-mail]:8123/databuddy_analytics"
REDIS_URL="redis://:[e-mail]:6379"

# Application
NODE_ENV=production
BETTER_AUTH_URL="https://analytics.yourcompany.com"
NEXT_PUBLIC_API_URL="https://api.analytics.yourcompany.com"

# Auth (MUST be different from dev!)
BETTER_AUTH_SECRET="GENERATE_NEW_SECRET_FOR_PRODUCTION"

# OAuth
GITHUB_CLIENT_ID="Iv1.your_production_client_id"
GITHUB_CLIENT_SECRET="your_production_client_secret"
GOOGLE_CLIENT_ID="your-production-id.apps.googleusercontent.com"
GOOGLE_CLIENT_SECRET="your_production_secret"

# Email (required for production)
RESEND_API_KEY="re_your_production_api_key"

# Storage
R2_ACCESS_KEY_ID="your_r2_access_key"
R2_SECRET_ACCESS_KEY="your_r2_secret"
R2_BUCKET="databuddy-prod-uploads"
R2_ENDPOINT="https://your-account.r2.cloudflarestorage.com"

# Logging
LOGTAIL_SOURCE_TOKEN="your_logtail_token"

# Security
AUTUMN_SECRET_KEY="your_autumn_secret"

Environment Variable Validation

Databuddy validates required environment variables on startup. Missing required variables will prevent the application from starting with clear error messages.

Required variables:

• DATABASE_URL
• CLICKHOUSE_URL
• REDIS_URL
• BETTER_AUTH_URL
• BETTER_AUTH_SECRET
• NEXT_PUBLIC_API_URL

Recommended for production:

• RESEND_API_KEY
• GITHUB_CLIENT_ID + GITHUB_CLIENT_SECRET (or Google OAuth)
• R2_* variables for image uploads

Security Best Practices

1. Never commit secrets to version control

   Add .env to .gitignore:

   .gitignore

   .env
   .env.local
   .env.production
   
2. Use different secrets for each environment

   Development, staging, and production should have completely different:

   • Database passwords
   • Auth secrets
   • API keys
3. Rotate secrets regularly

   Update sensitive credentials periodically:

   • BETTER_AUTH_SECRET every 90 days
   • Database passwords every 180 days
   • API keys when team members leave
4. Use secrets management in production

   Consider using:

   • AWS Secrets Manager
   • HashiCorp Vault
   • Google Secret Manager
   • Kubernetes Secrets

Next Steps

Database Setup

Initialize PostgreSQL and ClickHouse

Configuration

Advanced configuration and tuning