refactor: Organize and enhance .env.example structure and comments

Author: karlspace

.env.example

@@ -3,61 +3,77 @@
 # ==============================================================================
 # Documentation: https://docs.bugsink.com/
 
-# -- Common Settings --
+# ==============================================================================
+# BASIC SETTINGS
+# ==============================================================================
+
+# -- Stack Identity --
 STACK_NAME=error-observability_app_example_com
 BUGSINK_VERSION=2
-
-TIME_ZONE=UTC
-# -- Site Configuration --
-# Customize your Bugsink instance name
 SITE_TITLE=Error Observability [COMPANY NAME]
+TIME_ZONE=UTC
 
-# -- Database Settings --
-# PostgreSQL 18 with SSD/NVMe tuning
-POSTGRES_VERSION=18
-DATABASE_POOLMAXSIZE=100
-DATABASE_PASSWORD=CHANGE_ME_SECURE_PASSWORD
+# -- Security Secrets --
+# Generate with: openssl rand -base64 50
+SECRET_KEY=GENERATE_WITH_openssl_rand_base64_50
+
+# ==============================================================================
+# NETWORK & PROXY
+# ==============================================================================
 
-# -- Network Settings --
+# -- Hostname --
+# DNS must resolve to this hostname
+SERVICE_HOSTNAME=error-observability.app.example.com
+
+# -- Docker Network --
 # Unique subnet ID (1-254) to avoid conflicts with other stacks
 PRIVATESUBNET=252
+PROXY_NETWORK=traefik
 
-# -- Development Settings --
+# -- Development --
 # Server port for local development (default: 8000)
 DEV_SERVER_PORT=8000
 
-# -- Traefik Proxy Settings --
-# DNS must resolve to ${SERVICE_HOSTNAME}
-SERVICE_HOSTNAME=error-observability.app.example.com
-PROXY_NETWORK=traefik
+# ==============================================================================
+# DATABASE
+# ==============================================================================
 
-# -- Application Secrets --
-# Generate with: openssl rand -base64 50
-SECRET_KEY=GENERATE_WITH_openssl_rand_base64_50
+# PostgreSQL configuration
+POSTGRES_VERSION=18
+DATABASE_POOLMAXSIZE=100
+DATABASE_PASSWORD=CHANGE_ME_SECURE_PASSWORD
+
+# ==============================================================================
+# AUTHENTICATION & USERS
+# ==============================================================================
 
 # -- Initial Admin User --
 # Format: email:password
-# Remove this variable after first start for security
+# IMPORTANT: Remove this variable after first start for security!
 CREATE_SUPERUSER=admin@example.com:CHANGE_ME_SECURE_PASSWORD
 
-# -- User Registration & Permissions --
-# SINGLE_USER=true     -> Disable all multi-user functionality
-# SINGLE_TEAM=true     -> All users share one team
+# -- User Mode --
+# SINGLE_USER=true  -> Disable all multi-user functionality
+# SINGLE_TEAM=true  -> All users share one team
 SINGLE_USER=false
 SINGLE_TEAM=false
 
-# USER_REGISTRATION options:
-#   CB_ANYBODY  -> Anyone can sign up (dangerous on public internet!)
-#   CB_MEMBERS  -> Any existing user can invite new users
-#   CB_ADMINS   -> Only admins can invite new users
-#   CB_NOBODY   -> User registration disabled entirely
+# -- User Registration --
+# Options: CB_ANYBODY  -> Anyone can sign up (dangerous on public internet!)
+#          CB_MEMBERS  -> Any existing user can invite new users
+#          CB_ADMINS   -> Only admins can invite new users
+#          CB_NOBODY   -> User registration disabled entirely
 USER_REGISTRATION=CB_ADMINS
 USER_REGISTRATION_VERIFY_EMAIL=true
 
-# TEAM_CREATION options: CB_MEMBERS, CB_ADMINS, CB_NOBODY
+# -- Team Creation --
+# Options: CB_MEMBERS, CB_ADMINS, CB_NOBODY
 TEAM_CREATION=CB_ADMINS
 
