.env.example

# ============================================================================
# Quackback Environment Configuration
# ============================================================================
# Copy this file to .env and fill in your values.
# For self-hosted deployments, only the "Required" section needs configuration.
#
# IMPORTANT — do NOT wrap values in quotes, and do not put inline comments on a
# value line. Docker's `--env-file` / Compose `env_file` reads the entire text
# after `=` literally: it does NOT strip quotes or trailing `# comments`. So a
# quoted DATABASE_URL="postgresql://..." is passed with the quotes attached and
# fails with `ERR_INVALID_URL`. Plain `KEY=value` works everywhere (Docker
# --env-file, Compose, and Bun's dotenv loader).

# ============================================================================
# Required
# ============================================================================

# PostgreSQL connection string
DATABASE_URL=postgresql://postgres:password@localhost:5432/quackback

# Public URL for your Quackback instance (used for auth, emails, OAuth callbacks)
BASE_URL=http://localhost:3000

# Port for the application server
PORT=3000

# Secret key for authentication and encryption - MUST be at least 32 characters
# This single key is used for session signing and deriving encryption keys.
# Generate with: openssl rand -base64 32
SECRET_KEY=

# Redis/Dragonfly connection for background job queue (BullMQ)
# Dragonfly is included in docker-compose and started by `bun run setup`.
REDIS_URL=redis://localhost:6379

# ============================================================================
# Email (optional)
# ============================================================================
# If not configured, emails are logged to console (useful for development).
# Priority: SMTP (if configured) → Resend (if configured) → Console logging
#
# Option 1: SMTP (recommended for self-hosted, works with any provider)
#   - Gmail: smtp.gmail.com (port 587, use app password)
#   - Amazon SES: email-smtp.{region}.amazonaws.com
#   - Mailgun: smtp.mailgun.org
#   - SendGrid: smtp.sendgrid.net

EMAIL_SMTP_HOST=
EMAIL_SMTP_PORT=587
EMAIL_SMTP_USER=
EMAIL_SMTP_PASS=
# Uncomment for port 465 (implicit TLS):
# EMAIL_SMTP_SECURE=true

# Option 2: Resend API (simpler setup, requires Resend account)
# Get your API key at: https://resend.com/api-keys

EMAIL_RESEND_API_KEY=

# Sender address (REQUIRED when using SMTP or Resend)
# Format (no quotes): Your App <noreply@yourdomain.com>
EMAIL_FROM=

# ============================================================================
# Inbound email (optional) — live-chat email channel
# ============================================================================
# Lets visitors reply to an agent's email and have it thread back into their
# live-chat conversation. Both must be set to switch the channel on; until then
# the inbound webhook 404s and agent-reply emails carry no routable Reply-To.
#   - EMAIL_INBOUND_DOMAIN: the receiving domain (e.g. a Resend inbound domain).
#     Agent replies use reply+<conversationId>@<domain>.
#   - EMAIL_INBOUND_SIGNING_SECRET: the provider's webhook signing secret
#     (Svix "whsec_..."). Point the provider's inbound webhook at
#     <BASE_URL>/api/chat/email/inbound.
EMAIL_INBOUND_DOMAIN=
EMAIL_INBOUND_SIGNING_SECRET=

# ============================================================================
# AI (optional)
# ============================================================================
# Enable AI features like auto-categorization and summarization.

# AI (optional). All AI features are OFF unless configured below.
# Quackback talks to any OpenAI-compatible endpoint. You must set BOTH a key
# and an explicit base URL — there is no implicit provider default.
OPENAI_API_KEY=
# Endpoint examples:
#   Direct OpenAI:        https://api.openai.com/v1
#   OpenRouter:           https://openrouter.ai/api/v1
#   Cloudflare AI Gateway: https://gateway.ai.cloudflare.com/v1/<account>/<gateway>/openai
OPENAI_BASE_URL=

# Models. A feature is enabled only when its model resolves to a value.
# Two roles cover everything; per-feature overrides are optional.
#   - Chat features: summary, sentiment, extraction, quality gate, interpretation, merge
#   - Embedding features: duplicate detection, help-center semantic search
# Use model ids your endpoint accepts (direct OpenAI: e.g. gpt-4o-mini,
# text-embedding-3-small; a gateway: e.g. google/gemini-3.1-flash-lite-preview).
AI_CHAT_MODEL=
AI_EMBEDDING_MODEL=
# Optional per-feature overrides of AI_CHAT_MODEL. Set to "off" to disable just
# that feature while keeping the rest (e.g. AI_SUMMARY_MODEL=off).
AI_SUMMARY_MODEL=
AI_SENTIMENT_MODEL=
AI_EXTRACTION_MODEL=
AI_QUALITY_GATE_MODEL=
AI_INTERPRETATION_MODEL=
AI_MERGE_MODEL=

