.env.example

# Obiente Cloud Environment Configuration
# Complete reference: docs/reference/environment-variables.md

# =============================================================================
# Database Configuration
# =============================================================================
POSTGRES_USER=obiente
POSTGRES_PASSWORD=your_secure_password_here
POSTGRES_DB=obiente
DB_HOST=postgres
DB_PORT=5432

# High Availability (HA) - Optional, only for HA deployments
# REPLICATION_PASSWORD=your_replication_password_here
# PATRONI_ADMIN_PASSWORD=your_patroni_admin_password_here

# =============================================================================
# Metrics Database Configuration (TimescaleDB)
# =============================================================================
# Metrics are stored in a separate TimescaleDB instance for optimal time-series performance
# Falls back to main PostgreSQL if TimescaleDB is not available
METRICS_DB_HOST=timescaledb
METRICS_DB_PORT=5432
METRICS_DB_USER=obiente
METRICS_DB_PASSWORD=your_secure_password_here
METRICS_DB_NAME=obiente_metrics

# =============================================================================
# API Configuration
# =============================================================================
GO_API_PORT=3001
LOG_LEVEL=info
# Options: debug, info, warn, error
# Production: Use 'info' or 'warn'
# Development: Use 'debug'

# Database Logging Level (optional, falls back to LOG_LEVEL if not set)
# Controls GORM database query logging separately from application logs
# Options: debug, trace, info, warn, warning, error
# Production: Use 'error' to suppress SQL queries
# DB_LOG_LEVEL=error

# =============================================================================
# Authentication
# =============================================================================
ZITADEL_URL=https://auth.obiente.cloud
DISABLE_AUTH=false
# Development only: Set to 'true' to disable authentication completely
SKIP_TLS_VERIFY=false
# Development only: Set to 'true' to skip TLS certificate verification

# =============================================================================
# CORS Configuration
# =============================================================================
# Allow all origins (development only)
CORS_ORIGIN=*
# Production: Use specific origins
# CORS_ORIGIN=https://app.obiente.cloud,https://dashboard.obiente.cloud

# =============================================================================
# Domain & SSL
# =============================================================================
DOMAIN=obiente.cloud
ACME_EMAIL=admin@obiente.cloud
# Required for Let's Encrypt SSL certificate generation

# =============================================================================
# Security
# =============================================================================
# Generate with: openssl rand -hex 32
# Required for cryptographic operations like domain verification token generation
SECRET=your_secret_key_here_generate_with_openssl_rand_hex_32

# Rate Limiting (optional - uses defaults if not set)
# RATE_LIMIT_WINDOW_MS=60000
# RATE_LIMIT_MAX=100

# =============================================================================
# Notifications Service Configuration
# =============================================================================
# Shared secret for authenticating service-to-service calls to the notifications service
# Required for services that create notifications
# Generate with: openssl rand -hex 32
# Must be identical across all services that communicate with the notifications service
INTERNAL_SERVICE_SECRET=your_internal_service_secret_here_generate_with_openssl_rand_base64_32

# URL of the notifications service for internal service-to-service communication
# Defaults to Docker service name if not set
# NOTIFICATIONS_SERVICE_URL=http://notifications-service:3012

# Retry configuration for failed notification requests (optional - uses defaults if not set)
# Maximum number of retry attempts for transient errors (connection refused, unavailable, etc.)
# NOTIFICATIONS_RETRY_MAX_ATTEMPTS=3

# Initial backoff delay before first retry (exponential backoff doubles each attempt)
# NOTIFICATIONS_RETRY_INITIAL_BACKOFF=1s

# Maximum backoff delay between retry attempts (exponential backoff will not exceed this)
# NOTIFICATIONS_RETRY_MAX_BACKOFF=10s

# =============================================================================
# DNS Configuration
# =============================================================================
# Node IPs per region (REQUIRED for DNS resolution)
# Maps regions to node IP addresses for DNS resolution of deployments and game servers
# Format: "region1:ip1,ip2;region2:ip3,ip4" or simple "ip1,ip2" (defaults to "default" region)
# Examples:
#   Simple: NODE_IPS="1.2.3.4" or NODE_IPS="1.2.3.4,1.2.3.5"
#   Single region: NODE_IPS="us-east-1:1.2.3.4,1.2.3.5"
#   Multiple regions: NODE_IPS="us-east-1:1.2.3.4,1.2.3.5;eu-west-1:5.6.7.8,5.6.7.9"
#   Explicit default: NODE_IPS="default:1.2.3.4"
NODE_IPS=

