.env.example

# ============================================
# Compendiq - Environment Configuration
# ============================================
# Copy this file to .env and fill in real values.
# NEVER commit .env to git.

# === Application ===

# --- Docker image version (GHCR tag for docker/docker-compose.yml; default: dev) ---
# Pin a release for production, e.g. 0.6.2. install.sh defaults to latest when unset.
# COMPENDIQ_VERSION=dev

# --- Required Secrets (MUST change in production) ---
JWT_SECRET=change-me-to-a-random-32-char-string-min
# PAT_ENCRYPTION_KEY must be at least 32 bytes (UTF-8). The full value is fed
# through HKDF-SHA256 to derive the AES-256-GCM key, so every character
# contributes — longer is better. Also encrypts smtp_pass at rest.
PAT_ENCRYPTION_KEY=change-me-to-a-random-32-char-string-min
# MCP_DOCS_TOKEN is the shared secret for backend <-> mcp-docs /mcp communication.
# In production (NODE_ENV=production, the Docker default), the sidecar fails closed
# (returns 401 Unauthorized) until this token is set on both services.
MCP_DOCS_TOKEN=change-me-to-a-random-32-char-string-min

# Optional master key for scheduled / S3 backups (#1420). Same 32-byte minimum
# as PAT_ENCRYPTION_KEY. On-demand downloads may use a passphrase instead.
# BACKUP_ENCRYPTION_KEY=change-me-to-a-random-32-char-string-min
#
# Standalone restore CLI only. Supply this through a secret-aware shell or
# process environment instead of `--passphrase`, which exposes the value in
# the process list. Do not persist a real restore passphrase in this file.
# BACKUP_PASSPHRASE=
#
# EE KMS backup credentials (CE ignores these). Provider/key selection lives
# in Backup & Recovery settings. An enabled KMS provider needs no local
# BACKUP_ENCRYPTION_KEY or download passphrase.
# AWS uses the default credential chain: static credentials, profiles,
# web identity, container roles, then instance roles, with token refresh.
# File paths below refer to files mounted read-only INSIDE the backend container.
# AWS_ACCESS_KEY_ID=
# AWS_SECRET_ACCESS_KEY=
# AWS_SESSION_TOKEN=
# AWS_REGION=
# AWS_DEFAULT_REGION=
# AWS_PROFILE=
# AWS_SHARED_CREDENTIALS_FILE=
# AWS_CONFIG_FILE=
# AWS_ROLE_ARN=
# AWS_ROLE_SESSION_NAME=
# AWS_WEB_IDENTITY_TOKEN_FILE=
# AWS_CONTAINER_CREDENTIALS_FULL_URI=
# AWS_CONTAINER_CREDENTIALS_RELATIVE_URI=
# AWS_CONTAINER_AUTHORIZATION_TOKEN=
# AWS_CONTAINER_AUTHORIZATION_TOKEN_FILE=
# AWS_EC2_METADATA_DISABLED=false
# VAULT_ADDR=
# VAULT_TOKEN=
# VAULT_NAMESPACE=
#
# EE offline replica recovery: explicit target, without the source database.
# Use --object-key for the complete key recorded by that destination.
# BACKUP_RESTORE_S3_ENDPOINT=
# BACKUP_RESTORE_S3_BUCKET=
# BACKUP_RESTORE_S3_REGION=us-east-1
# BACKUP_RESTORE_S3_PREFIX=
# BACKUP_RESTORE_S3_ACCESS_KEY=
# BACKUP_RESTORE_S3_SECRET_KEY=
# BACKUP_RESTORE_S3_FORCE_PATH_STYLE=true

# --- PostgreSQL ---
# The password must match the POSTGRES_PASSWORD you set for docker compose
# (see "Docker Compose Only" below — it has no default).
POSTGRES_URL=postgresql://kb_user:<your-POSTGRES_PASSWORD>@localhost:5432/kb_creator

