Skip to main content

Configuration Reference

Complete environment variable reference for self-hosted Ovyxa.

Core Configuration​

BASE_URL​

  • Required: Yes
  • Description: Public URL where Ovyxa is accessible
  • Example: https://analytics.yourdomain.com
  • Notes: Used for CORS, email links, redirects

SECRET_KEY_BASE​

  • Required: Yes
  • Description: Secret for JWT signing and encryption
  • Example: $(openssl rand -hex 64)
  • Notes: Keep secret, rotate periodically. Must be 64+ hex chars

NODE_ENV​

  • Required: No
  • Default: development
  • Options: development | production | test
  • Description: Runtime environment

LOG_LEVEL​

  • Required: No
  • Default: info
  • Options: error | warn | info | debug | trace
  • Description: Logging verbosity

Database Configuration​

DATABASE_URL​

  • Required: Yes
  • Description: PostgreSQL connection string (metadata)
  • Example: postgresql://user:pass@host:5432/dbname
  • Format: postgresql://[user]:[password]@[host]:[port]/[database]

CLICKHOUSE_HOST​

  • Required: Yes
  • Description: ClickHouse HTTP endpoint (analytics)
  • Example: http://clickhouse:8123
  • Notes: Use HTTP protocol, not native

CLICKHOUSE_DATABASE​

  • Required: No
  • Default: ovyxa
  • Description: ClickHouse database name

CLICKHOUSE_USER​

  • Required: No
  • Default: default
  • Description: ClickHouse username

CLICKHOUSE_PASSWORD​

  • Required: No
  • Description: ClickHouse password (if auth enabled)

REDIS_URL​

  • Required: Yes
  • Description: Redis connection string
  • Example: redis://:password@host:6379
  • Format: redis://[:password]@[host]:[port]/[db]

Privacy & Tracking​

RESPECT_DNT​

  • Required: No
  • Default: true
  • Description: Honor Do Not Track browser setting
  • Options: true | false

IP_SALT​

  • Required: No
  • Default: Auto-generated daily
  • Description: Salt for IP hashing (daily unique calculation)
  • Notes: Leave empty for auto-rotation

DATA_RETENTION_DAYS​

  • Required: No
  • Default: 365
  • Description: How many days to keep raw event data
  • Example: 180 (6 months), 730 (2 years)

STRIP_QUERY_PARAMS​

  • Required: No
  • Default: false
  • Description: Remove all query parameters from URLs
  • Options: true | false

STRIP_SENSITIVE_PARAMS​

  • Required: No
  • Default: email,token,key,secret,password,auth
  • Description: Comma-separated list of query params to strip
  • Example: email,token,session_id

Rate Limiting​

RATE_LIMIT_WINDOW​

  • Required: No
  • Default: 60000 (1 minute)
  • Description: Rate limit window in milliseconds

RATE_LIMIT_MAX​

  • Required: No
  • Default: 100
  • Description: Max requests per IP per window

RATE_LIMIT_ENABLED​

  • Required: No
  • Default: true
  • Description: Enable/disable rate limiting
  • Options: true | false

Email Configuration​

SMTP_HOST​

  • Required: No (optional feature)
  • Description: SMTP server hostname
  • Example: smtp.gmail.com

SMTP_PORT​

  • Required: No
  • Default: 587
  • Description: SMTP port (587 for TLS, 465 for SSL)

SMTP_USER​

  • Required: If SMTP enabled
  • Description: SMTP username/email
  • Example: noreply@yourdomain.com

SMTP_PASSWORD​

  • Required: If SMTP enabled
  • Description: SMTP password or app-specific password

SMTP_FROM_EMAIL​

  • Required: No
  • Default: Uses SMTP_USER
  • Description: "From" address for emails

SMTP_FROM_NAME​

  • Required: No
  • Default: Ovyxa
  • Description: "From" name for emails

GeoIP Configuration​

GEOIP_DATABASE_PATH​

  • Required: No
  • Default: ./data/GeoLite2-Country.mmdb
  • Description: Path to MaxMind GeoIP database
  • Notes: Download from MaxMind (free account required)

GEOIP_ENABLED​

  • Required: No
  • Default: true
  • Description: Enable country detection from IP
  • Options: true | false

Performance & Caching​

CACHE_TTL​

  • Required: No
  • Default: 300 (5 minutes)
  • Description: Default cache TTL in seconds

CLICKHOUSE_MAX_QUERY_SIZE​

  • Required: No
  • Default: 10000
  • Description: Max rows returned per query

CLICKHOUSE_TIMEOUT​

  • Required: No
  • Default: 30000 (30 seconds)
  • Description: Query timeout in milliseconds