# Traefik IPs per region (required)
# Format: "region1:ip1,ip2;region2:ip3,ip4"
# Simple format: "ip1,ip2" (defaults to "default" region)
# Example: TRAEFIK_IPS="us-east-1:1.2.3.4,1.2.3.5;eu-west-1:5.6.7.8,5.6.7.9"
TRAEFIK_IPS=

# DNS Server IPs (optional, for nameserver configuration)
# Comma-separated list of public IPs where DNS servers run
# Example: DNS_IPS="1.2.3.4,5.6.7.8,9.10.11.12"
DNS_IPS=

# DNS Server Port (optional, default: 53)
# Use a different port if 53 is already in use (e.g., systemd-resolved)
DNS_PORT=53

# DNS HTTP Port (optional, default: 8053)
# HTTP port for DNS delegation push endpoints
DNS_HTTP_PORT=8053

# =============================================================================
# Port Configuration
# =============================================================================
# Public HTTP/HTTPS Ports (docker-compose.yml - development)
# Published ports for Traefik reverse proxy
PUBLIC_HTTP_PORT=80
PUBLIC_HTTPS_PORT=443

# Traefik Dashboard Port (docker-compose.yml - development)
# Published port for Traefik dashboard
PUBLIC_TRAEFIK_DASHBOARD_PORT=8080

# Traefik Ports (docker-compose.swarm.yml - production)
# Published ports for Traefik reverse proxy in Swarm mode
TRAEFIK_HTTP_PORT=80
TRAEFIK_HTTPS_PORT=443
TRAEFIK_DEPLOYMENTS_PORT=8000
TRAEFIK_DASHBOARD_PORT=8080
TRAEFIK_SSH_PORT=2222

# SSH Proxy Port
# Port for SSH proxy (routed through Traefik)
# Used for VPS access
SSH_PROXY_PORT=2222

# Database Port Exposure
# Ports to expose PostgreSQL and TimescaleDB on host (localhost only)
# Default: PostgreSQL on 5433, TimescaleDB on 5434
# Note: 5432 is reserved for databases-service proxy.
POSTGRES_EXPOSE_PORT=5433
METRICS_DB_EXPOSE_PORT=5434


# =============================================================================
# DNS Delegation Configuration (Optional)
# =============================================================================
# DNS delegation allows self-hosted Obiente Cloud instances to use the main
# my.obiente.cloud DNS service while keeping their deployments in their own database.
# See docs/deployment/dns-delegation.md for detailed setup instructions.

# For self-hosted APIs pushing DNS records to production:
# Production API URL (e.g., "https://api.obiente.cloud")
# DNS_DELEGATION_PRODUCTION_API_URL=https://api.obiente.cloud

# API key for authentication (required for DNS delegation)
# Get API key by subscribing to DNS delegation ($2/month) or via superadmin
# DNS_DELEGATION_API_KEY=your_api_key_here

# How often to push DNS records (default: 2m)
# Must be less than DNS_DELEGATION_TTL to prevent expiration
# Recommended: Push interval < TTL / 2
# DNS_DELEGATION_PUSH_INTERVAL=2m

# TTL for pushed DNS records (default: 300s = 5 minutes)
# Records expire automatically if not refreshed within TTL
# DNS_DELEGATION_TTL=300s

# For production API accepting pushed records:
# Comma-separated list of API URLs for DNS delegation client queries
# DNS_DELEGATION_API_URLS=https://api1.example.com,https://api2.example.com

# Timeout for DNS delegation API queries (default: 5s)
# DNS_DELEGATION_TIMEOUT=5s

# =============================================================================
# Dashboard & Support
# =============================================================================
# Support contact displayed in email footers
SUPPORT_EMAIL=support@obiente.cloud

# Comma-separated list of emails with global access (Superadmin API and dashboard)
# Example: SUPERADMIN_EMAILS=admin@example.com,ops@example.com
SUPERADMIN_EMAILS=