# ============================================================================
# File Storage (for image uploads)
# ============================================================================
# S3-compatible storage for image uploads in changelogs.
# Supports AWS S3, Cloudflare R2, Backblaze B2, MinIO, Railway Buckets, and other S3-compatible services.
# If not configured, image upload will be disabled in the rich text editor.
#
# S3_PUBLIC_URL is optional. If not set, files are served via BASE_URL/api/storage
# using presigned URL redirects (works with any provider, including private buckets).
# Set it explicitly to use a CDN or public bucket URL instead.
#
# For local development, MinIO is included in docker-compose and configured by default.
# Run `bun run setup` or `docker compose up -d minio` to start it.

# MinIO (local development - enabled by default)
S3_ENDPOINT=http://localhost:9000
S3_BUCKET=quackback
S3_REGION=us-east-1
S3_ACCESS_KEY_ID=minioadmin
S3_SECRET_ACCESS_KEY=minioadmin
S3_FORCE_PATH_STYLE=true
S3_PUBLIC_URL=
# Proxy all S3 traffic (uploads and downloads) through the server. Enable when
# the browser can't reach S3 directly (e.g. self-hosted Docker, ngrok):
# S3_PROXY=false

# Using an external S3 provider instead of the bundled MinIO?
#   - The local `minio` and `minio-init` services in docker-compose.yml are
#     then unused — stop/remove them (e.g. `docker compose stop minio minio-init`)
#     so you aren't running a container you don't need.
#   - Fill in the provider values below.
#
# For production, replace with your preferred S3-compatible provider:
#
# AWS S3 (public bucket):
#   S3_ENDPOINT=          # Leave empty for AWS S3
#   S3_BUCKET=your-bucket-name
#   S3_REGION=us-east-1
#   S3_ACCESS_KEY_ID=your-access-key
#   S3_SECRET_ACCESS_KEY=your-secret-key
#   S3_FORCE_PATH_STYLE=false
#   S3_PUBLIC_URL=https://your-bucket-name.s3.us-east-1.amazonaws.com
#
# AWS S3 (private bucket via presigned redirect):
#   S3_ENDPOINT=
#   S3_BUCKET=your-bucket-name
#   S3_REGION=us-east-1
#   S3_ACCESS_KEY_ID=your-access-key
#   S3_SECRET_ACCESS_KEY=your-secret-key
#   S3_FORCE_PATH_STYLE=false
#   S3_PUBLIC_URL=https://your-app.example.com/api/storage
#
# Cloudflare R2:
#   S3_ENDPOINT=https://<account-id>.r2.cloudflarestorage.com
#   S3_BUCKET=your-bucket-name
#   S3_REGION=auto
#   S3_ACCESS_KEY_ID=your-access-key
#   S3_SECRET_ACCESS_KEY=your-secret-key
#   S3_FORCE_PATH_STYLE=true
#   S3_PUBLIC_URL=https://your-custom-domain.com
#
# Railway Buckets (private — served via presigned URL redirects automatically):
#   S3_ENDPOINT=https://your-bucket-endpoint.storageapi.dev
#   S3_BUCKET=your-bucket-name
#   S3_REGION=us-east-1
#   S3_ACCESS_KEY_ID=your-access-key
#   S3_SECRET_ACCESS_KEY=your-secret-key
#   S3_FORCE_PATH_STYLE=true
#   # No S3_PUBLIC_URL needed — files served via BASE_URL/api/storage automatically

# ============================================================================
# Telemetry (optional)
# ============================================================================
# Anonymous usage statistics are enabled by default to help improve Quackback.
# Uncomment to disable.

# DISABLE_TELEMETRY=true

# ============================================================================
# Logging (optional)
# ============================================================================
# The server emits structured JSON logs to stdout (one object per line), ready
# for any log shipper (Grafana Alloy, Promtail, Fluent Bit, Vector, ...).
# LOG_LEVEL controls verbosity: trace | debug | info | warn | error | fatal | silent
# Default: info in production, debug otherwise.

# LOG_LEVEL=info