.env.example

# =============================================================================
# Environment Variables Example - Master Template
# =============================================================================
# Copy this file to .env.development or .env.production and update with your values
#
# For Development:
#   cp .env.example .env.development
#
# For Production:
#   cp .env.example .env.production
#
# NOTE: When running via Docker Compose (make up-dev / make up-prod),
#       ONLY root .env files are used. Package-level .env files are ignored.
#
# =============================================================================
# ENVIRONMENT FILE MAPPING
# =============================================================================
# | Docker Compose File        | Environment File   | Usage                                            |
# | -------------------------- | ------------------ | ------------------------------------------------ |
# | docker-compose.prod.yml   | .env.production    | Production deployment                            |
# | docker-compose.dev.yml    | .env.development   | Docker development (all services in containers)  |
# | docker-compose.local.yml  | .env.local         | Local development (infra in Docker, apps native) |
#
# =============================================================================
# IMPORTANT DIFFERENCES: .env.development vs .env.local
# =============================================================================
# .env.development (Docker Development):
#   - Uses Docker service names for inter-container communication:
#     * SERVER_RESTAPI_URL=http://rest-api:4000/api (Docker service name)
#     * REDIS_HOST=redis (Docker service name)
#     * DATABASE_URL is set by Docker Compose (not in file)
#
# .env.local (Local Development):
#   - Uses localhost for native apps connecting to Docker infrastructure:
#     * SERVER_RESTAPI_URL=http://localhost:4000/api (localhost)
#     * REDIS_HOST=localhost (localhost)
#     * DATABASE_URL=postgresql://...@localhost:5432/... (explicit connection string)
#   - Gitignored - safe for local customizations
#
# NOTE: 'make dev-local' creates both files on first run (.env.development from
#       this template, then .env.local from it with the localhost values and
#       DATABASE_URL applied automatically). No manual copying needed.
# =============================================================================

# =============================================================================
# APPLICATION - General Configuration
# =============================================================================
ENVIRONMENT=development
NODE_ENV=development
APP_NAME=docsplus

# =============================================================================
# SECURITY
# =============================================================================
# Generate a strong random secret for production (min 32 characters)
# Use: openssl rand -base64 64
JWT_SECRET=dev-secret-key-change-in-production-min-32-chars

# =============================================================================
# INFRASTRUCTURE - Shared Services
# =============================================================================
DB_USER=docsplus
DB_PASSWORD=CHANGE_ME_STRONG_PASSWORD
DB_PORT=5432
REDIS_PORT=6379

# =============================================================================
# SUPABASE - Server-side (containers → host/internal)
# =============================================================================
SUPABASE_URL=http://host.docker.internal:54321
SUPABASE_ANON_KEY=eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJpc3MiOiJzdXBhYmFzZS1kZW1vIiwicm9sZSI6ImFub24iLCJleHAiOjE5ODM4MTI5OTZ9.CRXP1A7WOeoJeXxjNni43kdQwgnWNReilDMblYTn_I0
# Admin gateway (fail-closed) + view-tracking worker. This is the CLI's public
# local-demo key (same family as the anon key above) — replace for cloud/prod.
SUPABASE_SERVICE_ROLE_KEY=eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJpc3MiOiJzdXBhYmFzZS1kZW1vIiwicm9sZSI6InNlcnZpY2Vfcm9sZSIsImV4cCI6MTk4MzgxMjk5Nn0.EGIM96RAZx35lJzdJsyH-qQwv8Hdp7fsn3W0YpN81IU

# The OAuth issuer that /api/mcp names in its protected-resource metadata. Copy
# `issuer` from $SUPABASE_URL/auth/v1/.well-known/openid-configuration exactly.
# Unset means ${SUPABASE_URL}/auth/v1, which is wrong for a container address.
MCP_AUTH_ISSUER=http://127.0.0.1:54321/auth/v1