-# -- SMTP Settings --
+# ==============================================================================
+# EMAIL / SMTP
+# ==============================================================================
+
 # Required for notifications and password reset emails
 EMAIL_HOST=smtp.example.com
 EMAIL_PORT=587
@@ -69,23 +85,27 @@ EMAIL_TIMEOUT=5
 DEFAULT_FROM_EMAIL=Error Observability <error-observability@example.com>
 EMAIL_LOGGING=false
 
-# -- Rate Limits & Maximums --
-# Tuned for multi-project instance (~100 projects)
+# ==============================================================================
+# RATE LIMITS & EVENT PROCESSING
+# ==============================================================================
+
+# -- Rate Limits --
 # These are PER PROJECT limits, not global!
 #
 # Sizing guide:
 #   Small  (1-10 projects):   1000/5min,  5000/hour
 #   Medium (10-50 projects):  2500/5min, 15000/hour
 #   Large  (50-200 projects): 2500/5min, 15000/hour (current)
 #   XLarge (200+ projects):   1500/5min, 10000/hour (reduce per-project)
-#
+MAX_EVENTS_PER_PROJECT_PER_5_MINUTES=2500
+MAX_EVENTS_PER_PROJECT_PER_HOUR=15000
+# MAX_EMAILS_PER_MONTH=50000
+
+# -- Event Size Limits --
 # Values in bytes: 1MB=1048576, 2MB=2097152, 20MB=20971520, 100MB=104857600
 MAX_EVENT_SIZE=2097152
 MAX_ENVELOPE_SIZE=104857600
 MAX_ENVELOPE_COMPRESSED_SIZE=20971520
-MAX_EVENTS_PER_PROJECT_PER_5_MINUTES=2500
-MAX_EVENTS_PER_PROJECT_PER_HOUR=15000
-# MAX_EMAILS_PER_MONTH=50000
 
 # -- Background Worker --
 # TASK_ALWAYS_EAGER=true  -> Process inline (dev only)
@@ -94,27 +114,42 @@ MAX_EVENTS_PER_PROJECT_PER_HOUR=15000
 TASK_ALWAYS_EAGER=false
 SNAPPEA_NUM_WORKERS=4
 
-# -- Privacy & Debugging --
+# ==============================================================================
+# PRIVACY & DEBUGGING
+# ==============================================================================
+
 # Disable telemetry to bugsink.com
 PHONEHOME=false
 DEBUG=false
 
+# ==============================================================================
+# QUICK START GUIDE
+# ==============================================================================
+#
+# 1. Copy this file to .env:
+#    cp .env.example .env
 #
-# URLs
-# =====
-# Application -> https://error-observability.app.example.com
+# 2. Update all CHANGE_ME values:
+#    - DATABASE_PASSWORD
+#    - SECRET_KEY (generate with: openssl rand -base64 50)
+#    - CREATE_SUPERUSER
+#    - EMAIL_HOST_PASSWORD
 #
-# Quick Start
-# ===========
-# 1. Copy this file to .env: cp .env.example .env
-# 2. Update all CHANGE_ME values
-# 3. Generate SECRET_KEY: openssl rand -base64 50
-# 4. Adjust SERVICE_HOSTNAME and PRIVATESUBNET
-# 5. Start: docker compose up -d
-# 6. Remove CREATE_SUPERUSER from .env after first login
+# 3. Adjust network settings:
+#    - SERVICE_HOSTNAME
+#    - PRIVATESUBNET
+#
+# 4. Start the stack:
+#    docker compose up -d
+#
+# 5. Remove CREATE_SUPERUSER from .env after first login!
+#
+# ==============================================================================
+# SENTRY SDK INTEGRATION
+# ==============================================================================
 #
-# Sentry SDK Integration
-# ======================
 # DSN Format: https://<project-key>@<hostname>/<project-id>
 # Example:    https://abc123@error-observability.app.example.com/1
 #
+# Application URL: https://error-observability.app.example.com
+#