Skip to content

docs: .env.example lacks setup instructions for self-host required variables #649

Description

@sundaram2021

docker compose -f docker-compose.selfhost.yml up -d hard-requires 11 env vars
(IMAGE_TAG, POSTGRES_PASSWORD, CLICKHOUSE_PASSWORD, REDIS_PASSWORD,
DASHBOARD_URL, API_URL, BASKET_URL, BETTER_AUTH_SECRET,
DATABUDDY_ENCRYPTION_KEY, IP_HASH_SALT, AI_GATEWAY_API_KEY), but
.env.example doesn't explain how to obtain or generate most of them.

Self-hosters currently hit Set X in your environment errors one by one and
have to guess. Notably IP_HASH_SALT — leaving it empty falls back to a
public default salt in production, weakening IP anonymization.

Suggest adding a short comment per variable: an openssl rand command for the
secrets/passwords, console links + callback URLs for OAuth/Slack/Resend keys,
and the GHCR tags page for IMAGE_TAG.

before

CLICKHOUSE_URL="http://default:@localhost:8123/databuddy_analytics"
# Required by DQL. This must use the separately provisioned dql_user account;
# never point it at the application/admin ClickHouse credentials.
CLICKHOUSE_DQL_URL="http://dql_user:databuddy_dql_dev_password@localhost:8123/databuddy_analytics"
DATABASE_URL="postgres://databuddy:databuddy_dev_password@localhost:5432/databuddy"
REDIS_URL="redis://localhost:6379"
BULLMQ_REDIS_URL="redis://localhost:6379"

# Required only by docker-compose.selfhost.yml. Use URL-safe passwords and make
# the local database URLs above use the same credentials before initialization.
IMAGE_TAG=""
POSTGRES_PASSWORD=""
CLICKHOUSE_PASSWORD=""
REDIS_PASSWORD=""

# Public URLs. Local development uses built-in localhost defaults when blank.
DASHBOARD_URL=""
API_URL=""
BASKET_URL=""
LINKS_URL=""

# Baked into the dashboard browser bundle. Set these before production builds.
NEXT_PUBLIC_APP_URL=""
NEXT_PUBLIC_API_URL=""
NEXT_PUBLIC_BASKET_URL=""
NEXT_PUBLIC_LINKS_URL=""
NEXT_PUBLIC_STATUS_URL=""

AI_GATEWAY_API_KEY=""
FIRECRAWL_API_KEY=""
SUPERMEMORY_API_KEY=""

BETTER_AUTH_URL="http://localhost:3000"
# Required by docker-compose.selfhost.yml. Generate independent random values.
BETTER_AUTH_SECRET="generate-a-random-32-byte-base64-secret"
DATABUDDY_ENCRYPTION_KEY=""
IP_HASH_SALT=""

AUTUMN_SECRET_KEY=""

# Local dev default. Root build/start scripts force NODE_ENV=production.
NODE_ENV=development

GITHUB_CLIENT_ID=""
GITHUB_CLIENT_SECRET=""

GOOGLE_CLIENT_ID=""
GOOGLE_CLIENT_SECRET=""

RESEND_API_KEY=""
# Required when RESEND_API_KEY is set; use a domain verified in Resend.
EMAIL_FROM="Databuddy <no-reply@example.com>"
ALERTS_EMAIL_FROM="Databuddy <alerts@example.com>"
NEXT_PUBLIC_OPENAI_ADS_PIXEL_ID=""

# Slack bot / AI agent adapter
SLACK_APP_TOKEN=""
SLACK_SIGNING_SECRET=""
SLACK_CLIENT_ID=""
SLACK_CLIENT_SECRET=""
SLACK_REDIRECT_URI=""

# Not Necessary unless using blog
MARBLE_API_KEY=
MARBLE_WORKSPACE_KEY=
MARBLE_API_URL=https://api.marblecms.com/v1

# Not Necessary unless using changelog
NOTRA_API_KEY=

# Superlog OTLP logs export. When set, evlog drains in api/basket/insights/slack/uptime
# also ship wide events to https://intake.superlog.sh/v1/logs.
SUPERLOG_API_KEY=""

after

