.env.example

# Kima Configuration
# Copy to .env and edit as needed

# ==============================================================================
# Database Configuration
# ==============================================================================
DATABASE_URL="postgresql://kima:kima@localhost:5433/kima"

# ==============================================================================
# Redis Configuration
# ==============================================================================
# Note: Redis container port is mapped to 6380 to avoid conflicts with other Redis instances
REDIS_URL="redis://localhost:6380"

# ==============================================================================
# REQUIRED: Path to your music library
# ==============================================================================
MUSIC_PATH=/path/to/your/music
# DEVELOPMENT: Use your local path (e.g., /home/user/Music)
# DOCKER: This is the HOST path that gets mounted to /music in the container
#         The backend inside Docker always uses /music, not this value.
#         Example: MUSIC_PATH=~/Music  (container mounts as ~/Music:/music)

# ==============================================================================
# REQUIRED: Security Keys
# ==============================================================================

# Encryption key for sensitive data (API keys, passwords, 2FA secrets)
# CRITICAL: You MUST set this before starting Kima
# Generate with: openssl rand -base64 32
SETTINGS_ENCRYPTION_KEY=

# Session secret (auto-generated if not set)
# Generate with: openssl rand -base64 32
SESSION_SECRET=

# ==============================================================================
# OPTIONAL: Customize these if needed
# ==============================================================================

# Port to access Kima (default: 3030)
PORT=3030

# Timezone (default: UTC)
TZ=UTC

# Logging level (default: debug in development, warn in production)
# Options: debug, info, warn, error, silent
LOG_LEVEL=debug

# Allow public access to API documentation in production (default: false)
# Set to 'true' to make /api/docs accessible without authentication in production
# Development mode always allows public access
# DOCS_PUBLIC=true

# DockerHub username (for pulling images)
# Your DockerHub username (same as GitHub: chevron7locked)
DOCKERHUB_USERNAME=chevron7locked

# Version tag (use 'latest' or specific like 'v1.0.0')
VERSION=latest

# ==============================================================================
# OPTIONAL: Audio Analyzer Configuration
# ==============================================================================

# Audio Analyzer CPU Control
# NUM_WORKERS=2                   # Number of parallel worker processes (1-8, default: 2)
# THREADS_PER_WORKER=1            # Threads per worker for TensorFlow/FFT (1-4, default: 1)
# Formula: max_cpu_usage ≈ WORKERS × (THREADS_PER_WORKER + 1) × 100%
# Example: 2 workers × (1 thread + 1 overhead) = ~400% CPU (4 cores)

# Audio Analyzer Timeout Configuration
# STALE_PROCESSING_MINUTES=15     # Timeout for tracks stuck in 'processing' state (default: 15)
#                                 # MUST match backend cleanup threshold to prevent race conditions
# MAX_ANALYZE_SECONDS=90          # Seconds of audio to analyze per track (default: 90)
#                                 # Limits memory usage - full tracks analyzed in chunks
# BATCH_SIZE=10                   # Number of tracks to process in parallel (default: 10)
# MAX_RETRIES=3                   # Maximum retry attempts per track before permanent failure (default: 3)

# Audio Analyzer Idle Optimization
# AUDIO_BRPOP_TIMEOUT=30          # Redis BRPOP timeout in seconds (default: 30)
#                                 # Also controls DB reconciliation interval
# AUDIO_MODEL_IDLE_TIMEOUT=300    # Seconds before unloading ML models when idle (default: 300)
#                                 # Set to 0 to keep models loaded permanently

# CLAP Audio Analyzer (AI vibe/mood matching)
# Set to 'true' to disable the CLAP embedding analyzer on startup.
# Useful for low-memory deployments or when AI vibe matching is not needed.
# Only applies to the all-in-one container (docker-compose.prod.yml).
# For split containers (docker-compose.yml), simply don't start the audio-analyzer-clap service.
# DISABLE_CLAP=true

# ==============================================================================
# OPTIONAL: MusicBrainz Configuration
# ==============================================================================

# Custom MusicBrainz API base URL (default: https://musicbrainz.org/ws/2)
# Useful for self-hosted MusicBrainz mirrors to avoid rate limiting
# MUSICBRAINZ_BASE_URL=https://musicbrainz.org/ws/2

# ==============================================================================
# OPTIONAL: Lidarr Webhook Configuration
# ==============================================================================

# Kima callback URL - How Lidarr can reach Kima backend for webhooks
# DOCKER SAME-NETWORK: Use service name (http://backend:3006)
# DOCKER EXTERNAL: Use host IP (http://192.168.1.100:3006 or http://host.docker.internal:3006)
# STANDALONE LIDARR: Use external URL (http://yourserver:3006)
# Default: http://backend:3006 (assumes Lidarr and Kima are on same Docker network)
KIMA_CALLBACK_URL=http://backend:3006

# TROUBLESHOOTING: If you get "Name does not resolve (backend:3006)" errors in Lidarr logs:
# 1. Ensure Lidarr and Backend are on the same Docker network (default: kima_network)
# 2. Try using the container name: http://kima_backend:3006
# 3. Try using the host gateway: http://host.docker.internal:3006
# 4. Use your host's LAN IP: http://192.168.1.100:3006
#
# Solution:
# - Check networks: docker network inspect kima_network
# - If Lidarr is on different network, use external IP instead: http://<your-ip>:3006
# - Then update Lidarr → Settings → Connect → Kima webhook URL to match