.env.example

# ─────────────────────────────────────────────────────────────────────────────
# 0. HOW TO USE THIS FILE
# ─────────────────────────────────────────────────────────────────────────────
#
# Local dev: the defaults below target the local Docker stack, so `pnpm dev`
# works once you fill the three secrets marked "REQUIRED (local)":
# BETTER_AUTH_SECRET, CRYPTO_LOCAL_MASTER_KEY, OPENAI_API_KEY.
# Step-by-step setup → docs/dev-quickstart.md.
#
# Self-host: lines marked "self-host:" show the value to use when deploying via
# Docker Compose. Copy to `.env`, fill every REQUIRED value, `chmod 600 .env`,
# `docker compose up`. Full variable reference → docs/hosting/configuration.md.

# ─────────────────────────────────────────────────────────────────────────────
# 1. Image versions (compose-only)
# ─────────────────────────────────────────────────────────────────────────────

# Pin a semver in production; `latest` is fine for first run.
PLATFORM_VERSION=latest
PLATFORM_IMAGE_SERVER=${ECR_REGISTRY}/${ECR_REPOSITORY}:server-${PLATFORM_VERSION}
PLATFORM_IMAGE_WEB=${ECR_REGISTRY}/${ECR_REPOSITORY}:web-${PLATFORM_VERSION}

# ─────────────────────────────────────────────────────────────────────────────
# 2. Public surface (Traefik + TLS)
# ─────────────────────────────────────────────────────────────────────────────

# Must resolve to this host's public IP for Let's Encrypt HTTP-01.
PLATFORM_DOMAIN=localhost

# Must match the externally-visible scheme+host (better-auth baseURL + cookies).
# Local dev serves the web app from Vite on http://localhost:5173.
# self-host: PUBLIC_URL=https://${PLATFORM_DOMAIN}
PUBLIC_URL=http://localhost:5173

# Required when PLATFORM_TLS_MODE=letsencrypt.
PLATFORM_ACME_EMAIL=admin@example.com

# letsencrypt: ACME HTTP-01 (port 80 reachable). self-signed: Traefik mints at boot.
PLATFORM_TLS_MODE=letsencrypt

# ─────────────────────────────────────────────────────────────────────────────
# 3. Postgres
# ─────────────────────────────────────────────────────────────────────────────

POSTGRES_USER=seta
# REQUIRED. Strong random value.
POSTGRES_PASSWORD=
POSTGRES_DB=seta

# Local dev connects to the Docker Postgres mapped to host port 5442 (`pnpm db:up`).
# self-host: DATABASE_URL=postgres://${POSTGRES_USER}:${POSTGRES_PASSWORD}@postgres:5432/${POSTGRES_DB}
DATABASE_URL=postgres://seta:seta@localhost:5442/seta

# ─────────────────────────────────────────────────────────────────────────────
# 4. Server runtime
# ─────────────────────────────────────────────────────────────────────────────

# self-host: NODE_ENV=production
NODE_ENV=development

# In-container only; Traefik routes to this.
PORT=3000

# REQUIRED. Min 32 chars. `openssl rand -hex 32`.
BETTER_AUTH_SECRET=

# Retention for core.events partitions.
EVENTS_RETENTION_DAYS=30

# env: reads CRYPTO_LOCAL_MASTER_KEY. kms: reads CRYPTO_KMS_KEY_ARN + AWS_REGION.
CRYPTO_KEY_PROVIDER=env

# Required when CRYPTO_KEY_PROVIDER=env. 64 hex chars (32 bytes).
# Generate: `pnpm --filter @seta/shared-crypto crypto:gen-local-key`.
# For rotation, switch to CRYPTO_LOCAL_KEYS + CRYPTO_LOCAL_PRIMARY_KID.
CRYPTO_LOCAL_MASTER_KEY=

# Required when CRYPTO_KEY_PROVIDER=kms. IAM role needs kms:GenerateDataKey,
# kms:Decrypt, kms:DescribeKey on this ARN.
CRYPTO_KMS_KEY_ARN=
AWS_REGION=

# `*` loads all modules (default). Comma-separated list for split deploys.
PLATFORM_MODULES=*

# Comma-separated list of allowed origins for the API (CORS allowlist).
# Browsers must be served from one of these origins to call /api/* with cookies.
CORS_ORIGINS=http://localhost:5173

# Session cookie SameSite policy. `strict` is the default; switch to `lax`
# only if Entra/SSO callback is on a different host than the app.
SESSION_COOKIE_SAMESITE=strict

# ─────────────────────────────────────────────────────────────────────────────
# 5. SSO (optional — local-password auth works without it)
# ─────────────────────────────────────────────────────────────────────────────

# Microsoft Entra ID multi-tenant app. Both required to enable Entra SSO.
MICROSOFT_CLIENT_ID=
MICROSOFT_CLIENT_SECRET=

# ─────────────────────────────────────────────────────────────────────────────
# 6. Mail (outbound transactional only)
# ─────────────────────────────────────────────────────────────────────────────

# dev-stub captures emails in memory. Production must set `smtp`.
MAILER_DEFAULT_TRANSPORT=dev-stub
MAILER_DEFAULT_SENDER=noreply@seta.example
MAILER_DEFAULT_SENDER_DISPLAY_NAME=

# Required when MAILER_DEFAULT_TRANSPORT=smtp.
# e.g. smtp://user:pass@email-smtp.us-east-1.amazonaws.com:587
MAILER_DEFAULT_SMTP_URL=

