.env.example

# ============================================================================
# Root - Unified Environment Configuration
# ============================================================================
# Copy this file to `.env` in the project root and fill in the values.
# All services (Go API, Python RAG, Frontend) can share this single file.
#
# Quick Start (Local Development):
# 1. Copy this file: cp .env.example .env
# 2. Set DATABASE_URL (PostgreSQL connection)
# 3. Set API keys for AI services (optional, disables features if not set)
# 4. Set RAG_MICROSERVICE_SECRET for Go <-> Python authentication
# 5. Run: docker-compose -f docker-compose.rag.yml up
# ============================================================================

# ----------------------------------------------------------------------------
# SHARED: Database (REQUIRED for all services)
# ----------------------------------------------------------------------------
# PostgreSQL connection string
# Format: postgres://user:password@host:port/database?sslmode=mode
#
# Go API uses: postgres://...
# Python RAG uses: postgresql+asyncpg://... (auto-converted)
#
# Production: Use sslmode=require
# Development: Use sslmode=disable
DATABASE_URL=postgres://postgres:password@localhost:5432/db?sslmode=disable

# Test database (for Go integration tests only)
TEST_DATABASE_URL=postgres://postgres:password@localhost:5432/railway_test?sslmode=disable

# ----------------------------------------------------------------------------
# SHARED: AI Services (OPTIONAL - features disabled if not set)
# ----------------------------------------------------------------------------
# Used by: Go API (embedding worker), Python RAG service

# Voyage AI - For embeddings and reranking
# Get API key from: https://www.voyageai.com/
EMBEDDING_API_KEY=

# OpenAI - For LLM generation
# Get API key from: https://platform.openai.com/
LLM_API_KEY=

# AssemblyAI - For podcast transcription
# Get API key from: https://www.assemblyai.com/
ASSEMBLYAI_API_KEY=

# Cloudflare R2 - For transcript storage
# Bucket naming: {APP_ENV}_root (e.g., localhost_root, dev_root, prod_root)
# Get credentials from Cloudflare dashboard: https://dash.cloudflare.com/
R2_ACCOUNT_ID=
R2_ACCESS_KEY_ID=
R2_SECRET_ACCESS_KEY=
R2_BUCKET_NAME=local-root
R2_ENDPOINT_URL=https://<account_id>.r2.cloudflarestorage.com
# Public URL pattern for accessing transcripts (optional, can be R2 bucket URL or custom domain)
R2_PUBLIC_URL_BASE=https://pub-<bucket_id>.r2.dev

# YouTube Proxy - For yt-dlp transcript fetching (via youtube-transcript-api)
# Used by: Python RAG service
# Get credentials from a proxy provider like Webshare: https://www.webshare.io/
YOUTUBE_PROXY_USERNAME=
YOUTUBE_PROXY_PASSWORD=
# Optional: Specify proxy country code (e.g., "US", "CA", "GB")
YOUTUBE_PROXY_COUNTRY=

# ----------------------------------------------------------------------------
# SHARED: RAG Service Integration (REQUIRED if using Python RAG service)
# ----------------------------------------------------------------------------
# Used by: Go API (proxy), Python RAG service (auth validation)

# Python RAG microservice URL
# Local: http://localhost:8081
# Docker: http://rag-service:8081
FAST_API_URL=http://localhost:8081

# Shared secret for HMAC authentication between Go and Python
# IMPORTANT: Must be the same in both services
# Generate a strong random value: openssl rand -hex 32
RAG_MICROSERVICE_SECRET=your-shared-secret-between-go-and-python

# ----------------------------------------------------------------------------
# GO API: Authentication & Frontend (REQUIRED for Go API)
# ----------------------------------------------------------------------------
# Used by: Go API only

# Next.js frontend URL where Better-Auth is running
# The Go backend fetches public keys from {FRONTEND_URL}/api/auth/jwks
# Production: https://yourapp.com
# Development: http://localhost:3000
FRONTEND_URL=http://localhost:3000

# ----------------------------------------------------------------------------
# GO API: Application Configuration
# ----------------------------------------------------------------------------
# Used by: Go API only

# Server port
PORT=8080

# Environment: localhost, dev, staging, production
APP_ENV=localhost

# Automatically run database migrations on startup (default: true)
# Set to false in production if you prefer manual migration control
AUTO_MIGRATE=true

# Seed database with test data on startup (for development only)
SEED_DB=false

# Admin credentials for seeding (optional)
# ADMIN_EMAIL=admin@example.com
# ADMIN_PASSWORD=changeme

# Basic auth for monitoring endpoints (optional)
# MONITORING_USERNAME=admin
# MONITORING_PASSWORD=secret

# Legacy JWT secret (deprecated - JWKS is used for validation)
# JWT_SECRET=your-secret-key

# ----------------------------------------------------------------------------
# GO API: OpenTelemetry (OPTIONAL)
# ----------------------------------------------------------------------------
# Used by: Go API only

