atbb / .env.production.example

# ============================================================================
# atBB Production Environment Configuration
# ============================================================================
# Copy this file to .env.production and fill in your actual values.
# NEVER commit .env.production with real secrets to version control!
#
# After copying:
#   1. Generate SESSION_SECRET: openssl rand -hex 32
#   2. Fill in your AT Protocol credentials (FORUM_DID, PDS_URL, etc.)
#   3. Set strong passwords for FORUM_PASSWORD and database
#   4. Update URLs to match your deployment domain
#   5. Restrict file permissions: chmod 600 .env.production
#
# Security note: This file contains sensitive credentials. Protect it like
# you would protect SSH keys or API tokens.
# ============================================================================

# ============================================================================
# Database Configuration
# ============================================================================
# PostgreSQL connection string
# Format: postgresql://username:password@hostname:port/database
#
# Production example (managed PostgreSQL):
#   DATABASE_URL=postgresql://atbb_prod:S3cureP@[e-mail]:5432/atbb_prod
#
# Docker Compose example (container name as hostname):
#   DATABASE_URL=postgresql://atbb:changeme@postgres:5432/atbb
#
# Notes:
#   - Use strong passwords (minimum 16 characters, alphanumeric + symbols)
#   - Enable SSL/TLS in production: ?sslmode=require
#   - Consider connection pooling for high traffic
DATABASE_URL=postgresql://atbb_user:[e-mail]:5432/atbb_production

# ============================================================================
# AT Protocol Configuration
# ============================================================================
# These settings connect your forum to the AT Protocol network (Bluesky/atproto).

# Forum's Decentralized Identifier (DID)
# This is your forum's unique identity on the AT Protocol network.
# Get this after creating your forum account on a PDS.
#
# Example: did:plc:abcdef1234567890
# Production: Use your actual forum DID from your PDS
FORUM_DID=did:plc:CHANGE_ME_YOUR_FORUM_DID

# Personal Data Server URL
# The PDS where your forum's records are stored.
# This can be your own PDS instance or a hosted service.
#
# Examples:
#   - Self-hosted: https://pds.yourdomain.com
#   - Bluesky PDS: https://bsky.social
PDS_URL=https://pds.example.com

# ============================================================================
# Application URLs
# ============================================================================
# These URLs determine how services communicate and handle OAuth.

# Public URL where your forum is accessible to users
# Used for OAuth redirect URIs and client_id generation.
# MUST be HTTPS in production (HTTP only for local development).
#
# Examples:
#   - Production: https://forum.example.com
#   - Staging: https://staging.forum.example.com
OAUTH_PUBLIC_URL=https://forum.example.com

# Internal URL for web service to reach appview API
# In single-container deployments: http://localhost:3000
# In multi-container deployments: http://appview:3000 (Docker service name)
# In Kubernetes: http://appview-service:3000
#
# Notes:
#   - Use container/service names, not external domains
#   - HTTP is fine for internal communication (encrypted at network layer)
#   - Must be reachable from web service container
APPVIEW_URL=http://localhost:3000

# ============================================================================
# Session Management
# ============================================================================
# Session security is critical for protecting user accounts.

# Secret key for encrypting and signing session cookies
# CRITICAL: Generate a strong random value, never use the default!
#
# Generate with: openssl rand -hex 32
#
# Security requirements:
#   - Minimum 32 bytes (64 hex characters)
#   - Use cryptographically secure random generation
#   - Unique per environment (dev, staging, production)
#   - Never commit to version control
#   - Rotate periodically (invalidates all active sessions)
#
# Example output from openssl:
#   a1b2c3d4e5f6789012345678901234567890abcdef1234567890abcdef123456
SESSION_SECRET=

# ============================================================================
# Service Ports (Optional)
# ============================================================================
# Override default ports if needed for your deployment environment.
# Most deployments can use the defaults.

# AppView API server port (default: 3000)
# This is the internal port the appview service listens on.
# PORT=3000
# WEB_PORT=3001

# Note: In the Docker container, nginx listens on port 80 and proxies to both services.

# ============================================================================
# AT Protocol Features (Optional)
# ============================================================================
# Advanced AT Protocol configuration.