# PG_POOL_MAX=20                       # PostgreSQL connection pool max (default: 20)
# PG_VECTOR_POOL_MAX=5                 # Separate pool for pgvector similarity queries (default: 5)
# PG_STATEMENT_TIMEOUT=30000           # Global query timeout in ms (default: none)

# --- PostgreSQL (Test - port 5433) ---
POSTGRES_TEST_URL=postgresql://kb_user:changeme-postgres@localhost:5433/kb_creator_test

# --- Redis ---
# Both Redis clients (node-redis and BullMQ/ioredis) support:
#   rediss:// scheme = TLS, optional ACL username:password (percent-encoded),
#   optional numeric /N database index,
#   e.g. rediss://app-user:secret@redis.internal:6380/2
# Not supported on the BullMQ side: IPv6 bracket hosts and query parameters;
# a non-numeric database path is ignored.
# The password must match the REDIS_PASSWORD you set for docker compose
# (see "Docker Compose Only" below — it has no default).
REDIS_URL=redis://:<your-REDIS_PASSWORD>@localhost:6379

# --- BullMQ Job Queue ---
# USE_BULLMQ=true                      # Set to 'false' to fall back to legacy setInterval workers (default: true)

# --- Server ---
NODE_ENV=development                    # 'development' or 'production' only (exact). Not 'prod' — anything else is treated as development. Docker images set production.
BACKEND_PORT=3051
# FRONTEND_URL=http://localhost:5273    # Used for CORS origin (default: http://localhost:5273). Comma-separated for multiple origins: http://localhost:5273,https://app.example.com
                                        # Behind a reverse proxy with SSO/OIDC (EE): MUST be the public origin (e.g. https://app.example.com).
                                        # The post-login OIDC redirect to the SPA is built from this value — leaving it at the localhost default dead-ends login. See docs/ADMIN-GUIDE.md → OIDC / SSO.
# LOG_LEVEL=info                        # Pino log level: 'fatal','error','warn','info','debug','trace' (default: info)
# SHUTDOWN_TIMEOUT_MS=50000             # Graceful-shutdown hard deadline in ms before the process force-exits (positive integer, default: 50000). Keep below the container stop grace period (EE compose: 60s) so the in-process timer fires before SIGKILL. See ADR-024.

# --- Session ---
# ACCESS_TOKEN_EXPIRY=1h      # JWT access token lifetime (default: 1h, maximum: 24h). Accepts jose duration format: '30m', '1h', '2h', etc.
                              # Capped at 24h (#737): the lifetime bounds how long a deactivated/demoted account could keep
                              # API access if revocation checks were unavailable. Values above 24h are clamped to 24h at
                              # startup with a warning logged. Use the 7-day refresh token for session longevity.
# TOKEN_CLEANUP_INTERVAL_HOURS=24  # How often to run expired refresh token cleanup (default: 24h)

# LEGACY LLM env vars (bootstrap-only fallback, used only on fresh install
# when llm_providers table is empty). Configure providers in Settings → AI Models.

# --- LLM providers (configured in Settings → AI Models, see ADR-021) ---
# Providers are now rows in the `llm_providers` table, managed via the admin UI.
# All env vars in this section are DEPRECATED: seed-only; consulted on first
# boot when `llm_providers` is empty. Configure providers in Settings → AI Models.

# (Removed) LLM_PROVIDER was the legacy two-slot {ollama, openai} toggle. Replaced by the `llm_providers` table + per-use-case assignments. Configure providers in Settings → AI Models.

# DEPRECATED: seed-only; consulted on first boot when llm_providers is empty. Configure providers in Settings → AI Models.
# OLLAMA_BASE_URL=http://localhost:11434

# DEPRECATED: no effect since migration 054 (a warning is logged if set). Configure per-use-case models in Settings → AI Models.
# EMBEDDING_MODEL=bge-m3

# EMBEDDING_DIMENSIONS=1024            # Vector dimensions — must match the embedding model output (schema-level)
# (Removed) FTS_LANGUAGE was the keyword-search language (stemming + stop words). It is now `admin_settings.fts_language`, edited in Settings → AI Models → Retrieval. The env var never took effect on a migrated instance: migration 049 seeds that row, so the fallback that read it was unreachable.
# REEMBED_WAIT_LOCKS_MS=600000         # Max time a re-embed job waits for per-user embedding locks to clear before aborting (default: 600000 = 10 min)
# BGE-M3 via Ollama (1024 dims). Run: ollama pull bge-m3

