Environment Variables

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

Required Variables

Warning: 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.

Tip: 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 <[email protected]>`

Resend

Variable	Description	Example
`EMAIL_RESEND_API_KEY`	Resend API key	`re_xxxxxxxxxxxx`
`EMAIL_FROM`	Sender email address	`Quackback <[email protected]>`

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

Note: 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.

Note: 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.

Note: 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 <[email protected]>"

# Or Resend
# EMAIL_RESEND_API_KEY="re_xxxxxxxxxxxx"
# EMAIL_FROM="Quackback <[email protected]>"

# ===================
# 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

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