# =============================================================================
# Email Configuration (Optional)
# =============================================================================
# SMTP_HOST and SMTP_FROM_ADDRESS must be set for outbound email
# When missing, email delivery is disabled gracefully
# SMTP_HOST=smtp.example.com
# SMTP_PORT=587
# SMTP_USERNAME=your_smtp_username
# SMTP_PASSWORD=your_smtp_password
# SMTP_FROM_ADDRESS=noreply@obiente.cloud
# SMTP_FROM_NAME="Obiente Cloud"
# SMTP_REPLY_TO=support@obiente.cloud
# SMTP_USE_STARTTLS=true
# SMTP_SKIP_TLS_VERIFY=false
# SMTP_TIMEOUT_SECONDS=10
# SMTP_LOCAL_NAME=api.obiente.local

# =============================================================================
# Orchestration
# =============================================================================
# Deployment strategy: least-loaded, round-robin, resource-based
# DEPLOYMENT_STRATEGY=least-loaded
# MAX_DEPLOYMENTS_PER_NODE=50

# =============================================================================
# Metrics Collection Configuration (Optional - uses defaults if not set)
# =============================================================================
# How often to collect metrics from containers
# METRICS_COLLECTION_INTERVAL=5s

# How often to batch write metrics to database
# METRICS_STORAGE_INTERVAL=60s

# How long to keep live metrics in memory
# METRICS_LIVE_RETENTION=5m

# Max parallel workers for stats collection
# METRICS_MAX_WORKERS=50

# Batch size for database writes
# METRICS_BATCH_SIZE=100

# Max metrics to keep in memory per deployment
# METRICS_MAX_LIVE_PER_DEPLOYMENT=1000

# Max container stats to cache for delta calculation
# METRICS_MAX_PREVIOUS_STATS=10000

# =============================================================================
# Metrics Docker API Configuration (Optional)
# =============================================================================
# Timeout for Docker API calls
# METRICS_DOCKER_API_TIMEOUT=10s

# Max retry attempts for failed API calls
# METRICS_DOCKER_API_RETRY_MAX=3

# Initial backoff delay for retries
# METRICS_DOCKER_API_RETRY_BACKOFF_INITIAL=1s

# Maximum backoff delay for retries
# METRICS_DOCKER_API_RETRY_BACKOFF_MAX=30s

# =============================================================================
# Metrics Circuit Breaker Configuration (Optional)
# =============================================================================
# Failures before opening circuit
# METRICS_CIRCUIT_BREAKER_FAILURE_THRESHOLD=5

# Cooldown period before attempting half-open
# METRICS_CIRCUIT_BREAKER_COOLDOWN=1m

# Successful calls needed to close circuit
# METRICS_CIRCUIT_BREAKER_HALFOPEN_MAX=3

# =============================================================================
# Metrics Health Check Configuration (Optional)
# =============================================================================
# How often to run health checks
# METRICS_HEALTH_CHECK_INTERVAL=30s

# Consecutive failures before unhealthy
# METRICS_HEALTH_CHECK_FAILURE_THRESHOLD=3

# =============================================================================
# Metrics Backpressure & Subscriber Configuration (Optional)
# =============================================================================
# Buffer size for subscriber channels
# METRICS_SUBSCRIBER_BUFFER_SIZE=100

# Time before marking subscriber as slow
# METRICS_SUBSCRIBER_SLOW_THRESHOLD=5s

# How often to cleanup dead subscribers
# METRICS_SUBSCRIBER_CLEANUP_INTERVAL=1m

# =============================================================================
# Metrics Retry Queue Configuration (Optional)
# =============================================================================
# Max retries for failed database writes
# METRICS_RETRY_MAX_RETRIES=5

# Interval between retry attempts
# METRICS_RETRY_INTERVAL=1m

# Max size of retry queue
# METRICS_RETRY_MAX_QUEUE_SIZE=10000

# =============================================================================
# Stripe Payment Processing
# =============================================================================
# Required for billing features
# Get your API keys from: https://dashboard.stripe.com/apikeys
# Secret key (starts with sk_) - Keep this secure, never expose to client
STRIPE_SECRET_KEY=sk_test_your_secret_key_here

