.env.example

# ──────────────────────────────────────────────────────────────────
# OpenGTM — Environment Variables
# Copy to .env and fill in your keys
# ──────────────────────────────────────────────────────────────────

# === LLM Provider (at least one required for AI features) ===
# All providers are configured via the Settings UI at runtime.
# You can also pre-seed them here. Only one is needed.
#
# --- Anthropic (Claude) — premium, native Messages API ---
# Powers AI/research columns and chat with Claude. In a cloud deployment
# (YUPCHA_CLOUD=1) Claude becomes the default automatically when a key is set;
# self-hosted/OSS installs stay opt-in (set LLM_DEFAULT_PROVIDER=anthropic, or
# pick it in Settings). Either way the free providers below remain the fallback.
# ANTHROPIC_API_KEY=           # https://console.anthropic.com/settings/keys
# ANTHROPIC_MODEL=claude-opus-4-8   # default model (Claude Opus 4.8)
#
# Set on hosted/cloud deployments so Claude is the default provider when an
# Anthropic key is present. Leave unset for self-host to keep the free chain.
# YUPCHA_CLOUD=1
#
# --- Free / OSS-friendly providers (the default fallback chain) ---
# OPENROUTER_API_KEY=          # https://openrouter.ai/keys (free: 20 RPM)
# OPENROUTER_MODEL=meta-llama/llama-3.3-70b-instruct:free
#
# GOOGLE_AI_API_KEY=           # https://aistudio.google.com/app/apikey
# GOOGLE_AI_MODEL=gemini-2.0-flash
#
# GROQ_API_KEY=                # https://console.groq.com/keys (free: 30 RPM)
# GROQ_MODEL=llama-3.3-70b-versatile
#
# CEREBRAS_API_KEY=            # https://cloud.cerebras.ai/
# CEREBRAS_MODEL=llama-3.3-70b
#
# NVIDIA_API_KEY=              # https://build.nvidia.com/ (free: 40 RPM)
# NVIDIA_MODEL=meta/llama-3.3-70b-instruct
#
# MISTRAL_API_KEY=             # https://console.mistral.ai/api-keys
# MISTRAL_MODEL=mistral-small-latest
#
# GITHUB_MODELS_API_KEY=       # https://github.com/marketplace/models
# GITHUB_MODELS_MODEL=gpt-4o

# === Enrichment Providers (BYOK, all optional) ===
# These can also be configured in Settings → API Keys at runtime.
#
# HUNTER_API_KEY=              # https://hunter.io — Email finder (25/mo free)
# APOLLO_API_KEY=              # https://apollo.io — People + company enrichment (50/mo free)
# ABSTRACT_API_KEY=            # https://abstractapi.com — Email validation (100/mo free)
# NUMVERIFY_API_KEY=           # https://numverify.com — Phone validation (100/mo free)
# IPINFO_TOKEN=                # https://ipinfo.io — Company data from domain (50K/mo free)

# === CRM Integrations (optional) ===
# HUBSPOT_TOKEN=               # HubSpot Private App token — https://developers.hubspot.com/
# META_ACCESS_TOKEN=           # Meta Marketing API token for Custom Audiences
# GOOGLE_ADS_ACCESS_TOKEN=     # OAuth2 token for Customer Match
# GOOGLE_ADS_DEVELOPER_TOKEN=  # Approved Google Ads API developer token
# LINKEDIN_ACCESS_TOKEN=       # rw_dmp_segments access requires LinkedIn approval

# === Data Sources (optional) ===
# GOOGLE_PLACES_API_KEY=       # Google Places API for structured business data
# GOOGLE_API_KEY=              # Google Custom Search API key
# GOOGLE_CSE_ID=               # Google Custom Search Engine ID
# SERPINGAPI_API_KEY=          # Serping API key (Google SERP; keyed search fallback) — https://serpingapi.com

