.env.example

# ================================================================
# TYPELETS API - ENVIRONMENT CONFIGURATION TEMPLATE
# ================================================================
# This file is for LOCAL DEVELOPMENT AND TESTING ONLY
# Copy this file to `.env` and update with your actual values
# Production deployments use AWS ECS task definitions, not .env files

# ================================================================
# REQUIRED CONFIGURATION
# ================================================================

# Database Connection (REQUIRED)
# For Docker PostgreSQL (recommended for local development):
DATABASE_URL=postgresql://postgres:devpassword@localhost:5432/typelets_local
# For local PostgreSQL installation:
# DATABASE_URL=postgresql://postgres:your_password@localhost:5432/typelets_local
# For production (example):
# DATABASE_URL=postgresql://username:password@hostname:5432/database?sslmode=require

# Valkey Cache (OPTIONAL - for performance optimization)
# VALKEY_HOST=your-cluster.serverless.use1.cache.amazonaws.com
# VALKEY_PORT=6379

# Clerk Authentication (REQUIRED)
# Get your secret key from: https://dashboard.clerk.com/
# For development, use test keys (sk_test_...)
# For production, use live keys (sk_live_...)
CLERK_SECRET_KEY=sk_test_your_actual_clerk_secret_key_from_dashboard

# CORS Origins (REQUIRED)
# Comma-separated list of allowed origins (no spaces after commas)
# Include all frontend domains that will access this API
# If not set, all cross-origin requests will be blocked
CORS_ORIGINS=http://localhost:5173,http://localhost:3000
# Production example:
# CORS_ORIGINS=https://app.typelets.com,https://typelets.com

# ================================================================
# SERVER CONFIGURATION
# ================================================================

# Server Port
PORT=3000

# Environment
NODE_ENV=development

# API URL (for OpenAPI/Swagger documentation)
# This sets the server URL shown in the Swagger docs
# Development (default):
API_URL=http://localhost:3000
# Production example:
# API_URL=https://api.typelets.com

# ================================================================
# SECURITY CONFIGURATION
# ================================================================

# Message Authentication Secret
# Generate with: openssl rand -hex 32
# CRITICAL: Use a strong random string (minimum 32 characters) in production
MESSAGE_AUTH_SECRET=your-very-secure-random-string-here-min-32-chars

# ================================================================
# RATE LIMITING CONFIGURATION
# ================================================================
# Current defaults are development-friendly
# Adjust these values based on your usage patterns

# HTTP API Rate Limiting
# HTTP_RATE_LIMIT_WINDOW_MS=900000    # 15 minutes in milliseconds
# HTTP_RATE_LIMIT_MAX_REQUESTS=1000   # Max requests per window per user/IP
# HTTP_FILE_RATE_LIMIT_MAX=100        # Max file operations per window

# Production Rate Limiting Recommendations:
# - HTTP: 500-1000 requests per 15 minutes per user
# - File uploads: 50-100 operations per 15 minutes per user

# ================================================================
# FILE UPLOAD CONFIGURATION
# ================================================================

# File Size Limits
MAX_FILE_SIZE_MB=50# Maximum size per file (default: 50MB)
# MAX_NOTE_SIZE_MB=1024               # Maximum total attachments per note (default: 1GB)

# Allowed File Types (handled in code, documented here)
# Images: JPEG, PNG, GIF, WebP
# Documents: PDF, Plain Text, Markdown, JSON, CSV
# Add new types in: src/lib/validation.ts

# ================================================================
# CODE EXECUTION CONFIGURATION (Self-hosted Piston)
# ================================================================

# Piston API Configuration (OPTIONAL - for code execution features)
# Self-hosted Piston: https://github.com/engineer-man/piston
# Run with Docker: docker run -d --name piston -p 2000:2000 ghcr.io/engineer-man/piston
# PISTON_API_URL=http://localhost:2000

# Code execution rate limits
# CODE_EXEC_RATE_LIMIT_MAX=50         # Max code executions per 15 minutes per user

# ================================================================
# BILLING & LIMITS CONFIGURATION
# ================================================================

# Free Tier Limits
FREE_TIER_STORAGE_GB=1# Storage limit for free users (default: 1GB)
FREE_TIER_NOTE_LIMIT=100# Note count limit for free users (default: 100)

# Usage tracking for billing analytics
# These limits trigger billing events logged to console
# Upgrade prompts and enforcement handled in frontend

# ================================================================
# LOGGING & MONITORING
# ================================================================

# Grafana Cloud with OpenTelemetry (OPTIONAL - for observability)
# Get your Grafana Cloud configuration from: https://grafana.com/products/cloud/
# 1. Sign up for Grafana Cloud (free tier available)
# 2. Go to Connections > Add new connection > OpenTelemetry
# 3. Copy the export commands provided (they will look like the examples below)
# 4. Set the environment variables in your deployment