# Required only for tenants using Microsoft Graph /sendMail. Reuse the operator
# Entra app with Mail.Send (Application) permission + tenant admin consent.
MAILER_GRAPH_CLIENT_ID=
MAILER_GRAPH_CLIENT_SECRET=

# OTLP HTTP endpoint for traces. Unset = traces dropped locally.
# When running via Docker Compose, point to the bundled Jaeger service:
#   OTEL_EXPORTER_OTLP_ENDPOINT=http://jaeger:4318
# Jaeger UI available at https://traces.<domain>
OTEL_EXPORTER_OTLP_ENDPOINT=

# Prometheus metrics are always exposed on port 9464 by each app container
# (scraped by the bundled Prometheus service). Override the port if needed:
OTEL_PROMETHEUS_PORT=

# Grafana admin password (default: admin — change before exposing publicly).
# Grafana UI available at https://metrics.<domain>
GRAFANA_ADMIN_PASSWORD=
# Root URL for Grafana (required for correct redirects behind a reverse proxy):
#   GRAFANA_ROOT_URL=https://metrics.example.com
GRAFANA_ROOT_URL=

# /health/ready returns 503 when any subscription has more than this many
# dead-letter rows in the last 24h. Default 100.
DLQ_ALERT_THRESHOLD=100

# ─────────────────────────────────────────────────────────────────────────────
# 7. Agent
# ─────────────────────────────────────────────────────────────────────────────

# Comma list of chat models as provider/model[:tier]; tier ∈ fast|balanced|reasoning
# (default balanced). First listed is used when AGENT_MODEL_DEFAULT=auto can't infer.
# Provider keys follow the conventional names below. Unset → disables agent chat.
AGENT_MODELS=openai/gpt-5.5:balanced
# Selection key or "auto" (tier-based auto-pick). Default: auto.
# AGENT_MODEL_DEFAULT=auto

# Per-provider API keys (Mastra reads these automatically). OpenAI is the default.
OPENAI_API_KEY=
# ANTHROPIC_API_KEY=
# GOOGLE_API_KEY=
# Self-hosted / OpenAI-compatible (LM Studio, vLLM, Ollama): set <PROVIDER>_BASE_URL
# (+ optional <PROVIDER>_API_KEY) and reference it as "<provider>/<model>" in AGENT_MODELS.
# Example for AGENT_MODELS=vllm/llama-3.3:
# VLLM_BASE_URL=http://localhost:1234/v1
# VLLM_API_KEY=

# AGENT_HITL_EXPIRY_SECONDS=300
# AGENT_RATE_LIMIT_TPM=60000
# AGENT_RATE_LIMIT_TURNS_PER_MIN=10

# --- Agent tool execution timeout & circuit breaker ---
# Per-call deadline for read tools (tools without needsApproval). Default 30s.
# AGENT_TOOL_TIMEOUT_READ_MS=30000
# Per-call deadline for write tools (needsApproval=true). Default 60s.
# AGENT_TOOL_TIMEOUT_WRITE_MS=60000
# Hard cap on any per-tool executionTimeoutMs override. Default 300s.
# AGENT_TOOL_TIMEOUT_MAX_MS=300000
# Consecutive timeouts or unhandled exceptions before the per-(tenant, tool)
# circuit breaker opens. Default 3.
# AGENT_TOOL_BREAKER_FAILURE_THRESHOLD=3
# How long the breaker stays open before allowing one half-open probe.
# Default 60s.
# AGENT_TOOL_BREAKER_OPEN_MS=60000

# Memory — sliding window size per turn. Increase for longer sessions.
# Default 20.
# AGENT_MEMORY_LAST_MESSAGES=20

# ─────────────────────────────────────────────────────────────────────────────
# 8. Retrieval — rerank + HNSW
# ─────────────────────────────────────────────────────────────────────────────

# Online + batch embedding model as provider/model. Must be a 1536-dim model
# (pgvector columns are pinned to 1536). Batch backfill requires an openai/* model.
EMBED_MODEL=openai/text-embedding-3-small

# auto: Cohere if COHERE_API_KEY set, else LLM-as-judge. none: skip rerank.
RERANKER_PROVIDER=auto
COHERE_API_KEY=

# Stage-1 oversample → stage-2 cap.
RERANK_STAGE1_TOPK=50
RERANK_STAGE2_TOPN=10
RERANK_CACHE_TTL_SECONDS=300

# pgvector HNSW search-list. Higher = better recall, slower query.
HNSW_EF_SEARCH=100

# ─────────────────────────────────────────────────────────────────────────────
# 9. S3-lite storage (tenant knowledge files)
# ─────────────────────────────────────────────────────────────────────────────

S3_REGION=ap-southeast-1

# Keys are prefixed `tenants/<id>/`.
S3_BUCKET=seta-knowledge

# Set for MinIO/LocalStack (e.g. http://localhost:9000).
S3_ENDPOINT=

# Required when S3_ENDPOINT is set or running outside an IAM instance role.
S3_ACCESS_KEY_ID=
S3_SECRET_ACCESS_KEY=

# true for MinIO; false for AWS S3.
S3_FORCE_PATH_STYLE=false

# ─────────────────────────────────────────────────────────────────────────────
# 10. Knowledge upload AV scanning (ClamAV)
# ─────────────────────────────────────────────────────────────────────────────

# Compose service hostname. Defaults to `localhost` for split deploys.
CLAMAV_HOST=clamav
CLAMAV_PORT=3310

# When true (default), files cannot move past `uploading` until ClamAV marks
# them clean. Set to `false` only for environments that intentionally skip AV.
KNOWLEDGE_AV_REQUIRED=false