# =============================================================================
# SUPABASE - Client-side (browser → direct access)
# =============================================================================
NEXT_PUBLIC_SUPABASE_URL=http://localhost:54321
NEXT_PUBLIC_SUPABASE_WS_URL=ws://localhost:54321
NEXT_PUBLIC_SUPABASE_ANON_KEY=eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJpc3MiOiJzdXBhYmFzZS1kZW1vIiwicm9sZSI6ImFub24iLCJleHAiOjE5ODM4MTI5OTZ9.CRXP1A7WOeoJeXxjNni43kdQwgnWNReilDMblYTn_I0

# =============================================================================
# REST API SERVICE
# =============================================================================
APP_PORT=4000
EXPOSE_APP_PORT=4000
# For .env.development (Docker): Use Docker service name
# For .env.local (Local): Use localhost
SERVER_RESTAPI_URL=http://rest-api:4000/api
NEXT_PUBLIC_RESTAPI_URL=http://localhost:4000/api
# This server's own public origin, used by document conversion. ORIGIN ONLY —
# unlike the two above, NO `/api` suffix: route paths are appended and the result
# is persisted into document content, so `/api/api/...` would be permanent. It must
# match the origin already baked into stored image URLs. Unset means DOCX imports
# report images as dropped and DOCX exports omit pictures.
PUBLIC_RESTAPI_URL=http://localhost:4000
REST_LOG_LEVEL=debug

# =============================================================================
# HOCUSPOCUS WEBSOCKET SERVICE
# =============================================================================
HOCUSPOCUS_PORT=4001
EXPOSE_HOCUSPOCUS_PORT=4001
NEXT_PUBLIC_PROVIDER_URL=ws://localhost:4001
WS_LOG_LEVEL=debug

# Internal HTTP listener on the collaboration process: /metrics plus the
# service-role content-apply endpoint. Never expose it through Traefik.
# Defaults are 4003 / 0.0.0.0 / http://localhost:4003; compose points REST at
# http://hocuspocus-server:4003. Set the host to 127.0.0.1 on a shared network.
# HOCUSPOCUS_INTERNAL_HTTP_PORT=4003
# HOCUSPOCUS_INTERNAL_HTTP_HOST=0.0.0.0
# HOCUSPOCUS_INTERNAL_URL=http://localhost:4003

# Hocuspocus Logger Configuration
HOCUSPOCUS_LOGGER=true
HOCUSPOCUS_LOGGER_ON_CONNECT=true
HOCUSPOCUS_LOGGER_ON_DISCONNECT=true
HOCUSPOCUS_LOGGER_ON_LOAD_DOCUMENT=true
HOCUSPOCUS_LOGGER_ON_CHANGE=true
HOCUSPOCUS_LOGGER_ON_UPGRADE=true
HOCUSPOCUS_LOGGER_ON_REQUEST=true
HOCUSPOCUS_LOGGER_ON_LISTEN=true
HOCUSPOCUS_LOGGER_ON_DESTROY=true
HOCUSPOCUS_LOGGER_ON_CONFIGURE=true

# Hocuspocus Throttle Configuration
# BANTIME is in MINUTES (extension multiplies by 60 * 1000)
HOCUSPOCUS_THROTTLE=true
HOCUSPOCUS_THROTTLE_ATTEMPTS=100
HOCUSPOCUS_THROTTLE_BANTIME=1

# =============================================================================
# WORKER SERVICE
# =============================================================================
WORKER_HEALTH_PORT=4002
EXPOSE_WORKER_HEALTH_PORT=4002
WORKER_LOG_LEVEL=debug

# =============================================================================
# WEBAPP SERVICE
# =============================================================================
NEXT_PUBLIC_SSE_URL=http://localhost:3000/sse

# =============================================================================
# DATABASE - PostgreSQL Connection Pool
# =============================================================================
# For .env.development (Docker): DATABASE_URL is set by Docker Compose (not needed here)
# For .env.local (Local): required — the dev-local preflight appends it automatically
# when creating .env.local, built from DB_USER/DB_PASSWORD/DB_PORT:
# DATABASE_URL=postgresql://docsplus:CHANGE_ME_STRONG_PASSWORD@localhost:5432/docsplus?connection_limit=10&pool_timeout=10&sslmode=prefer
DB_POOL_SIZE=10
DB_IDLE_TIMEOUT=300000
DB_CONNECT_TIMEOUT=10000
DB_STATEMENT_TIMEOUT=60000
DB_QUERY_TIMEOUT=60000
DB_LOG_LEVEL=