# Jetstream firehose URL for real-time updates
# Receives live events from the AT Protocol network to keep your forum
# synchronized with user posts and profile changes.
#
# Default: wss://jetstream2.us-east.bsky.network/subscribe
#
# Notes:
#   - Uses WebSocket (wss://) for real-time streaming
#   - Alternative endpoints available for different regions
#   - Required for live post indexing
# JETSTREAM_URL=wss://jetstream2.us-east.bsky.network/subscribe

# ============================================================================
# Session Configuration (Optional)
# ============================================================================
# Fine-tune session behavior for your deployment.

# Session cookie TTL (Time To Live) in days
# How long users stay logged in before requiring re-authentication.
#
# Default: 7 days
# Recommended ranges:
#   - High security: 1-7 days (default)
#   - Balanced: 14-30 days
#   - Convenience: 90 days
#
# Notes:
#   - Shorter TTL = more secure, more logins required
#   - Longer TTL = less secure, better user experience
#   - Consider your forum's security requirements
# SESSION_TTL_DAYS=7

# Redis session storage (optional, for multi-instance deployments)
# If set, sessions are stored in Redis instead of memory.
# Required for horizontal scaling (multiple appview instances).
#
# Format: redis://[username]:[password]@hostname:port/database
#
# Examples:
#   - Local Redis: redis://localhost:6379
#   - Docker Compose: redis://redis:6379
#   - Managed Redis: redis://default:[e-mail]:6379/0
#
# Notes:
#   - Leave blank/commented for single-instance deployments (uses in-memory)
#   - Required for multi-instance deployments (shared session state)
#   - Supports Redis Cluster and Sentinel configurations
# REDIS_URL=redis://redis:6379

# ============================================================================
# Security Checklist
# ============================================================================
# Before deploying to production, verify:
#
# [ ] Generated SESSION_SECRET with: openssl rand -hex 32
# [ ] Used strong, unique passwords (minimum 16 characters)
# [ ] Never committed .env.production to version control
# [ ] Set file permissions: chmod 600 .env.production
# [ ] All URLs use HTTPS (except APPVIEW_URL for internal communication)
# [ ] Database connection uses SSL/TLS (?sslmode=require)
# [ ] Forum account password is unique (not reused)
# [ ] SESSION_SECRET is different from dev/staging environments
# [ ] Documented secret rotation schedule (every 90 days recommended)
# [ ] Tested OAuth flow with OAUTH_PUBLIC_URL
# [ ] Verified APPVIEW_URL is reachable from web service
# [ ] Reviewed firewall rules (only expose necessary ports)
#
# ============================================================================
# Deployment Notes
# ============================================================================
#
# Single Container Deployment (appview + web in same container):
#   - Use APPVIEW_URL=http://localhost:3000
#   - No Redis required (in-memory sessions OK)
#   - Simpler setup, suitable for small forums
#
# Multi Container Deployment (separate appview and web containers):
#   - Use APPVIEW_URL=http://appview:3000 (Docker service name)
#   - Consider Redis for session storage
#   - Better scalability, suitable for larger forums
#
# Kubernetes Deployment:
#   - Use APPVIEW_URL=http://appview-service:3000
#   - Redis highly recommended for multi-replica deployments
#   - Use Secrets for sensitive values (not ConfigMaps)
#
# Environment Variable Loading:
#   - Docker: Use --env-file flag or docker-compose env_file
#   - Kubernetes: Mount as Secret or use external-secrets
#   - Systemd: Use EnvironmentFile=/path/to/.env.production
#   - Node.js: Use --env-file flag (Node 20.6+)
#
# ============================================================================
# Troubleshooting
# ============================================================================
#
# "Database connection failed":
#   - Verify DATABASE_URL is correct and accessible
#   - Check network connectivity to database host
#   - Ensure database exists and user has permissions
#   - Enable SSL if required by your database provider
#
# "OAuth redirect URI mismatch":
#   - Verify OAUTH_PUBLIC_URL matches your actual domain
#   - Must use HTTPS in production (not HTTP)
#   - Check for trailing slashes (should not have one)
#
# "Session errors / users logged out randomly":
#   - Verify SESSION_SECRET is set (not blank)
#   - For multi-instance: must use Redis (set REDIS_URL)
#   - Check SESSION_TTL_DAYS is reasonable (default 7)
#
# "Cannot reach appview API":
#   - Verify APPVIEW_URL uses correct hostname
#   - In Docker: use service name, not localhost
#   - Check container/service networking configuration
#
# ============================================================================