CLICKHOUSE_URL="http://default:@localhost:8123/databuddy_analytics"
# Required by DQL. This must use the separately provisioned dql_user account;
# never point it at the application/admin ClickHouse credentials.
CLICKHOUSE_DQL_URL="http://dql_user:databuddy_dql_dev_password@localhost:8123/databuddy_analytics"
DATABASE_URL="postgres://databuddy:databuddy_dev_password@localhost:5432/databuddy"
REDIS_URL="redis://localhost:6379"
BULLMQ_REDIS_URL="redis://localhost:6379"

# Required by docker-compose.selfhost.yml. Use URL-safe passwords and make
# the local database URLs above use the same credentials before initialization.
# Generate each password with: openssl rand -base64 24 | tr -d '/+='
# Release tags: https://github.com/databuddy-analytics/Databuddy/pkgs/container/databuddy-api
IMAGE_TAG=""
POSTGRES_PASSWORD=""
CLICKHOUSE_PASSWORD=""
REDIS_PASSWORD=""

# Public URLs. Local development uses built-in localhost defaults when blank.
DASHBOARD_URL=""
API_URL=""
BASKET_URL=""
LINKS_URL=""

# Baked into the dashboard browser bundle. Set these before production builds.
NEXT_PUBLIC_APP_URL=""
NEXT_PUBLIC_API_URL=""
NEXT_PUBLIC_BASKET_URL=""
NEXT_PUBLIC_LINKS_URL=""
NEXT_PUBLIC_STATUS_URL=""

# Vercel AI Gateway, required by the insights service: https://vercel.com/docs/ai-gateway
AI_GATEWAY_API_KEY=""
# Firecrawl — web scraping for insights
#   https://www.firecrawl.dev → API keys
FIRECRAWL_API_KEY=""

# Supermemory — long-term memory for insights
#   https://console.supermemory.ai
SUPERMEMORY_API_KEY=""

BETTER_AUTH_URL="http://localhost:3000"
# Required by docker-compose.selfhost.yml. Generate independent random values.
# Generate with: openssl rand -base64 32
BETTER_AUTH_SECRET=""
# Generate with: openssl rand -base64 32
DATABUDDY_ENCRYPTION_KEY=""
# Salts hashed visitor IPs. Never leave empty in production — the code falls
# back to a public default salt. Generate with: openssl rand -base64 24 | tr -d '/+='
IP_HASH_SALT=""

AUTUMN_SECRET_KEY=""

# Local dev default. Root build/start scripts force NODE_ENV=production.
NODE_ENV=development

# GitHub: https://github.com/settings/developers (callback: $BETTER_AUTH_URL/api/auth/callback/github)
GITHUB_CLIENT_ID=""
GITHUB_CLIENT_SECRET=""

# Google: https://console.cloud.google.com/apis/credentials (redirect: $BETTER_AUTH_URL/api/auth/callback/google)
GOOGLE_CLIENT_ID=""
GOOGLE_CLIENT_SECRET=""

# https://resend.com/api-keys
RESEND_API_KEY=""
# Required when RESEND_API_KEY is set; use a domain verified in Resend.
EMAIL_FROM="Databuddy <no-reply@example.com>"
ALERTS_EMAIL_FROM="Databuddy <alerts@example.com>"
NEXT_PUBLIC_OPENAI_ADS_PIXEL_ID=""

# Slack bot / AI agent adapter: https://api.slack.com/apps
SLACK_APP_TOKEN=""
SLACK_SIGNING_SECRET=""
SLACK_CLIENT_ID=""
SLACK_CLIENT_SECRET=""
SLACK_REDIRECT_URI=""

# Not Necessary unless using blog
MARBLE_API_KEY=
MARBLE_WORKSPACE_KEY=
MARBLE_API_URL=https://api.marblecms.com/v1

# Not Necessary unless using changelog
NOTRA_API_KEY=

# Superlog OTLP logs export. When set, evlog drains in api/basket/insights/slack/uptime
# also ship wide events to https://intake.superlog.sh/v1/logs.
SUPERLOG_API_KEY=""

Metadata

Metadata

Assignees

No one assigned

    Labels

    No labels
    No labels

    Type

    No type

    Projects

    No projects

    Milestone

    No milestone

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions