1- # LOCAL DEVELOPMENT AND TESTING ENVIRONMENT VARIABLES
2- # This file is ONLY for local development and testing
3- # Copy this file to .env and update with your local testing values
1+ # ================================================================
2+ # TYPELETS API - ENVIRONMENT CONFIGURATION TEMPLATE
3+ # ================================================================
4+ # This file is for LOCAL DEVELOPMENT AND TESTING ONLY
5+ # Copy this file to `.env` and update with your actual values
6+ # Production deployments use AWS ECS task definitions, not .env files
47
5- # Database connection for local testing
6- # For Docker PostgreSQL (recommended for testing):
8+ # ================================================================
9+ # REQUIRED CONFIGURATION
10+ # ================================================================
11+
12+ # Database Connection (REQUIRED)
13+ # For Docker PostgreSQL (recommended for local development):
714DATABASE_URL = postgresql://postgres:devpassword@localhost:5432/typelets_local
815# For local PostgreSQL installation:
916# DATABASE_URL=postgresql://postgres:your_password@localhost:5432/typelets_local
17+ # For production (example):
18+ # DATABASE_URL=postgresql://username:password@hostname:5432/database?sslmode=require
1019
11- # Clerk authentication for local testing (get from https://dashboard.clerk.com)
20+ # Clerk Authentication (REQUIRED)
21+ # Get your secret key from: https://dashboard.clerk.com/
22+ # For development, use test keys (sk_test_...)
23+ # For production, use live keys (sk_live_...)
1224CLERK_SECRET_KEY = sk_test_your_actual_clerk_secret_key_from_dashboard
1325
14- # CORS configuration - REQUIRED
15- # Comma-separated list of allowed origins
26+ # CORS Origins (REQUIRED)
27+ # Comma-separated list of allowed origins (no spaces after commas)
28+ # Include all frontend domains that will access this API
1629CORS_ORIGINS = http://localhost:5173,http://localhost:3000
30+ # Production example:
31+ # CORS_ORIGINS=https://app.typelets.com,https://typelets.com
32+
33+ # ================================================================
34+ # SERVER CONFIGURATION
35+ # ================================================================
1736
18- # Optional settings (have sensible defaults)
37+ # Server Port
1938PORT = 3000
39+
40+ # Environment
2041NODE_ENV = development
2142
22- # File upload configuration
23- # MAX_FILE_SIZE_MB=50 # Maximum size per file in MB (default: 50)
24- # MAX_NOTE_SIZE_MB=1024 # Maximum total attachments per note in MB (default: 1024MB = 1GB)
43+ # ================================================================
44+ # SECURITY CONFIGURATION
45+ # ================================================================
46+
47+ # WebSocket Message Authentication
48+ # Generate with: openssl rand -hex 32
49+ # CRITICAL: Use a strong random string (minimum 32 characters) in production
50+ MESSAGE_AUTH_SECRET = your-very-secure-random-string-here-min-32-chars
51+
52+ # ================================================================
53+ # RATE LIMITING CONFIGURATION
54+ # ================================================================
55+ # Current defaults are development-friendly
56+ # Adjust these values based on your usage patterns
57+
58+ # HTTP API Rate Limiting
59+ # HTTP_RATE_LIMIT_WINDOW_MS=900000 # 15 minutes in milliseconds
60+ # HTTP_RATE_LIMIT_MAX_REQUESTS=1000 # Max requests per window per user/IP
61+ # HTTP_FILE_RATE_LIMIT_MAX=100 # Max file operations per window
62+
63+ # WebSocket Rate Limiting
64+ WS_RATE_LIMIT_WINDOW_MS = 60000 # Time window: 1 minute (in milliseconds)
65+ WS_RATE_LIMIT_MAX_MESSAGES = 300 # Max messages per window per connection
66+ WS_MAX_CONNECTIONS_PER_USER = 20 # Max concurrent connections per user
67+ WS_AUTH_TIMEOUT_MS = 30000 # Authentication timeout: 30 seconds
68+
69+ # Production Rate Limiting Recommendations:
70+ # - HTTP: 500-1000 requests per 15 minutes per user
71+ # - WebSocket: 100-300 messages per minute per connection
72+ # - File uploads: 50-100 operations per 15 minutes per user
73+ # - Connections: 10-20 per user depending on multi-device usage
74+
75+ # ================================================================
76+ # FILE UPLOAD CONFIGURATION
77+ # ================================================================
78+
79+ # File Size Limits
80+ MAX_FILE_SIZE_MB = 50 # Maximum size per file (default: 50MB)
81+ # MAX_NOTE_SIZE_MB=1024 # Maximum total attachments per note (default: 1GB)
82+
83+ # Allowed File Types (handled in code, documented here)
84+ # Images: JPEG, PNG, GIF, WebP
85+ # Documents: PDF, Plain Text, Markdown, JSON, CSV
86+ # Add new types in: src/lib/validation.ts
87+
88+ # ================================================================
89+ # BILLING & LIMITS CONFIGURATION
90+ # ================================================================
91+
92+ # Free Tier Limits
93+ FREE_TIER_STORAGE_GB = 1 # Storage limit for free users (default: 1GB)
94+ FREE_TIER_NOTE_LIMIT = 100 # Note count limit for free users (default: 100)
95+
96+ # Usage tracking for billing analytics
97+ # These limits trigger billing events logged to console
98+ # Upgrade prompts and enforcement handled in frontend
99+
100+ # ================================================================
101+ # LOGGING & MONITORING
102+ # ================================================================
103+
104+ # Debug Logging
105+ # DEBUG=false # Set to true for verbose logging (not recommended in production)
106+
107+ # Application Logging
108+ # Structured logs are automatically generated for:
109+ # - Authentication events
110+ # - Rate limiting violations
111+ # - Security events (failed auth, suspicious activity)
112+ # - Billing limit violations
113+ # - WebSocket connection events
114+ # - File upload events
115+
116+ # ================================================================
117+ # DEVELOPMENT HELPERS
118+ # ================================================================
119+
120+ # Database Development
121+ # Run with Docker: docker run --name typelets-postgres -e POSTGRES_PASSWORD=devpassword -p 5432:5432 -d postgres:15
122+ # Connect: psql postgresql://postgres:devpassword@localhost:5432/typelets_local
123+
124+ # Frontend Development URLs
125+ # Vite dev server: http://localhost:5173
126+ # Next.js dev server: http://localhost:3000
127+ # React dev server: http://localhost:3000
128+
129+ # API Testing
130+ # Health check: GET http://localhost:3000/health
131+ # WebSocket status: GET http://localhost:3000/websocket/status
132+ # API documentation: https://github.com/typelets/typelets-api
133+
134+ # ================================================================
135+ # SECURITY NOTES
136+ # ================================================================
137+
138+ # 🔒 NEVER commit actual secrets to version control
139+ # 🔒 Use different secrets for development and production
140+ # 🔒 Rotate secrets regularly in production
141+ # 🔒 MESSAGE_AUTH_SECRET is critical for WebSocket security
142+ # 🔒 CLERK_SECRET_KEY controls all authentication
143+ # 🔒 DATABASE_URL contains database credentials
144+
145+ # Generate secure secrets:
146+ # MESSAGE_AUTH_SECRET: openssl rand -hex 32
147+ # API Keys: Use your service provider's dashboard
148+ # Database passwords: Use password managers
149+
150+ # ================================================================
151+ # PRODUCTION DEPLOYMENT NOTES
152+ # ================================================================
153+
154+ # AWS ECS Deployment:
155+ # - Environment variables are set in ECS task definitions
156+ # - Secrets are managed via AWS Secrets Manager
157+ # - This .env file is NOT used in production
158+ # - SSL/TLS termination handled by Application Load Balancer
159+ # - Database connections use IAM authentication or managed secrets
160+
161+ # Docker Production:
162+ # - Pass environment variables via docker run -e or docker-compose
163+ # - Mount secrets as files or use Docker secrets
164+ # - Never build secrets into Docker images
165+
166+ # Kubernetes Deployment:
167+ # - Use ConfigMaps for non-sensitive configuration
168+ # - Use Secrets for sensitive data (base64 encoded)
169+ # - Consider external secret management (HashiCorp Vault, etc.)
170+
171+ # ================================================================
172+ # TROUBLESHOOTING
173+ # ================================================================
25174
26- # Free tier limits for billing
27- # FREE_TIER_STORAGE_GB=1 # Storage limit in GB for free tier (default: 1)
28- # FREE_TIER_NOTE_LIMIT=100 # Note count limit for free tier (default: 100)
175+ # Common Issues:
176+ # 1. "Database connection failed" → Check DATABASE_URL and database status
177+ # 2. "Authentication failed" → Verify CLERK_SECRET_KEY is correct
178+ # 3. "CORS error" → Add your frontend URL to CORS_ORIGINS
179+ # 4. "Too many requests" → Increase rate limits or check for loops
180+ # 5. "WebSocket connection failed" → Check authentication and rate limits
29181
30- # Debug logging
31- # DEBUG=false # Set to true to enable debug logging in production
182+ # Useful Commands:
183+ # Check database connection: npx drizzle-kit studio
184+ # Test API endpoints: curl http://localhost:3000/health
185+ # Monitor logs: tail -f logs/app.log (if file logging enabled)
186+ # Generate new secrets: openssl rand -hex 32
32187
33- # IMPORTANT: This .env file is for LOCAL TESTING ONLY
34- # Production uses AWS ECS task definitions, not .env files
188+ # Support:
189+ # Documentation: https://github.com/typelets/typelets-api
190+ # Issues: https://github.com/typelets/typelets-api/issues
0 commit comments