# Required for webhook verification
# Get webhook secret from Stripe Dashboard or Stripe CLI (for local dev)
# For local development: Run 'stripe listen --forward-to localhost:3001/webhooks/stripe'
# The webhook secret will be shown in the CLI output (starts with whsec_)
# Important: Set webhook API version to '2025-10-29.clover' in Stripe Dashboard
STRIPE_WEBHOOK_SECRET=whsec_your_webhook_secret_here

# Frontend Stripe publishable key (exposed to client)
# Get from: https://dashboard.stripe.com/apikeys
# This is safe to expose publicly - it's used client-side for Stripe.js
# Publishable key (starts with pk_)
NUXT_PUBLIC_STRIPE_PUBLISHABLE_KEY=pk_test_your_publishable_key_here

# =============================================================================
# Monitoring & Grafana Configuration (Optional)
# =============================================================================
# Grafana admin password (default: admin)
# GRAFANA_PASSWORD=your_grafana_password_here

# Grafana datasource hostnames
# Swarm deployments: Use direct service names (postgres, timescaledb)
# HA deployments: Use pgpool service names (pgpool, metrics-pgpool)
# GRAFANA_POSTGRES_HOST=postgres
# GRAFANA_METRICS_DB_HOST=timescaledb

# Email address for Grafana alert notifications
# ALERT_EMAIL=alerts@obiente.cloud

# =============================================================================
# VPS Configuration
# =============================================================================
# VPS regions configuration
# Format: "region1:Name 1;region2:Name 2" or simple "region1"
# Examples:
#   VPS_REGIONS="us-illinois"
#   VPS_REGIONS="us-illinois,us-east-1"
#   VPS_REGIONS="us-illinois:US Illinois"
#   VPS_REGIONS="us-illinois:US Illinois;us-east-1:US East (N. Virginia)"
VPS_REGIONS=

# =============================================================================
# Proxmox Configuration
# =============================================================================
# Proxmox API URL
# Default Proxmox node endpoints mapping (used for both API and SSH if not overridden)
# Maps Proxmox node names to their hostnames/IPs (optionally with port)
# Format: "node1:host1,node2:host2" or "node1:host1:8006,node2:host2:8006"
# For API: Constructs https://host:8006 URLs from these endpoints
# For SSH: Uses endpoints directly (assumes port 22 if not specified)
# Example: PROXMOX_NODE_ENDPOINTS="node1:proxmox1.example.com,node2:proxmox2.example.com"
PROXMOX_NODE_ENDPOINTS=


# Optional API-specific override (overrides PROXMOX_NODE_ENDPOINTS for API only)
# Maps Proxmox node names to their full API URLs (https://host:8006)
# Format: "node1:https://proxmox1:8006,node2:https://proxmox2:8006" (full URLs required)
# Each API URL points to the Proxmox API on that specific node
# Example: PROXMOX_NODE_API_ENDPOINTS="node1:https://proxmox1.example.com:8006,node2:https://proxmox2.example.com:8006"
# If not configured, uses PROXMOX_NODE_ENDPOINTS (default)
PROXMOX_NODE_API_ENDPOINTS=


# Proxmox authentication (use either password OR token, not both)
# Option 1: Username and password
PROXMOX_USERNAME=root@pam
PROXMOX_PASSWORD=your-secure-password

# Option 2: API token (alternative to password)
# PROXMOX_TOKEN_ID=obiente-cloud
# PROXMOX_TOKEN_SECRET=your-token-secret

# Proxmox storage pool for VM disks (default: local-lvm)
# Common values: local-lvm, local, local-zfs, or custom storage pools
PROXMOX_STORAGE_POOL=local-lvm

# Starting VM ID range (optional)
# If set, VMs will be created starting from this ID
# If not set, Proxmox auto-generates the next available ID
# PROXMOX_VM_ID_START=300

# Optional VLAN tag for VM network isolation (optional)
# If set, all VMs will be placed on this VLAN
# Example: PROXMOX_VLAN_ID=100
# PROXMOX_VLAN_ID=

# Proxmox Region-to-Node Mapping (for multi-node clusters)
# Maps VPS regions to specific Proxmox cluster nodes
# Format: "region1:node1;region2:node2"
# Example: PROXMOX_REGION_NODES="us-east-1:customer;us-west-1:west"
# When creating a VPS in a region, the system will use the mapped node if available
# PROXMOX_REGION_NODES=
# If not configured or the mapped node does not exist, it falls back to the first available node