# === Email Outreach (optional, also configurable in Settings) ===
# SMTP_HOST=smtp.gmail.com
# SMTP_PORT=587
# SMTP_EMAIL=
# SMTP_PASSWORD=
# SMTP_FROM_NAME=Yupcha
# SMTP_MAX_PER_HOUR=50

# === Security ===
# SECRET_KEY=                  # JWT signing key. REQUIRED in production: the app
#                              # FAILS to boot if left on the insecure default and
#                              # APP_ENV is not dev/test/local. Generate one with:
#                              #   python -c "import secrets; print(secrets.token_urlsafe(48))"
# SECRETS_MASTER_KEY=          # Local Fernet custody (default provider).
# SECRETS_PROVIDER=local       # local | vault_transit
# VAULT_ADDR=https://vault.example.com
# VAULT_TOKEN=                 # Static token, or use the agent-managed file below.
# VAULT_TOKEN_FILE=            # Vault Agent token sink; reread on every operation.
# VAULT_TRANSIT_KEY=opengtm
# VAULT_NAMESPACE=             # Optional Vault Enterprise namespace.
# VAULT_CACERT=                # Optional private CA bundle path.
# Exact comma-separated OIDC issuer hosts workspace admins may configure.
# Empty disables OIDC configuration; paths are allowed beneath each host.
# SSO_ALLOWED_ISSUER_HOSTS=login.microsoftonline.com,mycompany.okta.com
# Workspace SCIM bearer-token lifetime. Values are clamped to 1-365 days.
# OPENGTM_SCIM_TOKEN_TTL_DAYS=90
# CRM inbound callback token lifetime, clamped to 1-365 days.
# OPENGTM_DESTINATION_TOKEN_TTL_DAYS=90
# Connector signatures are optional for local development. Set required on a
# managed catalog to load only packages signed by docs/connectors/trusted-publishers.json.
# CONNECTOR_SIGNATURE_POLICY=optional
# Exact immutable revision of this deployment. Required before any signed
# controlled-live certificate can expose an integration as supported.
# OPENGTM_BUILD_SHA=<full-git-commit-sha>
# APP_ENV=dev                  # dev|test|local tolerate the insecure default key;
#                              # any other value (prod/production/staging) fails closed.
# ACCESS_TOKEN_EXPIRE_MINUTES=30          # short-lived access tokens (15–60 min)
# REFRESH_TOKEN_EXPIRE_MINUTES=20160      # refresh-token TTL (default 14 days)
# Parallel durable-job slots per worker process (1-64) and graceful shutdown
# drain time before active subprocesses are cancelled.
# WORKER_CONCURRENCY=1
# WORKER_SHUTDOWN_GRACE_SECONDS=30
# Maximum processing jobs per workspace across workers; 0 disables the cap.
# WORKER_MAX_ACTIVE_PER_WORKSPACE=2

# === Database (Postgres — required) ===
# Primary store for users, workbooks, jobs, and enrichment cells. Postgres gives
# real concurrent writers (MVCC), which the workbook enrichment run depends on.
# Compose uses the owner URL only for migrations and a separate non-superuser
# URL for API/worker/scheduler traffic so forced row-level security is effective.
# DATABASE_URL=postgresql+psycopg://schema_owner:change-me@postgres:5432/yupcha
# APP_DATABASE_URL=postgresql+psycopg://yupcha_runtime:change-me@postgres:5432/yupcha
# YUPCHA_RUNTIME_DB_USER=yupcha_runtime
# YUPCHA_RUNTIME_DB_PASSWORD=change-me
# Format: postgresql+psycopg://USER[:PASSWORD]@HOST:PORT/DBNAME
#
# DOCKER COMPOSE: docker-compose.yml ships a `postgres` service and defaults
# DATABASE_URL to the line below automatically — you do NOT need to set anything
# here to boot the stack. Uncomment/override only to point at an external DB.
# DATABASE_URL=postgresql+psycopg://yupcha:yupcha@postgres:5432/yupcha
#
# LOCAL (non-docker) default — libpq fills the user from $USER, local socket:
# DATABASE_URL=postgresql+psycopg://localhost:5432/yupcha
#
# Legacy/dev fallback (no concurrency — enrichment will hit "database is locked"):
# DATABASE_URL=sqlite:///data/data.db

