Environment Variables

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/databaseExample:

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/databaseExample:

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:

Go to https://github.com/settings/developers
Create a new OAuth app
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:

Go to https://console.cloud.google.com/apis/credentials
Create OAuth 2.0 credentials
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-keysExample:

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:[email protected]:5432/databuddy"
CLICKHOUSE_URL="http://default:[email protected]:8123/databuddy_analytics"
REDIS_URL="redis://:[email protected]: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

Never commit secrets to version control

Add .env to .gitignore:

.gitignore

.env
.env.local
.env.production

Use different secrets for each environment

Development, staging, and production should have completely different:

Database passwords
Auth secrets
API keys

Rotate secrets regularly

Update sensitive credentials periodically:

BETTER_AUTH_SECRET every 90 days
Database passwords every 180 days
API keys when team members leave

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

Get Started

Core Concepts

SDK Integration

Tracking

Features

Privacy & Compliance

Self-Hosting

Guides

Environment Variables

Database Configuration

PostgreSQL

ClickHouse

Redis

Application Configuration

Environment Mode

Application URLs

Authentication

Better Auth Secret

OAuth Providers

Email Configuration

Storage Configuration

AI Features (Optional)

External Integrations (Optional)

Domain Ranking

Background Jobs

Content Management

Logging Configuration (Optional)

Advanced Configuration

Security

Event Streaming (Optional)

Example Configuration Files

Development Environment

Production Environment

Environment Variable Validation

Security Best Practices

Next Steps

Database Setup

Configuration

Build docs developers (and LLMs) love

Get Started

Core Concepts

SDK Integration

Tracking

Features

Privacy & Compliance

Self-Hosting

Guides

​Database Configuration

​PostgreSQL

​ClickHouse

​Redis

​Application Configuration

​Environment Mode

​Application URLs

​Authentication

​Better Auth Secret

​OAuth Providers

​Email Configuration

​Storage Configuration

​AI Features (Optional)

​External Integrations (Optional)

​Domain Ranking

​Background Jobs

​Content Management

​Logging Configuration (Optional)

​Advanced Configuration

​Security

​Event Streaming (Optional)

​Example Configuration Files

​Development Environment

​Production Environment

​Environment Variable Validation

​Security Best Practices

​Next Steps

Database Setup

Configuration

Build docs developers (and LLMs) love

Database Configuration

PostgreSQL

ClickHouse

Redis

Application Configuration

Environment Mode

Application URLs

Authentication

Better Auth Secret

OAuth Providers

Email Configuration

Storage Configuration

AI Features (Optional)

External Integrations (Optional)

Domain Ranking

Background Jobs

Content Management

Logging Configuration (Optional)

Advanced Configuration

Security

Event Streaming (Optional)

Example Configuration Files

Development Environment

Production Environment

Environment Variable Validation

Security Best Practices

Next Steps