.env.sample

# ================================================================
# DXClusterAPI Configuration File
# ================================================================
# Copy this file to .env and adjust the values to your needs
# This configuration works for Docker, Native Node.js, and Passenger modes

# ================================================================
# CORE SETTINGS - Essential Configuration
# ================================================================

# ----------------------------------------------------------------
# RUNTIME MODE
# ----------------------------------------------------------------
# Options: docker, native, passenger
# - docker: Running in Docker container
# - native: Standalone Node.js process
# - passenger: Phusion Passenger (shared hosting)
MODE=native

# ----------------------------------------------------------------
# WEB SERVER CONFIGURATION
# ----------------------------------------------------------------
# Port for the web server (ignored in Passenger mode)
WEBPORT=3000

# Trust proxy setting - Enable when behind reverse proxy (nginx, Apache, Passenger, load balancer)
# When true, Express will trust X-Forwarded-For headers for real client IP identification
# Required for accurate rate limiting and analytics when behind a proxy
# Set to false only if running standalone without a reverse proxy
TRUST_PROXY=true

# Base URL path (empty for root, or "/api" for subpath)
# Used as prefix for all API endpoints and routes
# Examples:
#   "" (empty)  -> Endpoints at root: http://yourserver.com/spots
#   "/api"      -> Endpoints at /api: http://yourserver.com/api/spots
#   "/dxapi"    -> Endpoints at /dxapi: http://yourserver.com/dxapi/spots
# All endpoints respect this prefix:
#   - API v1: BASEURL + /spots, BASEURL + /spot/:qrg, etc.
#   - API v2: BASEURL + /api/v2/spots, BASEURL + /api/v2/bands, etc.
#   - Health: BASEURL + /health
#   - Metrics: BASEURL + /metrics
#   - Live: BASEURL + /live
BASEURL=

# ----------------------------------------------------------------
# API CONFIGURATION
# ----------------------------------------------------------------
# Enable/disable API v1 (legacy endpoints)
API_V1_ENABLED=true

# Enable/disable API v2 (modern REST API)
API_V2_ENABLED=true

# API v2 authentication key (leave empty to disable authentication)
# When set, all API v2 requests must include "X-API-Key" header
API_V2_KEY=

# Default spot limit for API endpoints (maximum number of spots returned)
# Applies to API v1 /spots and API v2 /spots (when limit parameter not specified)
# Spots are sorted by timestamp (newest first) and limited to this number
# Default: 200, Recommended: 100-500 depending on client needs
API_SPOT_LIMIT=200

# ----------------------------------------------------------------
# SPOT CACHE CONFIGURATION
# ----------------------------------------------------------------
# Maximum number of spots to keep in cache before pruning old ones
# Recommended: 500 for production, 1000 for high-traffic servers
MAXCACHE=500

# Maximum age of spots in cache (in minutes)
# Spots older than this will be removed from cache
# Default: 120 minutes (2 hours)
SPOT_MAX_AGE=120

# ----------------------------------------------------------------
# DX CLUSTER CONFIGURATION
# ----------------------------------------------------------------
# Enable/disable DX Cluster connections module
CLUSTER_ENABLED=true

# Multiple DX Cluster connections (JSON array format)
# Each cluster should have: host, port, loginPrompt, call, password, cluster (name), customCommand (optional)
# Recommended clusters:
#   - DXSPOTS: Reliable, fast, worldwide coverage
#   - NC7J: Popular, good availability
# Replace YOUR_CALLSIGN with your amateur radio callsign
# customCommand: Optional command sent after login (e.g., "set/skimmer" for skimmer mode)
CLUSTERS=[{"host":"dxspots.com","port":7300,"loginPrompt":"login:","call":"YOUR_CALLSIGN","password":"","cluster":"DXSPOTS"},{"host":"dxc.nc7j.com","port":7300,"loginPrompt":"login:","call":"YOUR_CALLSIGN","password":"","cluster":"NC7J"}]

# Single cluster example (simpler format):
# CLUSTERS=[{"host":"dxspots.com","port":7300,"loginPrompt":"login:","call":"YOUR_CALLSIGN","password":"","cluster":"DXSPOTS"}]

# Cluster with custom command example:
# CLUSTERS=[{"host":"dxspots.com","port":7300,"loginPrompt":"login:","call":"YOUR_CALLSIGN","password":"","cluster":"DXSPOTS","customCommand":"set/skimmer"}]

# ================================================================
# SPOT SOURCES - External Data Integration
# ================================================================

# ----------------------------------------------------------------
# POTA (Parks on the Air) Integration
# ----------------------------------------------------------------
# Enable/disable POTA spot polling
POTA_ENABLED=true

# POTA API polling interval in seconds (recommended: 120 = 2 minutes)
# Don't set too low to avoid API rate limiting
POTA_POLLING_INTERVAL=120

# ----------------------------------------------------------------
# SOTA (Summits on the Air) Integration
# ----------------------------------------------------------------
# Enable/disable SOTA spot polling
SOTA_ENABLED=true

# SOTA API polling interval in seconds (recommended: 120 = 2 minutes)
# Don't set too low to avoid API rate limiting
SOTA_POLLING_INTERVAL=120

# ----------------------------------------------------------------
# RBN (Reverse Beacon Network) Integration
# ----------------------------------------------------------------
# Enable/disable RBN module (default: false for privacy)
# When enabled, connects to RBN to receive automated spot reports from CW/RTTY/FT8 skimmers
RBN_ENABLED=false