# Proxmox SSH Configuration (for cloud-init snippet writing)
# Required for writing cloud-init snippets to Proxmox storage
# See docs/guides/proxmox-ssh-user-setup.md for detailed setup instructions


# Optional SSH-specific override (overrides PROXMOX_NODE_ENDPOINTS for SSH only)
# Maps Proxmox node names to SSH endpoints (IP addresses or hostnames)
# Format: "node1:192.168.1.10,node2:192.168.1.11" or "node1:hostname1.example.com:22,node2:hostname2.example.com:2222"
# If not configured, uses PROXMOX_NODE_ENDPOINTS (default)
# Endpoints can be IP addresses or hostnames, optionally with ports
# Example: PROXMOX_NODE_SSH_ENDPOINTS="main:192.168.1.10,node2:192.168.1.11,node3:192.168.1.12"
PROXMOX_NODE_SSH_ENDPOINTS=

# SSH user for snippet writing (default: obiente-cloud)
# Same user must exist on all Proxmox nodes
# PROXMOX_SSH_USER=obiente-cloud

# SSH private key path (either this or PROXMOX_SSH_KEY_DATA must be set)
# Path to SSH private key file for snippet writing
# Same key is used for all nodes
# PROXMOX_SSH_KEY_PATH=/path/to/obiente-cloud-key

# SSH private key data (alternative to PROXMOX_SSH_KEY_PATH)
# SSH private key content (supports both raw key data and base64-encoded keys)
# Useful when using secrets managers
# Either this or PROXMOX_SSH_KEY_PATH must be set
# Same key is used for all nodes
# PROXMOX_SSH_KEY_DATA=

# Proxmox snippet storage pool (default: local)
# Storage pool for cloud-init snippets (must be directory-type: dir, nfs, cifs)
# Can be different from PROXMOX_STORAGE_POOL (which is for VM disks)
PROXMOX_SNIPPET_STORAGE=local

# =============================================================================
# VPS Gateway Configuration (Optional)
# =============================================================================
# Shared secret for authenticating with vps-gateway service
# Must match GATEWAY_API_SECRET configured in vps-gateway service
# Required when using gateway service for DHCP management
VPS_GATEWAY_API_SECRET=

# Per-node gateway endpoint mapping (REQUIRED for multi-node deployments)
# Maps Proxmox node names to their gateway service URLs
# Format: "node1:http://gateway1:1537,node2:http://gateway2:1537"
# Port 1537 = OCG (Obiente Cloud Gateway)
# Example: VPS_NODE_GATEWAY_ENDPOINTS="node1:http://203.0.113.1:1537,node2:http://203.0.113.2:1537"
# Each gateway URL points to the vps-gateway service on that specific node
VPS_NODE_GATEWAY_ENDPOINTS=

# Per-node gateway IP mapping for firewall rules (REQUIRED for multi-node deployments)
# Maps Proxmox node names to the internal gateway IP used for SSH proxying
# Format: "node1:10.15.3.10,node2:10.15.3.11"
# These IPs are on the VPS internal network (e.g., 10.15.3.0/24)
# VPS firewall rules allow SSH from these IPs for gateway access
# Example: VPS_NODE_GATEWAY_IPS="node1:10.15.3.10,node2:10.15.3.11"
# Falls back to VPS_GATEWAY_IP if node not found in mapping
VPS_NODE_GATEWAY_IPS=

# Bridge name for gateway network in Proxmox
# When using SDN, this should be the SDN VNet bridge name
# Auto-created by Proxmox (e.g., OCvpsnet for the OCvps-vnet VNet)
# Default: OCvpsnet
VPS_GATEWAY_BRIDGE=OCvpsnet

# Gateway Service Configuration (for vps-gateway service)
# =============================================================================
# Outbound IP address for SNAT (optional but recommended)
# If set, gateway will automatically configure iptables SNAT rules
# Allows isolation of VPS traffic from other infrastructure
# Each node's gateway can have a different outbound IP
# Example: GATEWAY_OUTBOUND_IP=203.0.113.10
GATEWAY_OUTBOUND_IP=

