.env.example

# Environment Variables
DATABASE_URL=postgresql://user:password@localhost:5432/propchain
PORT=3000
NODE_ENV=development
FRONTEND_URL=http://localhost:3000

# JWT Configuration
# Required. Must be at least 32 characters (256 bits). The app will refuse to
# start if either secret is missing or too short. Generate strong values with:
#   openssl rand -hex 32
JWT_SECRET=your-super-secret-jwt-key-change-in-production-min-32-chars
JWT_REFRESH_SECRET=your-super-secret-refresh-key-change-in-production-min-32c
JWT_ACCESS_EXPIRES_IN=15m
JWT_REFRESH_EXPIRES_IN=7d

# Security Configuration
BCRYPT_ROUNDS=12
PASSWORD_HISTORY_LIMIT=5

# Two-factor authentication (TOTP)
# Lifetime of a "remembered" trusted device, in days. After a successful TOTP
# challenge a user may opt to trust the device; future logins from that device
# skip the challenge until this many days have elapsed or the device is revoked.
# Invalid or non-positive values fall back to 30. Disabling 2FA or changing the
# password revokes every trusted device.
TRUSTED_DEVICE_TTL_DAYS=30

# Database Backup Management
BACKUP_STORAGE_PATH=./backups
PG_DUMP_PATH=pg_dump
PSQL_PATH=psql

# PgBouncer Connection Pooling
# Set to 'true' when connecting through PgBouncer (disables Prisma's built-in pool)
PGBOUNCER_ENABLED=false
# Prisma connection pool size (connection_limit), applied when PgBouncer is disabled.
# When PgBouncer is enabled this should match PgBouncer's DEFAULT_POOL_SIZE.
PGBOUNCER_POOL_SIZE=20
# Timeout (ms) for acquiring a connection from Prisma's pool. Applied when PgBouncer is
# disabled; with PgBouncer enabled the timeout is enforced server-side by PgBouncer.
PGBOUNCER_POOL_TIMEOUT=10000

# N+1 Query Detection (Issue #911)
# Warns when the same query shape hits the same table DB_N1_THRESHOLD times
# within DB_N1_WINDOW_MS. Unset = on outside production, off in production.
# 'true' opts production in (also enables Prisma query events, small overhead);
# 'false' disables it everywhere.
# DB_N1_DETECTION=true
# DB_N1_WINDOW_MS=100
# DB_N1_THRESHOLD=5

# Cache Warming
# Set to 'false' to disable startup and periodic cache warming (default: enabled)
CACHE_WARMING_ENABLED=true
# Interval (ms) between periodic warming runs using setInterval (default: 1800000 = 30 minutes)
# Note: This uses Node.js setInterval, not @nestjs/schedule. The timer is unref'd so it doesn't keep the process alive.
CACHE_WARMING_INTERVAL=1800000
# Google OAuth2
GOOGLE_CLIENT_ID=your-google-client-id
GOOGLE_CLIENT_SECRET=your-google-client-secret
GOOGLE_CALLBACK_URL=http://localhost:3000/api/auth/google/callback

# Blockchain Configuration
# #1178 – these are validated at boot when BLOCKCHAIN_ENABLED=true: the contract
# address must be a valid EIP-55 checksummed address (not the zero-address
# placeholder), the RPC URL must be a real http(s)/ws(s) endpoint, and the
# private key must be present. A misconfigured deployment aborts startup.
BLOCKCHAIN_ENABLED=true
BLOCKCHAIN_NETWORK=sepolia
# Replace with a real RPC endpoint (e.g. your Infura/Alchemy project URL)
BLOCKCHAIN_RPC_URL=https://sepolia.infura.io/v3/YOUR_INFURA_KEY
# Replace with your deployed contract address; the zero-address placeholder
# will be rejected at boot.
BLOCKCHAIN_CONTRACT_ADDRESS=0x0000000000000000000000000000000000000000
BLOCKCHAIN_PRIVATE_KEY=your-wallet-private-key

# Property Image Uploads
PROPERTY_IMAGES_UPLOAD_DIR=./uploads/properties
PROPERTY_IMAGE_MAX_SIZE=10485760
PROPERTY_IMAGE_MAX_PER_PROPERTY=30
BASE_URL=http://localhost:3000

# Signed URL / Object Storage (document upload & download)
# Selects the object storage provider for signed upload/download URLs.
# Supported values: 's3', 'gcs', 'azure'. When unset (or anything else), the
# document endpoints advertise signed URLs but fail at runtime; in production
# the app refuses to start so misconfiguration is caught at boot, not on the
# first user download.
# SIGNED_URL_PROVIDER=s3

# Geocoding
# Provider: 'nominatim' (default, free) or 'google' (requires GOOGLE_GEOCODING_API_KEY).
# When GOOGLE_GEOCODING_API_KEY is set, 'google' is auto-selected unless
# GEOCODING_PROVIDER is explicitly set to 'nominatim'.
GEOCODING_PROVIDER=nominatim
NOMINATIM_BASE_URL=https://nominatim.openstreetmap.org
GEOCODING_USER_AGENT=PropChain-Backend/1.0 (geocoding)
GEOCODING_TIMEOUT_MS=5000
# GOOGLE_GEOCODING_API_KEY=

# CAPTCHA Configuration
# Set to 'true' only in development environments to bypass CAPTCHA verification
CAPTCHA_BYPASS=false
# REQUIRED when CAPTCHA_BYPASS != true (default). Boot fails fast if absent.
# RECAPTCHA_SECRET=

# Reverse proxy / load balancer (Issue #1195)
# Set to the number of trusted proxy hops (e.g. '1' for nginx in front of the
# app) when running behind a proxy, so x-forwarded-for is trusted for rate
# limiting. Leave unset when exposed directly to the internet.
# TRUST_PROXY=1

# Login account lockout (Issue #1190)
# Failed attempts before lockout (default 5) and lockout window in minutes
# (default 30). Invalid values fall back to the defaults with a warning.
LOGIN_MAX_ATTEMPTS=5
LOGIN_LOCKOUT_MINUTES=30

# Redis (used by Docker Compose and cache module)
REDIS_HOST=localhost
REDIS_PORT=6379
REDIS_PASSWORD=
REDIS_DB=0

# Search analytics retention (Issue #1182)
# Days to keep per-user search analytics/history rows before the daily cleanup
# job purges them. Aggregated popular-search counters are always kept.
CLEANUP_SEARCH_RETENTION_DAYS=30

# Webhook delivery-log retention (Issue #1295)
# Days to keep WebhookDeliveryLog rows before they are pruned by the daily
# cleanup job / webhook cron. Defaults to 30.
CLEANUP_WEBHOOK_LOG_DAYS=30

# Analytics request-log retention (Issue #1296)
# Days to keep RequestLog rows before the daily cleanup job prunes them.
# Defaults to 7.
CLEANUP_REQUESTLOG_DAYS=7

# Analytics write coalescing (Issue #1296)
# When 'true', request-log writes are coalesced into a Redis list and flushed
# to the database on a cron (defaults to on in production, off elsewhere).
# ANALYTICS_USE_REDIS_BUFFER=true

# Maximum webhook payload size in bytes before a warning is logged (default 65536).
# WEBHOOK_MAX_PAYLOAD_BYTES=65536

# Prometheus Metrics Exposure Security (Issue #1249)
# METRICS_PORT=9090
# METRICS_BEARER_TOKEN=your-prometheus-bearer-token
# METRICS_IP_ALLOWLIST=127.0.0.1,::1