# Your amateur radio callsign (required for RBN login)
RBN_CALLSIGN=YOUR_CALLSIGN

# How long to keep RBN spots before they expire (in minutes)
RBN_SPOT_TIMEOUT=5

# Enable CW/RTTY feed (port 7000) - Traditional modes
RBN_CW_RTTY_ENABLED=true

# Enable FT8 feed (port 7001) - High volume, enable only if needed
RBN_FT8_ENABLED=false

# ================================================================
# API MODULES - Feature Enhancements
# ================================================================

# ----------------------------------------------------------------
# DATA ENRICHMENT
# ----------------------------------------------------------------
# Enable/disable automatic spot enrichment
# Extracts POTA/SOTA/IOTA/WWFF references, contest detection, etc.
ENRICHMENT_ENABLED=true

# ----------------------------------------------------------------
# MODE CLASSIFICATION
# ----------------------------------------------------------------
# Enable/disable automatic mode detection
# Detects CW/Phone/Digi and submodes (USB/LSB/FT8/RTTY/etc.) based on frequency
MODE_CLASSIFIER_ENABLED=true

# ================================================================
# MONITORING & ANALYTICS
# ================================================================

# ----------------------------------------------------------------
# ANALYTICS MODULE
# ----------------------------------------------------------------
# Enable/disable analytics tracking (default: false for privacy)
# Tracks spot statistics, source distribution, band activity
# Data stored in data/ directory
ANALYTICS_ENABLED=false

# ================================================================
# SECURITY - Protection Features
# ================================================================

# ----------------------------------------------------------------
# RATE LIMITING
# ----------------------------------------------------------------
# Enable/disable API rate limiting (default: false, enable for production if needed)
# Protects against abuse and DDoS attacks
RATE_LIMITER_ENABLED=false

# Maximum requests per minute for general endpoints (health, metrics, etc. are exempt)
# Default: 120 requests per minute (2 requests per second)
# Recommended: 60-240 depending on expected traffic and server capacity
RATE_LIMITER_GENERAL_MAX=120

# Maximum requests per minute for data endpoints (spots, bands, etc.)
# Default: 60 requests per minute (1 request per second, allows polling every 59s)
# Recommended: 30-120 depending on polling frequency requirements
RATE_LIMITER_DATA_MAX=60

# Ban duration when rate limit is exceeded (in seconds)
# Default: 60 seconds (1 minute)
# Recommended: 60-300 seconds depending on security requirements
RATE_LIMITER_BAN_TIME=60

# ================================================================
# USER INTERFACE
# ================================================================

# ----------------------------------------------------------------
# LIVE PAGE
# ----------------------------------------------------------------
# Enable/disable built-in live monitoring web interface at /live
LIVE_PAGE_ENABLED=true

# Live page password protection (leave empty to disable)
# When set, users must provide this password to access the live page
# Uses HTTP Basic Authentication
LIVE_PAGE_PASSWORD=

# ----------------------------------------------------------------
# WEBSOCKET
# ----------------------------------------------------------------
# Enable/disable WebSocket for real-time updates
# Disable if running on shared hosting where WebSocket is blocked
# Live page will automatically fall back to polling mode
WEBSOCKET_ENABLED=true

# ================================================================
# LOGGING & DEBUG
# ================================================================

# ----------------------------------------------------------------
# FILE LOGGING
# ----------------------------------------------------------------
# Enable/disable file-based logging (logs stored in logs/ directory)
FILE_LOGGING_ENABLED=true

# Number of days to keep log files before automatic cleanup
LOG_RETENTION_DAYS=3

# ----------------------------------------------------------------
# PERSISTENCE (SPOT CACHE)
# ----------------------------------------------------------------
# Enable/disable spot cache persistence to survive restarts
# When enabled, the spot cache is saved to disk every interval and restored on startup
# This allows the API to start with existing spots instead of waiting for new ones
PERSISTENCE_ENABLED=true

# How often to save the cache to disk (in seconds)
# Lower values = more frequent saves (higher I/O) but less data loss on crash
# Higher values = less I/O but potentially lose more spots on unexpected shutdown
# Recommended: 60-300 seconds (default: 60)
PERSISTENCE_INTERVAL=60

# Path to the cache file (default: data/spots-cache.json)
# The directory will be created automatically if it doesn't exist
PERSISTENCE_PATH=

# ================================================================
# OPTIONAL INTEGRATIONS
# ================================================================

# ----------------------------------------------------------------
# WAVELOG DXCC LOOKUP
# ----------------------------------------------------------------
# Enable Wavelog integration for DXCC entity lookups
# Leave empty to disable, or provide your Wavelog instance URL and API key
WAVELOG_URL=
WAVELOG_KEY=

# Maximum concurrent DXCC lookups to prevent overloading PHP-FPM
# Lower values reduce PHP-FPM memory usage but may slow down spot processing
# Recommended: 2-5 (default: 2)
MAX_CONCURRENT_DXCC=2

# Maximum number of DXCC lookups to cache in memory
# Higher values reduce API calls to Wavelog but use more memory
# Each entry uses ~500 bytes, so 5000 entries = ~2.5MB
# Recommended: 1000-10000 (default: 5000)
DXCC_CACHE_MAX_SIZE=5000
# ================================================================