.env.example

# =============================================================================
# Phoenix / Elixir
# =============================================================================

# Ecto database connection URL (format: ecto://USER:PASS@HOST:PORT/DATABASE)
DATABASE_URL=ecto://postgres:postgres@localhost:5432/stacks_dev

# Base64-encoded secret for signing cookies and tokens.
# Generate with: mix phx.gen.secret
SECRET_KEY_BASE=generate-with-mix-phx-gen-secret

# Public-facing hostname (used for URL generation)
PHX_HOST=localhost

# HTTP port the Phoenix server listens on
PORT=4000

# Set to "true" to enable IPv6 for database connections (required on some Fly.io setups)
ECTO_IPV6=false

# Ecto connection pool size (default: 10)
POOL_SIZE=10

# =============================================================================
# Guardian (JWT authentication)
# =============================================================================

# Secret key for signing JWT tokens.
# Generate with: mix guardian.gen.secret
GUARDIAN_SECRET_KEY=generate-a-secret-key

# =============================================================================
# Cloak (field-level encryption for PII)
# =============================================================================

# 32-byte AES key, base64-encoded.
# Generate with: 32 |> :crypto.strong_rand_bytes() |> Base.encode64()
CLOAK_KEY=generate-a-32-byte-base64-key

# =============================================================================
# Vision sidecar (Python/FastAPI — deployed to Modal)
# =============================================================================

# Environment name for the vision sidecar (development | production)
VISION_ENVIRONMENT=development

# URL of the deployed Modal vision service.
# Production: set automatically by deploy-preview.sh from the modal deploy output.
# Local dev: run `modal serve apps/vision/modal_app.py` and paste the printed URL,
#            or point at a locally running FastAPI server (e.g. http://localhost:8000).
VISION_SERVICE_URL=http://localhost:8000

# URL the vision sidecar uses to call back to the Phoenix core.
# In production on Fly.io this is http://core.internal:4000
VISION_CORE_URL=http://localhost:4000

# HMAC secret shared between Phoenix and the vision sidecar for request signing.
# Must be the same value in both services. Required at startup (not prod-only).
# Generate with: :crypto.strong_rand_bytes(64) |> Base.encode64()
VISION_HMAC_SECRET=generate-a-strong-random-secret

# Together AI API key for LLM features (used by vision sidecar)
VISION_TOGETHER_API_KEY=together-api-key-for-llm

# =============================================================================
# Object storage (Cloudflare R2 — S3-compatible)
# =============================================================================

# Cloudflare account ID (used to construct the R2 endpoint URL)
R2_ACCOUNT_ID=your_cloudflare_account_id

# Access credentials for the R2 storage bucket
# Create via: Cloudflare dashboard → R2 → Manage R2 API tokens
R2_ACCESS_KEY_ID=your_r2_access_key
R2_SECRET_ACCESS_KEY=your_r2_secret_key

# Bucket name for uploaded book images
R2_BUCKET_NAME=stacks-images

# =============================================================================
# Scraper (Rust microservice)
# =============================================================================

# Rust log level filter (trace | debug | info | warn | error)
RUST_LOG=info

# HMAC auth for scraper sidecar (generate with: openssl rand -hex 32)
SCRAPER_HMAC_SECRET=generate-with-openssl-rand-hex-32

# URL of Rust scraper (default: http://localhost:8080)
SCRAPER_SERVICE_URL=http://localhost:8080

# =============================================================================
# dbt (data transforms)
# =============================================================================

# PostgreSQL connection for the stacks_dbt role
DBT_HOST=localhost
DBT_PORT=5432
DBT_USER=stacks_dbt
DBT_PASSWORD=stacks_dbt
DBT_DBNAME=stacks_dev

# Passwords for the stacks_app and stacks_dbt database roles.
# Required when running migrations against hosted databases (e.g. Neon) that enforce
# password strength policies. If not set, role creation is skipped and the application
# connects as the database owner role instead (safe for dev and preview environments).
# Generate with: openssl rand -base64 24
STACKS_APP_DB_PASSWORD=your-strong-password
STACKS_DBT_DB_PASSWORD=your-strong-password

# =============================================================================
# External APIs
# =============================================================================

# Open Library base URL — currently hardcoded in ISBNResolver, not read from env.
# Listed here for reference only.
# OPEN_LIBRARY_BASE_URL=https://openlibrary.org

# Google Books API key — currently hardcoded in ISBNResolver, not read from env.
# Listed here for reference; wire through runtime.exs when API key rotation is needed.
# GOOGLE_BOOKS_API_KEY=your-google-books-api-key

# Brave Search API key for source discovery
BRAVE_SEARCH_API_KEY=your-brave-search-api-key

# =============================================================================
# Fly.io (deployment only — not needed for local dev)
# =============================================================================

# API token for flyctl deployments.
# Must be an org-level token (not a deploy token) so that deploy-preview.sh can
# create and destroy ephemeral apps dynamically.
# Generate with: fly tokens create org --org personal
FLY_API_TOKEN=your-fly-api-token

# =============================================================================
# Neon (preview DB branching — only needed for deploy-preview.sh / CI)
# =============================================================================

# Neon project ID — found in the Neon console under Project Settings.
# Used by deploy-preview.sh to fork a DB branch per PR.
# Obtain from: https://console.neon.tech → your project → Settings → General
NEON_PROJECT_ID=your-neon-project-id

# Neon API key — used to create and delete preview branches via the Neon API.
# Obtain from: https://console.neon.tech → Account → API Keys → New API Key
NEON_API_KEY=your-neon-api-key

# Name of the Neon branch used as parent for preview branches.
# Preview branches inherit this branch's data (fixture data only — no production data).
# Default: staging. See docs/deployment/NEON_BRANCH_TOPOLOGY.md for the branch hierarchy.
NEON_PARENT_BRANCH=staging

# =============================================================================
# SearXNG (federated search — deployed as an internal Fly.io service)
# =============================================================================

# URL of the SearXNG instance. On Fly.io this is the internal hostname; for
# local dev, run SearXNG in Docker and point here (or leave unset to skip search).
SEARXNG_URL=http://localhost:8888

# Secret key for SearXNG's own request signing. Required by deploy-searxng.sh.
# Generate with: openssl rand -hex 32
SEARXNG_SECRET_KEY=generate-with-openssl-rand-hex-32

# =============================================================================
# Replicate
# =============================================================================

REPLICATE_TOKEN=your-replicate-api-token

# =============================================================================
# Email
# =============================================================================

# Set to "resend" to enable real email delivery (via Resend.com)
EMAIL_PROVIDER=resend

# API key for Resend.com transactional email (only if EMAIL_PROVIDER=resend)
RESEND_API_KEY=your-resend-api-key

# =============================================================================
# Rate limiting (optional overrides)
# =============================================================================

# Override default auth rate limit (optional)
# RATE_LIMIT_AUTH=100

# =============================================================================
# Erlang clustering (libcluster)
# =============================================================================
# Shared cookie for Erlang distribution across Fly.io machines.
# Required in production when running multiple machines.
# Set as a Fly secret: fly secrets set RELEASE_COOKIE="$(openssl rand -base64 32)"
# Not needed for local dev (clustering only activates when FLY_APP_NAME is set).
RELEASE_COOKIE=generate-with-openssl-rand-base64-32