# DEPRECATED: no effect since migration 054 (a warning is logged if set). Set the provider's API key in Settings → AI Models.
# LLM_BEARER_TOKEN=

# LLM_AUTH_TYPE=               # No effect since migration 054 — auth type is set per provider in Settings → AI Models
# LLM_VERIFY_SSL=true          # Set to 'false' to disable TLS certificate verification for LLM connections
# LLM_STREAM_TIMEOUT_MS=300000 # Streaming request timeout in ms (default: 300000 = 5 min). Increase for very large articles.
# LLM_CACHE_TTL=3600           # Redis TTL in seconds for LLM response cache (default: 3600 = 1 hour)

# --- Image staging for AI source material (#1154 / #1183) ---
# POST /api/llm/prepare-image stages the uploaded image in Redis under
# llm:img:<userId>:<sha256> for 15 minutes, one entry per user (a new upload
# evicts that user's previous one). Two ceilings are worth knowing:
#
#   * Per image: 5 MB and 4096 px per edge, fixed in code
#     (backend/src/core/services/image-validator.ts). The browser re-encodes
#     every attachment to WebP within 1568 px first, so real uploads land far
#     below; the ceiling binds direct API callers.
#   * Across the instance: staged images may occupy at most
#     IMAGE_STAGING_MAX_REDIS_PERCENT of Redis --maxmemory, MINUS whatever the
#     queues and caches are already using. With the shipped --maxmemory 256mb
#     and the default 80%, that is a ~205 MB high-water mark for Redis as a
#     whole — roughly 40 users holding a worst-case 5 MB image at once.
#
# Redis runs --maxmemory-policy noeviction and is shared with BullMQ, so a full
# instance rejects writes for the whole app (sync, re-embed, summary, quality).
# Staging is therefore refused with 503 when the write would cross the mark:
# the image feature degrades, background processing does not. The check is
# check-then-write, so simultaneous uploads can each pass on the same pre-write
# reading and collectively overshoot the mark — under burst the percentage is
# a soft target, not a hard guarantee. Raise this only alongside --maxmemory.
# Ignored when maxmemory is 0 (unlimited) or when Redis does not answer INFO.
# IMAGE_STAGING_MAX_REDIS_PERCENT=80   # Range 1-100 (default: 80)

# --- LLM Request Queue (backpressure) ---
# LLM_CONCURRENCY=4                    # Max concurrent LLM requests (default: 4)
# LLM_MAX_QUEUE_DEPTH=50               # Reject new requests when queue exceeds this depth (default: 50)
# DEPRECATED: configure in Settings → AI Models → LLM providers (Runtime limits, #268); consulted only when the admin_settings row is absent.
# LLM_MAX_CONCURRENT_STREAMS_PER_USER=3  # Per-user cap on simultaneously-open SSE streams (fallback default: 3; range: 1–20)

# DEPRECATED: seed-only; consulted on first boot when llm_providers is empty. Configure providers in Settings → AI Models.
# DEFAULT_LLM_MODEL=

# --- Background Auto-Summarizer ---
# Run Now uses one bounded batch too; remaining pages wait for another trigger/cycle.
# Pages per batch is set in Settings → AI Models → Workers (no env var).
# SUMMARY_CHECK_INTERVAL_MINUTES=60  # How often the worker scans for pages needing summaries (default: 60)
# DEPRECATED: no effect since migration 054 (a warning is logged if set). Configure per-use-case models in Settings → AI Models.
# SUMMARY_MODEL=

# --- OpenAI-compatible seed values (DEPRECATED: seed-only; configure providers in Settings → AI Models) ---
# Works with: OpenAI, Azure OpenAI, LM Studio, vLLM, llama.cpp server, LocalAI, etc.
# OPENAI_BASE_URL=https://api.openai.com/v1
# OPENAI_API_KEY=              # API key — seeded as the openai provider's api_key on first boot