# =============================================================================
# REDIS - Connection & Configuration
# =============================================================================
REDIS=true
# For .env.development (Docker): Use Docker service name 'redis'
# For .env.local (Local): Use 'localhost'
REDIS_HOST=redis
REDIS_TLS=false
REDIS_CONNECT_TIMEOUT=30000
REDIS_COMMAND_TIMEOUT=60000
REDIS_KEEPALIVE=30000
REDIS_MAX_RETRIES=10
REDIS_LOG_LEVEL=

# =============================================================================
# BULLMQ - Queue Configuration
# =============================================================================
BULLMQ_CONCURRENCY=5
BULLMQ_RATE_LIMIT_MAX=100
BULLMQ_RATE_LIMIT_DURATION=1000
QUEUE_LOG_LEVEL=

# =============================================================================
# STORAGE - Configuration
# =============================================================================
# Storage type: 'local' or 's3'
STORAGE_TYPE=local
PERSIST_TO_LOCAL_STORAGE=true
LOCAL_STORAGE_PATH=./temp/hypermultimedia

# DigitalOcean Spaces / AWS S3
DO_STORAGE_ENDPOINT=https://nyc3.digitaloceanspaces.com
DO_STORAGE_REGION=nyc3
DO_STORAGE_BUCKET=your-bucket-name
DO_STORAGE_ACCESS_KEY_ID=your-access-key
DO_STORAGE_SECRET_ACCESS_KEY=your-secret-key
DO_STORAGE_MAX_FILE_SIZE=10485760
S3_CONNECT_TIMEOUT=10000
S3_REQUEST_TIMEOUT=30000
STORAGE_LOCAL_LOG_LEVEL=
STORAGE_S3_LOG_LEVEL=

# Legacy webapp storage variables (for backward compatibility)
NEXT_PUBLIC_SPACES_KEY=
NEXT_PUBLIC_SPACES_SECRET=

# =============================================================================
# CORS - Cross-Origin Resource Sharing
# =============================================================================
ALLOWED_ORIGINS=http://localhost:3000,http://localhost:3001

# =============================================================================
# RATE LIMITING
# =============================================================================
RATE_LIMIT_MAX=1000

# =============================================================================
# LOGGING - Global Configuration
# =============================================================================
# Global default level (others inherit unless overridden)
# Options: fatal | error | warn | info | debug | trace | silent
LOG_LEVEL=debug

# Per-service log levels (leave empty to inherit LOG_LEVEL)
HTTP_LOG_LEVEL=
DOCUMENTS_CONTROLLER_LOG_LEVEL=
HEALTH_CONTROLLER_LOG_LEVEL=
DOCUMENTS_SERVICE_LOG_LEVEL=
MEDIA_SERVICE_LOG_LEVEL=
HEALTH_SERVICE_LOG_LEVEL=
JWT_LOG_LEVEL=

# =============================================================================
# SERVICE SCALING - Production Replicas
# =============================================================================
REST_REPLICAS=2
WS_REPLICAS=3
WORKER_REPLICAS=2
WEBAPP_REPLICAS=2

# =============================================================================
# BUILD METADATA
# =============================================================================
BUILD_ID=development-build
GIT_HASH=dev
# Client release tag (baked into the webapp/admin bundle at build; = GIT_HASH at deploy)
NEXT_PUBLIC_GIT_HASH=dev

# =============================================================================
# OBSERVABILITY - Error capture (GlitchTip / Sentry)
# =============================================================================
# Both SDKs no-op until their DSN is set. NEXT_PUBLIC_* is inlined at build time,
# so it must be present BEFORE the webapp/admin image is built (not just at runtime).
GLITCHTIP_DSN=
NEXT_PUBLIC_GLITCHTIP_DSN=

# Observability stack (prod host: .env.observability — see scripts/observability/.env.example)
# GRAFANA_ADMIN_PASSWORD=
# GLITCHTIP_SECRET_KEY=
# GLITCHTIP_POSTGRES_PASSWORD=
# TELEGRAM_BOT_TOKEN=
# TELEGRAM_CHAT_ID=
# DEADMAN_WEBHOOK_URL=

