Skip to content

environment-variables.mdx

Latest commit

 

History

History
176 lines (130 loc) · 6.91 KB

environment-variables.mdx

File metadata and controls

176 lines (130 loc) · 6.91 KB
Raw
title Environment Variables
description Complete reference for all Quackback configuration options.
icon gear

Environment Variables

Complete reference for all Quackback configuration options. Copy .env.example to .env and fill in your values.

Required Variables

These variables must be set for Quackback to run.
Variable Description Example
DATABASE_URL PostgreSQL connection string postgresql://postgres:password@localhost:5432/quackback
SECRET_KEY Secret key for authentication and encryption (32+ chars). Used for session signing and deriving encryption keys. openssl rand -base64 32
BASE_URL Public URL for your instance (used for auth, emails, and OAuth callbacks) https://feedback.example.com
REDIS_URL Redis/Dragonfly connection for background job queue (BullMQ). Dragonfly is included in docker-compose. redis://localhost:6379

Email Configuration

Configure email delivery for OTP codes, notifications, and invitations.

If email is not configured, OTP codes and other emails are printed to the console. This is useful for local development.

Priority order: SMTP (if configured) > Resend (if configured) > Console logging.

SMTP

Variable Description Example
EMAIL_SMTP_HOST SMTP server hostname smtp.sendgrid.net
EMAIL_SMTP_PORT SMTP port 587
EMAIL_SMTP_USER SMTP username apikey
EMAIL_SMTP_PASS SMTP password SG.xxxx
EMAIL_SMTP_SECURE Use TLS (for port 465) true
EMAIL_FROM Sender email address Quackback <feedback@example.com>

Resend

Variable Description Example
EMAIL_RESEND_API_KEY Resend API key re_xxxxxxxxxxxx
EMAIL_FROM Sender email address Quackback <feedback@example.com>

OAuth Providers

Enable social login for portal users and team members.

GitHub

Variable Description
GITHUB_CLIENT_ID GitHub OAuth App client ID
GITHUB_CLIENT_SECRET GitHub OAuth App client secret

Create at: GitHub Developer Settings

Callback URL: https://your-domain.com/api/auth/callback/github

Google

Variable Description
GOOGLE_CLIENT_ID Google OAuth client ID
GOOGLE_CLIENT_SECRET Google OAuth client secret

Create at: Google Cloud Console

Callback URL: https://your-domain.com/api/auth/callback/google

Integration credentials (Slack, Microsoft Teams, Linear, etc.) are configured through the admin UI and stored securely in the database, not as environment variables.

AI

Enable AI features: post summaries, duplicate detection, feedback extraction, and help center semantic search. AI is off unless you set the key, the endpoint, and a model for each role -- Quackback works with any OpenAI-compatible endpoint but never assumes one.

Variable Description Example
OPENAI_API_KEY API key for your AI endpoint sk-...
OPENAI_BASE_URL OpenAI-compatible endpoint. Required -- there is no default https://api.openai.com/v1
AI_CHAT_MODEL Default model for chat features (summaries, suggestions, merge verification) gpt-4o-mini
AI_EMBEDDING_MODEL Model for embeddings (duplicate detection, semantic search) text-embedding-3-small
AI_SUMMARY_MODEL Per-feature override of AI_CHAT_MODEL for post summaries off
AI_SENTIMENT_MODEL Per-feature override for sentiment analysis gpt-4o-mini
AI_EXTRACTION_MODEL Per-feature override for suggestion extraction gpt-4o-mini
AI_QUALITY_GATE_MODEL Per-feature override for the suggestion quality gate gpt-4o-mini
AI_INTERPRETATION_MODEL Per-feature override for feedback interpretation gpt-4o-mini
AI_MERGE_MODEL Per-feature override for merge verification gpt-4o

Per-feature overrides fall back to AI_CHAT_MODEL when unset. Set an override to off to disable just that feature. Use model ids your endpoint accepts -- gateways typically want provider-prefixed ids like google/gemini-3.1-flash-lite-preview.

Before v0.12.0, `OPENAI_API_KEY` alone enabled AI with an implicit OpenAI endpoint and built-in model names. If you upgraded and AI features turned off, add `OPENAI_BASE_URL`, `AI_CHAT_MODEL`, and `AI_EMBEDDING_MODEL`.

File Storage

S3-compatible storage for image uploads in changelogs and rich text content. Supports AWS S3, Cloudflare R2, Backblaze B2, MinIO, and other S3-compatible services.

If not configured, image upload is disabled in the rich text editor. For local development, MinIO is included in `docker-compose` and configured by default. Run `bun run setup` to start it.
Variable Description Example
S3_ENDPOINT S3 endpoint URL (leave empty for AWS S3) http://localhost:9000
S3_BUCKET S3 bucket name quackback
S3_REGION S3 region us-east-1
S3_ACCESS_KEY_ID S3 access key minioadmin
S3_SECRET_ACCESS_KEY S3 secret key minioadmin
S3_FORCE_PATH_STYLE Use path-style URLs (required for MinIO, R2) true
S3_PUBLIC_URL Public URL for uploaded files (optional) https://cdn.example.com

Telemetry

Anonymous usage statistics help improve Quackback. Telemetry is enabled by default and can be disabled via environment variable.

Variable Description Example
DISABLE_TELEMETRY Set to "true" to disable anonymous usage statistics true

Complete Example

# ===================
# Required
# ===================
DATABASE_URL="postgresql://postgres:password@localhost:5432/quackback"
SECRET_KEY="your-32-character-minimum-secret-key-here"
BASE_URL="https://feedback.yourcompany.com"
REDIS_URL="redis://localhost:6379"

# ===================
# Email (choose one)
# ===================
# SMTP
EMAIL_SMTP_HOST="smtp.sendgrid.net"
EMAIL_SMTP_PORT="587"
EMAIL_SMTP_USER="apikey"
EMAIL_SMTP_PASS="SG.xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"
EMAIL_FROM="Quackback <feedback@yourcompany.com>"

# Or Resend
# EMAIL_RESEND_API_KEY="re_xxxxxxxxxxxx"
# EMAIL_FROM="Quackback <feedback@yourcompany.com>"

# ===================
# OAuth (optional)
# ===================
GITHUB_CLIENT_ID="your-github-client-id"
GITHUB_CLIENT_SECRET="your-github-client-secret"

GOOGLE_CLIENT_ID="your-google-client-id"
GOOGLE_CLIENT_SECRET="your-google-client-secret"

# ===================
# Telemetry (optional)
# ===================
# DISABLE_TELEMETRY="true"

Validation

Quackback validates required variables on startup. Missing variables will cause the application to fail with a clear error message indicating which variables are missing.