# --- Quality Analysis Worker ---
# Run Now uses one bounded batch too; remaining pages wait for another trigger/cycle.
# Pages per batch is set in Settings → AI Models → Workers (no env var).
# QUALITY_CHECK_INTERVAL_MINUTES=60  # How often the quality worker runs (default: 60 min)
# DEPRECATED: no effect since migration 054 (a warning is logged if set). Configure per-use-case models in Settings → AI Models.
# QUALITY_MODEL=

# --- Sync Scheduler ---
# SYNC_INTERVAL_MIN=15               # How often the background sync scheduler polls for due syncs, in minutes (default: 15)
# RESTRICTION_CONFIRM_WINDOW_HOURS=168  # (EE + RAG permission enforcement) Re-confirm each page's Confluence restrictions at least this often; the audit log is consulted to skip unchanged pages within the window. Fails safe to a full re-fetch. (default: 168 = 7 days)

# --- Confluence API Rate Limiting ---
# Confluence API rate limit is configured via Admin Settings (key: confluence_rate_limit_rpm, default 60 rpm). There is no env var override.

# --- MCP Documentation Sidecar (air-gapped LLM doc access) ---
# MCP_DOCS_URL=http://mcp-docs:3100/mcp  # URL of the MCP docs sidecar (default in Docker)
# MCP_LOG_LEVEL=info                       # Log level for the sidecar container
# MCP_CACHE_TTL=3600                       # Default cache TTL in seconds
# MCP_DOCS_TOKEN is configured in the "Required Secrets" section above.
# All other MCP Docs settings (enabled, domain allow/blocklist) are managed via Admin Settings UI.

# --- RAG / Vector Search ---
# RAG_EF_SEARCH=100                  # DEPRECATED (#1285). The HNSW ef_search floor lives in
#                                    # admin_settings.rag_ef_search, edited in Settings → AI Models → Retrieval.
#                                    # Nothing seeds that row, so this value is still honoured on a fresh
#                                    # install — but only until the panel is saved once, after which every
#                                    # successful read ignores it. A read that FAILS holds what that process
#                                    # last resolved, or the row it wrote; a process holding neither — a
#                                    # fresh pod, a restart, a pod that did not serve the write — reads this
#                                    # variable again, and keeps reading it — re-held each 60 s TTL — until
#                                    # one of its settings reads succeeds (#1512), so unset it once the panel
#                                    # is saved. Setting it logs a deprecation notice at startup.
#                                    # Must be a whole number in pgvector's [1, 1000]; anything else is
#                                    # ignored (the floor falls back to 100) and the startup notice says so.

# --- Data Retention ---
# RETENTION_AUDIT_LOG_DAYS=365       # Keep audit_log rows for N days (default: 365)
# RETENTION_SEARCH_ANALYTICS_DAYS=90 # Keep search_analytics rows for N days (default: 90)
# RETENTION_ERROR_LOG_DAYS=30        # Keep error_log rows for N days (default: 30)
# RETENTION_VERSIONS_MAX=50          # Keep last N page_versions per page (default: 50)
# Env fallbacks for admin-configurable retention windows (admin_settings takes
# precedence); accepted range 7–3650 days.
# RETENTION_ADMIN_ACCESS_DENIED_DAYS=90    # Keep admin access-denied audit rows for N days (default: 90)
# RETENTION_PENDING_SYNC_VERSIONS_DAYS=90  # Prune abandoned pending_sync_versions older than N days (default: 90)

# --- Enterprise License ---
# COMPENDIQ_LICENSE_KEY=              # Enterprise license key (format: ATM-{tier}-{seats}-{expiryYYYYMMDD}.{signature})