Security​

ALLOWED_ORIGINS​

  • Required: No
  • Default: * (all origins)
  • Description: CORS allowed origins (comma-separated)
  • Example: https://yourdomain.com,https://app.yourdomain.com

DISABLE_REGISTRATION​

  • Required: No
  • Default: false
  • Description: Disable new user registration
  • Options: true | false
  • Notes: Useful for private instances

SESSION_SECRET​

  • Required: No
  • Default: Uses SECRET_KEY_BASE
  • Description: Separate secret for sessions

BCRYPT_ROUNDS​

  • Required: No
  • Default: 12
  • Description: BCrypt cost factor for password hashing

Admin​

ADMIN_EMAIL​

  • Required: For initial setup
  • Description: Admin account email (created on first run)
  • Example: admin@yourdomain.com

ADMIN_PASSWORD​

  • Required: For initial setup
  • Description: Admin account password
  • Notes: Change immediately after first login

Experimental Features​

ENABLE_FUNNELS​

  • Required: No
  • Default: false
  • Description: Enable funnel analysis (Phase 2)
  • Options: true | false

ENABLE_COHORTS​

  • Required: No
  • Default: false
  • Description: Enable cohort analysis (Phase 2)
  • Options: true | false

ENABLE_OPT_IN_MODE​

  • Required: No
  • Default: false
  • Description: Allow sites to use opt-in tracking with first-party IDs
  • Options: true | false

Example Complete .env File​

# Core
BASE_URL=https://analytics.yourdomain.com
SECRET_KEY_BASE=abc123...xyz789 # 64+ hex chars
NODE_ENV=production
LOG_LEVEL=info

# Databases
DATABASE_URL=postgresql://ovyxa:strong_pass@postgres:5432/ovyxa
CLICKHOUSE_HOST=http://clickhouse:8123
CLICKHOUSE_DATABASE=ovyxa
REDIS_URL=redis://:redis_pass@redis:6379

# Privacy
RESPECT_DNT=true
DATA_RETENTION_DAYS=365
STRIP_SENSITIVE_PARAMS=email,token,key,password

# Rate Limiting
RATE_LIMIT_ENABLED=true
RATE_LIMIT_WINDOW=60000
RATE_LIMIT_MAX=100

# Email (optional)
SMTP_HOST=smtp.gmail.com
SMTP_PORT=587
SMTP_USER=noreply@yourdomain.com
SMTP_PASSWORD=app_specific_password
SMTP_FROM_NAME=Analytics

# Security
ALLOWED_ORIGINS=https://yourdomain.com
DISABLE_REGISTRATION=true

# Admin
ADMIN_EMAIL=admin@yourdomain.com
ADMIN_PASSWORD=change_me_immediately

# GeoIP
GEOIP_ENABLED=true
GEOIP_DATABASE_PATH=./data/GeoLite2-Country.mmdb

Loading Configuration​

Docker Compose​

Edit .env file in project root. Values loaded automatically.

Kubernetes​

Create Secret:

kubectl create secret generic ovyxa-config \
  --from-literal=SECRET_KEY_BASE=$(openssl rand -hex 64) \
  --from-literal=DATABASE_URL=postgresql://... \
  --namespace ovyxa

Reference in deployment:

spec:
  containers:
    - name: api
      envFrom:
        - secretRef:
            name: ovyxa-config

Systemd Service​

Add to service file:

[Service]
Environment="BASE_URL=https://analytics.yourdomain.com"
Environment="SECRET_KEY_BASE=abc123..."
EnvironmentFile=/etc/ovyxa/config.env

Validation​

Test configuration:

# Docker Compose
docker-compose exec api npm run config:validate

# Direct Node.js
node scripts/validate-config.js

Security Best Practices​

  1. Never commit secrets to version control
  2. Use strong passwords (32+ random characters)
  3. Rotate secrets periodically (quarterly recommended)
  4. Restrict ALLOWED_ORIGINS in production
  5. Enable rate limiting to prevent abuse
  6. Use environment-specific config files

Troubleshooting​

Config not loading​

  • Check file permissions: ls -la .env
  • Verify format (no spaces around =)
  • Check for trailing quotes (remove if present)

Database connection errors​

  • Verify DATABASE_URL format
  • Test connection: psql $DATABASE_URL
  • Check firewall rules

SMTP not working​

  • Test with nc -zv smtp.example.com 587
  • Check credentials
  • Verify port (587 for STARTTLS, 465 for SSL)

Next Steps​

Proper configuration ensures security, performance, and reliability.