# OpenTelemetry Configuration (via Grafana Alloy)
# IMPORTANT: Logs/traces/metrics are sent to local Grafana Alloy, which forwards to Grafana Cloud
# For local dev: docker-compose -f docker-compose.alloy.yml up -d
# For production: Run Alloy as ECS sidecar container (see docker-compose.alloy.yml)

# OTEL Configuration - Point to Alloy (localhost for both dev and prod sidecar)
# OTEL_EXPORTER_OTLP_ENDPOINT=http://localhost:4318
# OTEL_EXPORTER_OTLP_PROTOCOL=http/protobuf
# OTEL_TRACES_EXPORTER=otlp
# OTEL_METRICS_EXPORTER=otlp
# OTEL_LOGS_EXPORTER=otlp
# OTEL_NODE_RESOURCE_DETECTORS=env,host,os
# OTEL_SERVICE_NAME=typelets-api
# OTEL_RESOURCE_ATTRIBUTES=deployment.environment=production,service.name=typelets-api

# Grafana Cloud Configuration (required for Alloy container, NOT in app)
# Get these from Grafana Cloud: Connections > Add new connection > OpenTelemetry
# GRAFANA_CLOUD_ENDPOINT=your_otlp_gateway_endpoint_here
# GRAFANA_CLOUD_INSTANCE_ID=your_instance_id_here
# GRAFANA_CLOUD_TOKEN=your_grafana_cloud_token_here

# Application Logging
# Structured JSON logs are automatically generated for:
# - Authentication events
# - Rate limiting violations
# - Security events (failed auth, suspicious activity)
# - Billing limit violations
# - File upload events
# - HTTP requests and responses
# - Database queries
# - Cache operations

# When OpenTelemetry is configured, logs, traces, and metrics are sent to Grafana Cloud
# Features include:
# - Distributed tracing across services
# - Automatic instrumentation for HTTP, PostgreSQL, Redis
# - Custom business metrics and events
# - Performance monitoring and profiling
# - Log aggregation and search

# ================================================================
# DEVELOPMENT HELPERS
# ================================================================

# Database Development
# Run with Docker: docker run --name typelets-postgres -e POSTGRES_PASSWORD=devpassword -p 5432:5432 -d postgres:15
# Connect: psql postgresql://postgres:devpassword@localhost:5432/typelets_local

# Frontend Development URLs
# Vite dev server: http://localhost:5173
# Next.js dev server: http://localhost:3000
# React dev server: http://localhost:3000

# API Testing
# Health check: GET http://localhost:3000/health
# API documentation: https://github.com/typelets/typelets-api

# ================================================================
# SECURITY NOTES
# ================================================================

# 🔒 NEVER commit actual secrets to version control
# 🔒 Use different secrets for development and production
# 🔒 Rotate secrets regularly in production
# 🔒 MESSAGE_AUTH_SECRET is critical for message authentication
# 🔒 CLERK_SECRET_KEY controls all authentication
# 🔒 DATABASE_URL contains database credentials

# Generate secure secrets:
# MESSAGE_AUTH_SECRET: openssl rand -hex 32
# API Keys: Use your service provider's dashboard
# Database passwords: Use password managers

# Piston Setup (Self-hosted code execution):
# 1. Run Piston with Docker: docker run -d --name piston -p 2000:2000 ghcr.io/engineer-man/piston
# 2. Set PISTON_API_URL=http://localhost:2000
# 3. Code execution endpoints will be available: /api/code/*
# See: https://github.com/engineer-man/piston

# ================================================================
# PRODUCTION DEPLOYMENT NOTES
# ================================================================

# AWS ECS Deployment:
# - Environment variables are set in ECS task definitions
# - Secrets are managed via AWS Secrets Manager
# - This .env file is NOT used in production
# - SSL/TLS termination handled by Application Load Balancer
# - Database connections use IAM authentication or managed secrets

# Docker Production:
# - Pass environment variables via docker run -e or docker-compose
# - Mount secrets as files or use Docker secrets
# - Never build secrets into Docker images

# Kubernetes Deployment:
# - Use ConfigMaps for non-sensitive configuration
# - Use Secrets for sensitive data (base64 encoded)
# - Consider external secret management (HashiCorp Vault, etc.)

# ================================================================
# TROUBLESHOOTING
# ================================================================

# Common Issues:
# 1. "Database connection failed" → Check DATABASE_URL and database status
# 2. "Authentication failed" → Verify CLERK_SECRET_KEY is correct
# 3. "CORS error" → Add your frontend URL to CORS_ORIGINS
# 4. "Too many requests" → Increase rate limits or check for loops

# Useful Commands:
# Check database connection: npx drizzle-kit studio
# Test API endpoints: curl http://localhost:3000/health
# Monitor logs: tail -f logs/app.log (if file logging enabled)
# Generate new secrets: openssl rand -hex 32

# Support:
# Documentation: https://github.com/typelets/typelets-api
# Issues: https://github.com/typelets/typelets-api/issues