# Enable OpenTelemetry traces and metrics
OTEL_ENABLED=false

# OTLP gRPC endpoint for traces and metrics
# Examples:
#   - Local collector: localhost:4317
#   - Grafana Cloud: otlp-gateway-prod-us-central-0.grafana.net:443
OTEL_EXPORTER_OTLP_ENDPOINT=localhost:4317

# Service identification
OTEL_SERVICE_NAME=root-api
OTEL_SERVICE_VERSION=0.1.0

# Protocol: grpc or http/protobuf
OTEL_EXPORTER_OTLP_PROTOCOL=grpc

# TLS Configuration
# Use insecure connection (no TLS) - set to false in production
OTEL_EXPORTER_OTLP_INSECURE=true

# Optional: Path to client certificate for mTLS
# OTEL_EXPORTER_OTLP_CERTIFICATE=/path/to/cert.pem

# Optional: Path to CA certificate for server verification
# OTEL_EXPORTER_OTLP_CA_CERTIFICATE=/path/to/ca.pem

# Optional: Custom headers (comma-separated key=value)
# OTEL_EXPORTER_OTLP_HEADERS=

# ----------------------------------------------------------------------------
# PYTHON RAG: Server Configuration
# ----------------------------------------------------------------------------
# Used by: Python RAG service only

# Server port (default: 8081)
# PORT=8081

# Log level: DEBUG, INFO, WARNING, ERROR
LOG_LEVEL=INFO

# CORS origins (JSON array)
CORS_ORIGINS=["http://localhost:3000"]

# ----------------------------------------------------------------------------
# PYTHON RAG: RAG Algorithm Parameters (Advanced - Rarely Changed)
# ----------------------------------------------------------------------------
# Used by: Python RAG service only
# These have sensible defaults in code. Only set if you need to tune RAG behavior.

# VEC_K_PER_KIND=30          # Vector search results per kind (citations/captures)
# FTS_K_PER_KIND=30          # Full-text search results per kind
# FINAL_K=20                 # Final number of results after RRF merging
# RRF_K=60                   # RRF constant (higher = more weight to lower ranks)
# MAX_LLM_CHUNKS=20          # Max chunks sent to LLM

# ----------------------------------------------------------------------------
# FRONTEND: API Configuration (OPTIONAL)
# ----------------------------------------------------------------------------
# Used by: Frontend only

# Unified API URL for both Go and Fast API (when behind nginx)
# Local dev: Leave empty (defaults to localhost:8080 for Go, localhost:8081 for Fast API)
# Docker dev: http://localhost:8000 (nginx on port 8000)
# Production: https://api.yourapp.com or empty for same-origin
API_URL=

# ============================================================================
# Deployment Configurations
# ============================================================================
#
# Local Development (docker-compose.local.yml with nginx):
# - DATABASE_URL: postgres://postgres:password@postgres:5432/db
# - FAST_API_URL: http://rag-service:8081
# - FRONTEND_URL: http://localhost:3000
# - API_URL: http://localhost:8000  (nginx on port 8000)
# - Set AI API keys to enable features
#
# Local Development (without docker - separate services):
# - DATABASE_URL: postgres://postgres:password@localhost:5432/db
# - FAST_API_URL: http://localhost:8081
# - FRONTEND_URL: http://localhost:3000
# - API_URL: (empty - defaults to localhost:8080 for Go, localhost:8081 for Fast API)
# - Set AI API keys to enable features
#
# Production (Dokploy/Railway/Cloud):
# 1. Set DATABASE_URL to your managed PostgreSQL instance
# 2. Set FRONTEND_URL to your deployed Next.js URL (https://yourapp.com)
# 3. Set FAST_API_URL to Python service URL (internal or external)
# 4. Set API_URL to nginx/API gateway URL (https://api.yourapp.com) or empty for same-origin
# 5. Set AUTO_MIGRATE=true for automatic migrations
# 6. Set APP_ENV=production
# 7. Generate strong RAG_MICROSERVICE_SECRET: openssl rand -hex 32
# 8. Optional: Enable OTEL for observability
# 9. Optional: Configure LLM/Embedding providers for AI features
#
# Security Checklist:
# - Use strong, unique secrets for production
# - Enable SSL for DATABASE_URL (sslmode=require)
# - Use HTTPS for FRONTEND_URL, FAST_API_URL, and API_URL
# - Store secrets securely (Dokploy secrets, Railway variables, etc.)
# - Never commit .env files to version control
# - Rotate RAG_MICROSERVICE_SECRET periodically
#
# Service Dependencies:
# - Go API depends on: DATABASE_URL, FRONTEND_URL, (optional) FAST_API_URL
# - Python RAG depends on: DATABASE_URL, RAG_MICROSERVICE_SECRET, AI API keys
# - Frontend depends on: (optional) API_URL
#
# ============================================================================