# Demo-week backend logging (override compose defaults in .env.production):
# LOG_LEVEL=info REST_LOG_LEVEL=info WS_LOG_LEVEL=info WORKER_LOG_LEVEL=info HTTP_LOG_LEVEL=warn

# =============================================================================
# EMAIL - Notification Service (SMTP via Nodemailer)
# =============================================================================
# Sends email notifications when new documents are created.

# Common settings
EMAIL_FROM=notifications@yourdomain.com
SMTP_FROM_NAME=docs.plus
NEW_DOCUMENT_NOTIFICATION_EMAILS=admin@company.com,ops@company.com
APP_URL=https://yourdomain.com
EMAIL_LOG_LEVEL=

# Signs the one-click unsubscribe links in every email footer. The token is the
# credential, so a link works without a session. Treat it like a password, and
# never reuse it across environments. Unset does NOT mean no link: the footer
# falls back to a link with no token, which the route then rejects.
# Generate one with: openssl rand -base64 48
EMAIL_UNSUBSCRIBE_SECRET=

# SMTP Configuration
# Gmail: Use App Password (not your regular password)
# Setup guide: https://support.google.com/accounts/answer/185833
SMTP_HOST=smtp.gmail.com
SMTP_PORT=587
SMTP_USER=you@gmail.com
SMTP_PASS=your-16-char-app-password
SMTP_SECURE=false

# Alternative: Resend (recommended for production)
# RESEND_API_KEY=re_xxxxxxxxxxxxxxxxxxxxxxxxxxxx

# =============================================================================
# PUSH NOTIFICATIONS - Web Push (VAPID)
# =============================================================================
# Required for web push notifications to work.
# Generate keys with: bunx web-push generate-vapid-keys

# Client-side (used by webapp)
NEXT_PUBLIC_VAPID_PUBLIC_KEY=

# Virtuoso Message List (chat feed); baked at next build — https://virtuoso.dev/pricing/
NEXT_PUBLIC_VIRTUOSO_LICENSE=

# Server-side (used by hocuspocus-worker)
VAPID_PUBLIC_KEY=
VAPID_PRIVATE_KEY=
VAPID_SUBJECT=mailto:support@yourdomain.com

# Push Gateway Configuration
PUSH_WORKER_CONCURRENCY=5
PUSH_RATE_LIMIT_MAX=50
PUSH_RATE_LIMIT_DURATION=60000
PUSH_LOG_LEVEL=

# =============================================================================
# ANALYTICS & EXTERNAL SERVICES
# =============================================================================
# Google Analytics
NEXT_PUBLIC_GA_ID=

# Google OAuth - Required for Supabase Google Sign-In
# Get credentials from: https://console.cloud.google.com/apis/credentials
# Authorized redirect URI: http://localhost:54321/auth/v1/callback
GOOGLE_CLIENT_ID=
GOOGLE_SECRET=
NEXT_PUBLIC_GOOGLE_CLIENT_ID=

# Magic-link return base. Baked at next build, so it must be a webapp build arg.
# Leave empty to use the origin the browser is on.
NEXT_PUBLIC_SUPABASE_OTP_EMAIL_REDIRECT=

# TipTap Pro (Optional)
TIPTAP_PRO_TOKEN=

# Elastic APM (Optional)
NEXT_PUBLIC_ELASTIC_APM_SERVER_URL=
NEXT_PUBLIC_ELASTIC_APM_SECRET_TOKEN=

# =============================================================================
# ADMIN DASHBOARD
# =============================================================================
ADMIN_PORT=3100
NEXT_PUBLIC_ADMIN_URL=http://localhost:3100
NEXT_PUBLIC_API_URL=http://localhost:4000
NEXT_PUBLIC_APP_URL=http://localhost:3000
# Production:
# NEXT_PUBLIC_ADMIN_URL=https://admin.docs.plus
# NEXT_PUBLIC_API_URL=https://api.docs.plus
# NEXT_PUBLIC_APP_URL=https://docs.plus