# --- Email Notifications (SMTP) ---
# SMTP_HOST=                            # SMTP server hostname (e.g., smtp.example.com)
# SMTP_PORT=587                         # SMTP port (default: 587 for STARTTLS, 465 for SMTPS)
# SMTP_SECURE=false                     # Use TLS/SSL (default: false = STARTTLS on port 587)
# SMTP_USER=                            # SMTP username
# SMTP_PASS=                            # SMTP password
# SMTP_FROM=noreply@compendiq.local     # Sender address
# SMTP_ENABLED=false                    # Enable email notifications (default: false)

# --- OIDC / SSO ---
# OIDC/SSO is available in the Enterprise Edition only.

# --- Confluence (optional, can be set per-user in UI) ---
# CONFLUENCE_VERIFY_SSL=true

# --- Attachments (local cache for draw.io and image attachments synced from Confluence) ---
# ATTACHMENTS_DIR=data/attachments   # Relative to backend working dir (default). Set to an absolute path in production.
# CLIENT_MODEL_ASSETS_DIR=/app/data/client-models  # #1418 operator-supplied ONNX + Hunspell. Defaults to <parent of ATTACHMENTS_DIR>/client-models.

# --- Draw.io Editor ---
# The draw.io embed URL is configurable at runtime via Admin Settings in the UI.
# No env var is required — the default (https://embed.diagrams.net) is used automatically.
# Override in Admin Settings if embed.diagrams.net is blocked by your firewall.
# NOTE: If using a custom draw.io URL, also update the frame-src CSP in frontend/nginx-security-headers.conf.

# --- Custom CA Bundle (for self-signed certificates) ---
# NODE_EXTRA_CA_CERTS=/path/to/ca-bundle.pem  # PEM CA bundle file path (also used by Node.js natively)

# === Encryption Key Rotation ===
# SKIP on a fresh install. Set PAT_ENCRYPTION_KEY above and leave this whole
# block commented. Uncommenting the placeholders does nothing useful and can
# hide a real rotation (invalid JSON is ignored with a warning).
#
# Use this only when replacing PAT_ENCRYPTION_KEY without downtime:
#   1. Add the new key as a higher version (keep the old key listed).
#   2. Restart the backend. New writes use the highest version; decrypt still
#      tries every listed key, so existing PATs/API keys/SMTP stay readable.
#   3. POST /api/admin/rotate-encryption-key (admin JWT) to re-encrypt at rest.
#   4. Remove the old key from env and restart again.
#
# Pick one of A or B, not both. Option B is usually easier.
#
# Option A: JSON array of { version, key } objects
# PAT_ENCRYPTION_KEYS='[{"version":2,"key":"new-key-at-least-32-characters!!!!!"},{"version":1,"key":"old-key-at-least-32-characters!!!!!"}]'
#
# Option B: Numbered env vars (V1 through V10)
# PAT_ENCRYPTION_KEY_V1=old-key-at-least-32-characters!!!!!
# PAT_ENCRYPTION_KEY_V2=new-key-at-least-32-characters!!!!!
#
# The plain PAT_ENCRYPTION_KEY above is treated as version 0 (legacy fallback).
#
# AES keys are derived via HKDF-SHA256 over the full passphrase (>= 32 UTF-8
# bytes). Data encrypted before the HKDF migration (truncation-derived keys)
# stays decryptable and is upgraded automatically on re-encryption / rotation.

# === OpenTelemetry (optional) ===
# OTEL_ENABLED=false                          # Set to 'true' to enable OpenTelemetry tracing + metrics (default: false)
# OTEL_SERVICE_NAME=compendiq-backend         # Service name reported to the OTLP collector (default: compendiq-backend)
# OTEL_EXPORTER_OTLP_ENDPOINT=               # OTLP collector endpoint, e.g. http://localhost:4318.
#                                            # Traces AND metrics (#1117) go here when set. Standard per-signal
#                                            # env config is honored for both: OTEL_EXPORTER_OTLP_TRACES_ENDPOINT /
#                                            # OTEL_EXPORTER_OTLP_METRICS_ENDPOINT for split collectors, and
#                                            # OTEL_TRACES_EXPORTER / OTEL_METRICS_EXPORTER (incl. 'none'). Only
#                                            # when nothing is configured do both fall back to console exporters.

