From 4d40d8fd3f59303e83d1668c0445cc4260d2bcdd Mon Sep 17 00:00:00 2001 From: Cal Corum Date: Fri, 7 Nov 2025 11:53:23 -0600 Subject: [PATCH] CLAUDE: Add .env.example with comprehensive configuration guide - Documents all environment variables - Includes SQLite and PostgreSQL configurations - Provides example configurations for different environments - Adds security notes and best practices - Includes migration notes for PostgreSQL transition --- .env.example | 175 +++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 175 insertions(+) create mode 100644 .env.example diff --git a/.env.example b/.env.example new file mode 100644 index 0000000..a13d7fd --- /dev/null +++ b/.env.example @@ -0,0 +1,175 @@ +# Paper Dynasty Database API - Environment Configuration +# Copy this file to .env and update with your actual values +# DO NOT commit .env to version control! + +# ============================================================================= +# DATABASE CONFIGURATION +# ============================================================================= + +# Database type: 'sqlite' or 'postgresql' +# Default: sqlite +DATABASE_TYPE=sqlite + +# ----------------------------------------------------------------------------- +# SQLite Configuration (used when DATABASE_TYPE=sqlite) +# ----------------------------------------------------------------------------- +# SQLite uses the file: storage/pd_master.db +# No additional configuration needed for SQLite + +# ----------------------------------------------------------------------------- +# PostgreSQL Configuration (used when DATABASE_TYPE=postgresql) +# ----------------------------------------------------------------------------- + +# PostgreSQL host (hostname or IP address) +# Default: localhost +POSTGRES_HOST=localhost + +# PostgreSQL port +# Default: 5432 +POSTGRES_PORT=5432 + +# PostgreSQL database name +# Default: pd_master +POSTGRES_DB=pd_master + +# PostgreSQL username +# Default: pd_admin +POSTGRES_USER=pd_admin + +# PostgreSQL password (REQUIRED for PostgreSQL, no default) +POSTGRES_PASSWORD=your_secure_password_here + +# ============================================================================= +# APPLICATION CONFIGURATION +# ============================================================================= + +# Logging level: 'INFO' or 'WARN' +# Default: WARN +# Set to INFO for detailed logging during development +LOG_LEVEL=WARN + +# API authentication token +# Used for Bearer token authentication on protected endpoints +# Generate a secure random token for production +API_TOKEN=your_api_token_here + +# Include private endpoints in OpenAPI schema +# Set to any non-empty value to include private endpoints in /docs +# Leave empty or omit to exclude private endpoints +# PRIVATE_IN_SCHEMA=true + +# Testing mode +# Set to 'False' to use development database URL (pddev.manticorum.com) +# Leave unset or set to any other value for production +# TESTING=False + +# ============================================================================= +# EXAMPLE CONFIGURATIONS +# ============================================================================= + +# ----------------------------------------------------------------------------- +# Example 1: Local Development with SQLite (Default) +# ----------------------------------------------------------------------------- +# DATABASE_TYPE=sqlite +# LOG_LEVEL=INFO +# API_TOKEN=dev_token_12345 + +# ----------------------------------------------------------------------------- +# Example 2: Local Development with PostgreSQL +# ----------------------------------------------------------------------------- +# DATABASE_TYPE=postgresql +# POSTGRES_HOST=localhost +# POSTGRES_PORT=5432 +# POSTGRES_DB=pd_master_dev +# POSTGRES_USER=pd_admin +# POSTGRES_PASSWORD=dev_password_123 +# LOG_LEVEL=INFO +# API_TOKEN=dev_token_12345 + +# ----------------------------------------------------------------------------- +# Example 3: Production with PostgreSQL +# ----------------------------------------------------------------------------- +# DATABASE_TYPE=postgresql +# POSTGRES_HOST=db.example.com +# POSTGRES_PORT=5432 +# POSTGRES_DB=pd_master_prod +# POSTGRES_USER=pd_prod_user +# POSTGRES_PASSWORD=strong_random_password_here +# LOG_LEVEL=WARN +# API_TOKEN=prod_secure_token_here + +# ----------------------------------------------------------------------------- +# Example 4: Docker Development with PostgreSQL +# ----------------------------------------------------------------------------- +# DATABASE_TYPE=postgresql +# POSTGRES_HOST=postgres # Docker service name +# POSTGRES_PORT=5432 +# POSTGRES_DB=pd_master +# POSTGRES_USER=pd_admin +# POSTGRES_PASSWORD=docker_dev_password +# LOG_LEVEL=INFO +# API_TOKEN=docker_dev_token + +# ============================================================================= +# SECURITY NOTES +# ============================================================================= +# +# 1. NEVER commit .env files to version control +# - .env is already in .gitignore +# - Only commit .env.example (this file) +# +# 2. Use strong passwords in production +# - Generate random passwords: openssl rand -base64 32 +# - Minimum 20 characters for PostgreSQL password +# +# 3. Rotate API tokens regularly +# - Generate secure tokens: python -c "import secrets; print(secrets.token_urlsafe(32))" +# +# 4. Restrict database access +# - Use firewall rules to limit PostgreSQL access +# - Create separate database users for different environments +# - Grant only necessary privileges +# +# 5. Use environment-specific configurations +# - Development: Relaxed settings, verbose logging +# - Staging: Production-like settings, moderate logging +# - Production: Strict settings, minimal logging +# +# ============================================================================= +# MIGRATION NOTES +# ============================================================================= +# +# When migrating from SQLite to PostgreSQL: +# +# 1. Keep SQLite running during migration +# - Set DATABASE_TYPE=sqlite +# - Application continues to work normally +# +# 2. Set up PostgreSQL +# - Install PostgreSQL server +# - Create database and user +# - Grant privileges +# +# 3. Test PostgreSQL connection +# - Set DATABASE_TYPE=postgresql +# - Set POSTGRES_* variables +# - Test: python -c "from app.db_engine import db; db.connect(); print('✓ Connected'); db.close()" +# +# 4. Run data migration script +# - Use scripts/migrate_sqlite_to_postgres.py +# - Verify data integrity +# - Compare record counts +# +# 5. Switch to PostgreSQL +# - Update .env: DATABASE_TYPE=postgresql +# - Restart application +# - Monitor logs for errors +# +# 6. Rollback plan (if needed) +# - Update .env: DATABASE_TYPE=sqlite +# - Restart application +# - SQLite backup: storage/pd_master_backup_YYYYMMDD.db +# +# See POSTGRES_MIGRATION_PLAN.md for detailed migration instructions +# +# =============================================================================