# === Postgres service (docker-compose) ===
# Credentials for the bundled `postgres` container. Must stay consistent with
# the user/password/db in DATABASE_URL above. Defaults boot with NO edits.
# POSTGRES_USER=yupcha
# POSTGRES_PASSWORD=yupcha
# POSTGRES_DB=yupcha
# POSTGRES_PORT=5432            # Host port mapping for the postgres container

# === First-run demo seed (docker-compose `seed` service) ===
# On first boot the `seed` service creates an admin login + a populated, self-
# filling demo workbook wired to ZERO-KEY (free) providers — no API keys needed.
# It is idempotent (won't duplicate on restart). Defaults: admin / admin.
# SEED_ADMIN_USERNAME=admin
# SEED_ADMIN_PASSWORD=admin    # CHANGE THIS for any non-local deployment
# SEED_FORCE_RUN=1             # Re-trigger the demo enrichment run on next boot

# === Server Config ===
# PORT=3000                    # Nginx port (docker-compose)
# LOG_LEVEL=info

# === Redis (required for background enrichment workers) ===
# REDIS_URL=redis://localhost:6379

# === Worker Config ===
# WORKER_CONCURRENCY=10        # Max concurrent enrichment jobs per worker

# === Proxy (optional, for web scraping at scale) ===
# PROXY_LIST=                  # Comma-separated proxy URLs
# PROXY_MANAGER_URL=http://localhost:3050  # Proxy manager service URL

# === Reacher email verification (OPTIONAL — default OFF) ===
# Reacher is the strongest tier of the email cascade: unlimited, $0/email SMTP
# RCPT probing (safe/risky/invalid/unknown + catch-all + disposable + role). It
# is DUAL-LICENSED AGPL-3.0 OR commercial; we run the AGPL build as a separate
# networked process (compliant — no GPL contamination). When REACHER_ENABLED is
# unset the cascade is byte-for-byte today's SMTP-only behavior.
#
# Two ways to use it:
#   1. Self-host the optional container:  docker compose --profile reacher up
#      → set REACHER_ENABLED=1 and REACHER_API_KEY (= the container's header
#        secret). REACHER_URL defaults to the internal http://reacher:8080.
#   2. Commercial cloud API (BYO key): set REACHER_ENABLED=1, REACHER_URL to the
#      cloud endpoint, and REACHER_API_KEY to your key.
#
# PORT-25 CAVEAT: most clouds block outbound :25, so a self-hosted Reacher needs
# a SOCKS5 proxy (RCH__PROXY__*) or it returns mostly `unknown` (cascade falls
# back to the bundled SMTP probe). SECURITY: REACHER_URL is GLOBAL/env-only and
# is NEVER overridable per-workspace (SSRF mitigation) — only REACHER_ENABLED and
# REACHER_API_KEY can be set per workspace.
# REACHER_ENABLED=0            # 1/true to wire Reacher into the cascade front
# REACHER_URL=http://reacher:8080   # global only; http(s), not a metadata host
# REACHER_API_KEY=             # Bearer secret (self-host header secret OR cloud key)
# REACHER_TIMEOUT=12           # seconds; Reacher can stall on greylisting
# REACHER_BREAKER_THRESHOLD=3  # consecutive failures before the breaker opens
# REACHER_BREAKER_COOLDOWN=60  # seconds the breaker stays open
# REACHER_FROM_EMAIL=verify@yupcha.com    # container MAIL FROM identity
# REACHER_HELLO_NAME=verify.yupcha.com    # container EHLO/HELO name
# REACHER_PROXY_HOST=          # optional SOCKS5 proxy to escape blocked :25
# REACHER_PROXY_PORT=
# REACHER_PROXY_USERNAME=
# REACHER_PROXY_PASSWORD=