# --- SearXNG (optional) ---
# SEARXNG_URL=http://searxng:8080    # Backend fallback for the MCP-docs web-search backend (admin_settings.searxng_url takes precedence)
# SEARXNG_LIMITER=false              # Enable rate limiter (true for public-facing)
# SEARXNG_IMAGE_PROXY=false          # Enable image proxying
# SEARXNG_SECRET_KEY=                # Override auto-generated secret key
# SEARXNG_TRUSTED_PROXIES=          # Comma-separated IPs/CIDRs of actual reverse proxies; defaults to loopback only
#                                   # Traefik sends X-Forwarded-For automatically, but trust only its source address/network

# --- Collaborative editing e2e (Playwright project `collab`) ---
# Required for a full `npx playwright test` (chromium runs first; first-register
# cannot create an admin after that). Empty-DB first-register admin is only for
# `npx playwright test --project=collab --no-deps`.
# COLLAB_E2E_ADMIN=
# COLLAB_E2E_PASSWORD=
#
# --- Disposable browser CI stack (see docs/architecture/05-deployment.md) ---
# E2E_CI=1                         # Opt-in only: starts servers and provisions a fresh instance
# E2E_BASE_URL=http://localhost:8081
# VITE_API_PROXY_TARGET=http://localhost:3051
# Requires a fresh loopback POSTGRES_URL database named kb_e2e and disposable Redis.
# COLLAB_E2E_ADMIN / COLLAB_E2E_PASSWORD above become the newly created admin.
# Never point this mode at an existing installation; local normal mode does not provision.

# === Docker Compose Only ===
# These variables are used by docker-compose.yml and are NOT read by the application directly.
# POSTGRES_PASSWORD and REDIS_PASSWORD are REQUIRED by docker/docker-compose.yml
# with no default — compose refuses to start without them.
# Generate strong URL-safe values, e.g.: openssl rand -hex 24
# (not base64 — '/', '+', '=' break the raw interpolation into POSTGRES_URL/REDIS_URL)
# POSTGRES_USER=kb_user                       # PostgreSQL superuser name (used in docker-compose)
# POSTGRES_PASSWORD=                          # REQUIRED — PostgreSQL superuser password (used in docker-compose)
# POSTGRES_DB=kb_creator                      # PostgreSQL database name (used in docker-compose)
# REDIS_PASSWORD=                             # REQUIRED — Redis AUTH password (used in docker-compose)
# FRONTEND_PORT=5273                          # Host port mapped to the frontend container
# LOGIN_PAGE_VARIANT=local-loop               # Initial/fallback login design: local-loop or change-desk; Settings → Diagnostics can override it
# LOGIN_PAGE_VARIANT_PICKER=false             # Show the on-page design switcher (true/false); rebuild frontend after changing
# HOST_CA_BUNDLE_PATH=/etc/pki/ca-trust/extracted/pem/tls-ca-bundle.pem    # Host path to CA bundle (bind-mounted into container)
# CONTAINER_CA_BUNDLE_PATH=/etc/ssl/certs/ca-certificates.crt              # Container path for the CA bundle
#
# Per-service memory limits (used by docker-compose.yml). Each has a sensible
# default baked into compose; override only if a service is being OOM-killed
# (e.g. the backend during large Confluence syncs / embedding batches) or to
# tighten limits on a small host. Accept any docker mem_limit value (e.g. 2048m, 2g).
# FRONTEND_MEM_LIMIT=128m                     # nginx static edge (default 128m)
# BACKEND_MEM_LIMIT=1024m                     # Fastify API — raise for heavy sync/embedding/PDF work (default 1024m)
# POSTGRES_MEM_LIMIT=1024m                    # PostgreSQL + pgvector (default 1024m)
# REDIS_MEM_LIMIT=320m                        # Redis — keep above its maxmemory (default 320m)
# MCP_DOCS_MEM_LIMIT=256m                     # MCP docs sidecar (default 256m)
# SEARXNG_MEM_LIMIT=256m                      # SearXNG metasearch (default 256m)