From dffd4b4f5164d5b4f45123d82427e2288f978330 Mon Sep 17 00:00:00 2001 From: Nikhil Woodruff Date: Mon, 29 Dec 2025 10:48:08 +0000 Subject: [PATCH] docs: improve environment variables documentation - Reorganise .env.example with sections and comprehensive comments - Add Modal secrets setup instructions - Document all required environment variables in README - Update docs/.env.example --- .env.example | 72 +++++++++++++++++++++++++++++++++++++---------- README.md | 21 ++++++++++++++ docs/.env.example | 5 ++++ 3 files changed, 83 insertions(+), 15 deletions(-) diff --git a/.env.example b/.env.example index f7df0fc..80b85f8 100644 --- a/.env.example +++ b/.env.example @@ -1,31 +1,73 @@ -# Local development environment variables -# Copy this to .env and configure for your local setup +# PolicyEngine API v2 - Environment Variables +# Copy this to .env and configure for your environment -# Supabase (local instance via `supabase start`) +# ============================================================================= +# SUPABASE (Database & Storage) +# ============================================================================= +# For local development: run `supabase start` and use the local URLs +# For production: get these from Supabase Dashboard > Settings > API + +# Supabase API URL (NOT the database URL) SUPABASE_URL=http://127.0.0.1:54321 -SUPABASE_KEY=ey... -SUPABASE_SERVICE_KEY=ey... + +# Supabase anon/public key (safe to expose in client) +SUPABASE_KEY=your-anon-key + +# Supabase service role key (server-side only, never expose) +SUPABASE_SERVICE_KEY=your-service-role-key + +# PostgreSQL connection string for direct database access +# For production Supabase: use the "connection string" from Dashboard > Settings > Database +# Format: postgresql://postgres.[project-ref]:[password]@[host]:6543/postgres SUPABASE_DB_URL=postgresql://postgres:postgres@127.0.0.1:54322/postgres -# Storage +# ============================================================================= +# STORAGE +# ============================================================================= +# Supabase storage bucket name for datasets STORAGE_BUCKET=datasets -# API +# ============================================================================= +# API CONFIGURATION +# ============================================================================= API_TITLE=PolicyEngine API API_VERSION=0.1.0 API_PORT=8000 DEBUG=true -# Logfire (get token from https://logfire.pydantic.dev) -LOGFIRE_TOKEN=your-logfire-token-here +# ============================================================================= +# LOGGING (Logfire) +# ============================================================================= +# Get token from https://logfire.pydantic.dev +LOGFIRE_TOKEN= LOGFIRE_ENVIRONMENT=local -# Modal.com (compute backend) -# Get tokens from modal.com dashboard or via `modal token new` -MODAL_TOKEN_ID=ak-... -MODAL_TOKEN_SECRET=as-... - -# Demo agent +# ============================================================================= +# AGENT (Claude Code) +# ============================================================================= +# Anthropic API key for Claude ANTHROPIC_API_KEY=sk-ant-... + +# Whether to use Modal for agent compute (false = run locally) AGENT_USE_MODAL=false + +# PolicyEngine API URL that the agent will use POLICYENGINE_API_URL=http://localhost:8000 + +# ============================================================================= +# MODAL SECRETS (for production) +# ============================================================================= +# Modal secrets are NOT set via .env - they're managed via Modal CLI: +# +# 1. modal secret create policyengine-db \ +# DATABASE_URL='postgresql://...' \ +# SUPABASE_URL='https://...' \ +# SUPABASE_KEY='...' \ +# SUPABASE_SERVICE_KEY='...' \ +# STORAGE_BUCKET='datasets' +# +# 2. modal secret create anthropic-api-key \ +# ANTHROPIC_API_KEY='sk-ant-...' +# +# 3. modal secret create logfire-token \ +# LOGFIRE_TOKEN='...' diff --git a/README.md b/README.md index 27f021a..a960692 100644 --- a/README.md +++ b/README.md @@ -166,6 +166,27 @@ GET /variables List variables GET /health Health check ``` +## Environment variables + +Copy `.env.example` to `.env` and configure. All variables are documented in `.env.example`. + +| Variable | Description | +|----------|-------------| +| `SUPABASE_URL` | Supabase API URL (https://...) | +| `SUPABASE_KEY` | Supabase anon/public key | +| `SUPABASE_SERVICE_KEY` | Supabase service role key | +| `SUPABASE_DB_URL` | PostgreSQL connection string | +| `STORAGE_BUCKET` | Supabase storage bucket name | +| `LOGFIRE_TOKEN` | Logfire observability token | +| `ANTHROPIC_API_KEY` | Anthropic API key for agent | +| `AGENT_USE_MODAL` | Use Modal for agent (true/false) | + +For production Modal deployment, secrets are managed via Modal CLI (not .env): +```bash +modal secret create policyengine-db DATABASE_URL='...' SUPABASE_URL='...' ... +modal secret create anthropic-api-key ANTHROPIC_API_KEY='...' +``` + ## Development ```bash diff --git a/docs/.env.example b/docs/.env.example index 7e98b74..bc8a7d1 100644 --- a/docs/.env.example +++ b/docs/.env.example @@ -1,2 +1,7 @@ # Docs site environment variables +# Copy to .env.local for local development + +# API URL for the docs site to connect to +# Local development: http://localhost:8000 +# Production: https://v2.api.policyengine.org NEXT_PUBLIC_API_URL=http://localhost:8000