# Outbound network interface (optional, auto-detected if not set)
# Interface for outbound traffic routing
# Example: GATEWAY_OUTBOUND_INTERFACE=eth0
GATEWAY_OUTBOUND_INTERFACE=

# DHCP listen IP address (optional, defaults to GATEWAY_DHCP_GATEWAY)
# IP address for DHCP server to listen on within the VXLAN
# Allows each gateway to listen on a unique IP on the VXLAN
# Example: GATEWAY_DHCP_LISTEN_IP=10.15.3.10
GATEWAY_DHCP_LISTEN_IP=


# =============================================================================
# Notes
# =============================================================================
# - Never commit .env files to version control
# - Use strong passwords for all credentials
# - Rotate secrets regularly
# - Use Docker secrets in production
# - Set LOG_LEVEL=info in production
# - Set DB_LOG_LEVEL=error in production to suppress SQL queries
# - Duration values use Go's duration format: 5s, 1m, 2h

# =============================================================================
# Dashboard (Nuxt) Configuration
# =============================================================================
# Dashboard URL (used for OAuth callbacks and redirects)
# Typically: https://dashboard.${DOMAIN} or https://app.${DOMAIN}
DASHBOARD_URL=https://dashboard.obiente.cloud
# Dashboard hostname for Traefik routing (extracted from DASHBOARD_URL)
# If DASHBOARD_URL=https://dashboard.obiente.cloud, set DASHBOARD_HOSTNAME=dashboard.obiente.cloud
# If not set, defaults to dashboard.${DOMAIN}
DASHBOARD_HOSTNAME=dashboard.obiente.cloud

# API URL (used by dashboard to connect to backend API)
# Typically: https://api.${DOMAIN}
API_URL=https://api.obiente.cloud

# Session password for Nuxt session encryption
# MUST be at least 32 characters in production!
# Generate with: openssl rand -hex 32
NUXT_SESSION_PASSWORD=changeme
# Production: Use a secure random password (at least 32 characters)

# =============================================================================
# Dashboard (Nuxt) Public Environment Variables
# These are exposed to the client-side and must be prefixed with NUXT_PUBLIC_
# =============================================================================
# Request host (dashboard URL) - used for OAuth callbacks and redirects
NUXT_PUBLIC_REQUEST_HOST=${DASHBOARD_URL:-http://localhost:3000}

# API host - backend API endpoint
NUXT_PUBLIC_API_HOST=${API_URL:-http://api.${DOMAIN:-localhost}}

# OIDC Issuer URL
NUXT_PUBLIC_OIDC_ISSUER=${ZITADEL_URL:-https://obiente.cloud}

# OIDC Base URL (used for OIDC endpoints)
# Typically same as ZITADEL_URL, but can be different if needed
ZITADEL_BASE_URL=${ZITADEL_URL:-https://auth.obiente.cloud}
NUXT_PUBLIC_OIDC_BASE=${ZITADEL_BASE_URL:-https://auth.obiente.cloud}

# OIDC Client ID
NUXT_PUBLIC_OIDC_CLIENT_ID=${ZITADEL_CLIENT_ID:-339499954043158530}

# Disable authentication (client-side flag)
NUXT_PUBLIC_DISABLE_AUTH=${DISABLE_AUTH:-false}

# =============================================================================
# GitHub Integration
# =============================================================================
# GitHub OAuth Client ID (public, exposed to client)
NUXT_PUBLIC_GITHUB_CLIENT_ID=

# GitHub OAuth Client Secret (server-side only, never exposed to client)
GITHUB_CLIENT_SECRET=

# =============================================================================
# Dashboard Configuration Notes
# =============================================================================
# - All NUXT_PUBLIC_* variables are exposed to the client-side JavaScript
# - Never put secrets in NUXT_PUBLIC_* variables!
# - GITHUB_CLIENT_SECRET is server-side only (not exposed to client)
# - NUXT_SESSION_PASSWORD must be at least 32 characters in production
# - Traefik will automatically proxy the dashboard based on DOMAIN variable
#   Dashboard will be available at: http://dashboard.${DOMAIN} and https://dashboard.${DOMAIN}
#   Also accessible at: http://app.${DOMAIN} and https://app.${DOMAIN}