Skip to content

Environment Variables

Jump to bottom
Kolin edited this page Jun 22, 2026 · 5 revisions

Environment Variables

LogLynx uses environment variables for configuration. All variables have sensible defaults, so you can run LogLynx without any configuration.

Configuration Files

Create a .env file in the project root to customize settings. An example configuration file is provided as .env.example.

Quick Start:

cp .env.example .env
# Edit .env with your preferences
nano .env

Table of Contents

Database Configuration

DB_PATH

  • Type: String (file path)
  • Default: loglynx.db
  • Required: No
  • Description: Path to the SQLite database file. Can be absolute or relative to the working directory.
  • Example: 
    DB_PATH=loglynx.db                    # Relative path (default)
DB_PATH=/var/lib/loglynx/data.db      # Absolute path
DB_PATH=/data/loglynx.db              # Docker volume path

DB_MAX_OPEN_CONNS

  • Type: Integer
  • Default: 10
  • Required: No
  • Description: Maximum number of open database connections in the pool. Higher values allow more concurrent queries but consume more memory.
  • Recommended: 10-50 depending on traffic volume
  • Example: 
    DB_MAX_OPEN_CONNS=10    # Low traffic
DB_MAX_OPEN_CONNS=25    # High traffic

DB_MAX_IDLE_CONNS

  • Type: Integer
  • Default: 3
  • Required: No
  • Description: Maximum number of idle connections to keep in the pool. Should be less than or equal to DB_MAX_OPEN_CONNS.
  • Recommended: 25-50% of DB_MAX_OPEN_CONNS
  • Example: 
    DB_MAX_IDLE_CONNS=3

DB_CONN_MAX_LIFE

  • Type: Duration
  • Default: 1h (1 hour)
  • Required: No
  • Description: Maximum lifetime of a database connection before it's recycled. Prevents stale connections.
  • Format: Go duration format (e.g., 30m, 1h, 2h30m)
  • Example: 
    DB_CONN_MAX_LIFE=1h     # Recycle every hour
DB_CONN_MAX_LIFE=30m    # Recycle every 30 minutes

DB_RETENTION_DAYS

  • Type: Integer
  • Default: 60
  • Required: No
  • Description: Number of days to retain log data. Older data is automatically deleted. Set to 0 to disable automatic cleanup (database will grow indefinitely).
  • Recommended: 30-90 days for most use cases
  • Example: 
    DB_RETENTION_DAYS=60    # Keep 60 days of data
DB_RETENTION_DAYS=30    # Keep 30 days (saves disk space)
DB_RETENTION_DAYS=0     # Keep all data (disable cleanup)

DB_CLEANUP_INTERVAL

  • Type: Duration
  • Default: 1h (1 hour)
  • Required: No
  • Description: How often to check if cleanup should run. The actual cleanup only runs at DB_CLEANUP_TIME.
  • Format: Go duration format (e.g., 30m, 1h, 6h)
  • Example: 
    DB_CLEANUP_INTERVAL=1h    # Check every hour
DB_CLEANUP_INTERVAL=30m   # Check every 30 minutes

DB_CLEANUP_TIME

  • Type: String (time)
  • Default: 02:00
  • Required: No
  • Description: Time of day to run cleanup in 24-hour format (HH:MM). Recommended during low-traffic hours.
  • Format: HH:MM (24-hour format)
  • Example: 
    DB_CLEANUP_TIME=02:00    # 2:00 AM (default, low traffic)
DB_CLEANUP_TIME=03:30    # 3:30 AM
DB_CLEANUP_TIME=23:00    # 11:00 PM

DB_VACUUM_ENABLED

  • Type: Boolean
  • Default: true
  • Required: No
  • Description: Run SQLite VACUUM after cleanup to reclaim disk space. VACUUM briefly locks the database (approximately 1 minute per GB freed).
  • Values: true, false
  • Example: 
    DB_VACUUM_ENABLED=true    # Reclaim disk space (recommended)
DB_VACUUM_ENABLED=false   # Skip VACUUM (faster cleanup, no disk reclaim)

GeoIP Configuration

LogLynx uses MaxMind GeoLite2 databases for IP geolocation. Download from MaxMind.

GEOIP_ENABLED

  • Type: Boolean
  • Default: true
  • Required: No
  • Description: Enable or disable GeoIP enrichment. If disabled, geographic features will be unavailable.
  • Values: true, false
  • Example: 
    GEOIP_ENABLED=true     # Enable GeoIP (recommended)
GEOIP_ENABLED=false    # Disable GeoIP (faster ingestion, no geo data)

GEOIP_CITY_DB

  • Type: String (file path)
  • Default: geoip/GeoLite2-City.mmdb
  • Required: No (but recommended if GEOIP_ENABLED=true)
  • Description: Path to MaxMind GeoLite2 City database file. Provides city-level geolocation.
  • Download: MaxMind GeoLite2
  • Example: 
    GEOIP_CITY_DB=geoip/GeoLite2-City.mmdb              # Relative path
GEOIP_CITY_DB=/app/geoip/GeoLite2-City.mmdb         # Absolute path (Docker)

GEOIP_COUNTRY_DB

  • Type: String (file path)
  • Default: geoip/GeoLite2-Country.mmdb
  • Required: No (but recommended if GEOIP_ENABLED=true)
  • Description: Path to MaxMind GeoLite2 Country database file. Provides country-level geolocation.
  • Download: MaxMind GeoLite2
  • Example: 
    GEOIP_COUNTRY_DB=geoip/GeoLite2-Country.mmdb
GEOIP_COUNTRY_DB=/app/geoip/GeoLite2-Country.mmdb

GEOIP_ASN_DB

  • Type: String (file path)
  • Default: geoip/GeoLite2-ASN.mmdb
  • Required: No (but recommended if GEOIP_ENABLED=true)
  • Description: Path to MaxMind GeoLite2 ASN database file. Provides Autonomous System Number and organization data.
  • Download: MaxMind GeoLite2
  • Example: 
    GEOIP_ASN_DB=geoip/GeoLite2-ASN.mmdb
GEOIP_ASN_DB=/app/geoip/GeoLite2-ASN.mmdb

GEOIP_CACHE_SIZE

  • Type: Integer
  • Default: 10000
  • Required: No
  • Description: Number of IP addresses to cache in memory. Currently loaded but not fully implemented (reserved for future LRU caching).
  • Example: 
    GEOIP_CACHE_SIZE=10000    # Cache 10,000 IPs
GEOIP_CACHE_SIZE=50000    # Cache 50,000 IPs (higher memory usage)

Log Sources Configuration

LogLynx currently includes built-in parsers for Traefik, Caddy, Nginx, Apache, and HAProxy access logs. See the per-source wiki pages for format examples and recommended proxy/server configuration.

TRAEFIK_LOG_PATH

  • Type: String (file path)
  • Default: traefik/logs/access.log
  • Required: No
  • Description: Path to Traefik access log file. Can be absolute or relative to the working directory.
  • Example: 
    TRAEFIK_LOG_PATH=traefik/logs/access.log              # Relative path
TRAEFIK_LOG_PATH=/var/log/traefik/access.log          # Absolute path
TRAEFIK_LOG_PATH=/traefik/logs/access.log             # Docker volume

TRAEFIK_LOG_FORMAT

  • Type: String (enum)
  • Default: auto
  • Required: No
  • Description: Traefik log format. Use auto to automatically detect format, or specify json or clf explicitly.
  • Values: auto, json, clf (Common Log Format)
  • Example: 
    TRAEFIK_LOG_FORMAT=auto    # Auto-detect format (recommended)
TRAEFIK_LOG_FORMAT=json    # Force JSON parsing
TRAEFIK_LOG_FORMAT=clf     # Force Common Log Format parsing

LOG_AUTO_DISCOVER

  • Type: Boolean
  • Default: true
  • Required: No
  • Description: Automatically discover log files in directories. When enabled, LogLynx will scan for and monitor log files.
  • Values: true, false
  • Example: 
    LOG_AUTO_DISCOVER=true     # Auto-discover log files (recommended)
LOG_AUTO_DISCOVER=false    # Only monitor explicitly configured files

INITIAL_IMPORT_DAYS

  • Type: Integer
  • Default: 60
  • Required: No
  • Description: On first run, only import the last N days from log files. Prevents overwhelming the database with years of historical data. Set to 0 to import all historical data.
  • Recommended: 30-90 days
  • Example: 
    INITIAL_IMPORT_DAYS=60     # Import last 60 days on first run
INITIAL_IMPORT_DAYS=30     # Import last 30 days (faster initial load)
INITIAL_IMPORT_DAYS=0      # Import all historical data

INITIAL_IMPORT_ENABLE

  • Type: Boolean
  • Default: true
  • Required: No
  • Description: Enable or disable initial import limiting. When disabled, all historical data is imported regardless of INITIAL_IMPORT_DAYS.
  • Values: true, false
  • Example: 
    INITIAL_IMPORT_ENABLE=true     # Limit initial import (recommended)
INITIAL_IMPORT_ENABLE=false    # Import all historical data

Web Server Configuration

SERVER_HOST

  • Type: String (IP address or hostname)
  • Default: 0.0.0.0
  • Required: No
  • Description: Server bind address. Use 0.0.0.0 to listen on all network interfaces, or specify a specific IP/hostname.
  • Example: 
    SERVER_HOST=0.0.0.0        # All interfaces (default, recommended)
SERVER_HOST=127.0.0.1      # Localhost only (local development)
SERVER_HOST=192.168.1.100  # Specific IP address

SERVER_PORT

  • Type: Integer
  • Default: 8080
  • Required: No
  • Description: Port to listen on for HTTP traffic. Must be available and not in use by another service.
  • Range: 1-65535 (typically 1024-65535 for non-root users)
  • Example: 
    SERVER_PORT=8080     # Default port
SERVER_PORT=3000     # Alternative port
SERVER_PORT=80       # HTTP standard port (requires root/admin)

SERVER_PRODUCTION

  • Type: Boolean
  • Default: false
  • Required: No
  • Description: Enable production mode for Gin framework. In production mode, debug output is disabled and performance is optimized.
  • Values: true, false
  • Example: 
    SERVER_PRODUCTION=false    # Development mode (verbose logging)
SERVER_PRODUCTION=true     # Production mode (optimized, less logging)

TIMEZONE

  • Type: String (IANA timezone name)
  • Default: UTC
  • Required: No
  • Description: This variable is passed to the frontend and used to display chart labels and timestamps in the chosen timezone. If TIMEZONE is not set, LogLynx falls back to Docker's standard TZ environment variable, then UTC.
  • Example: 
    TIMEZONE=UTC
TIMEZONE=Europe/Amsterdam

DASHBOARD_ENABLED

  • Type: Boolean
  • Default: true
  • Required: No
  • Description: Enable or disable the dashboard web UI. When set to false, only the API routes at /api/v1 are exposed. Useful for headless/API-only deployments or security-focused setups.
  • Example: 
    DASHBOARD_ENABLED=true     # Full dashboard (default)
DASHBOARD_ENABLED=false    # API-only mode (no HTML pages served)

SPLASH_SCREEN_ENABLED

  • Type: Boolean
  • Default: true
  • Required: No
  • Description: Show a loading splash screen while initial log ingestion is in progress. Set to false to skip it and go directly to the dashboard.
  • Example: 
    SPLASH_SCREEN_ENABLED=true     # Show loading screen on startup (default)
SPLASH_SCREEN_ENABLED=false    # Skip splash screen

WIDGET_ENABLED

  • Type: Boolean
  • Default: true
  • Required: No
  • Description: Enable or disable the widget page (/widget) and widget API endpoints. Useful to hide widget endpoints on public instances.
  • Example: 
    WIDGET_ENABLED=true     # Enable widgets (default)
WIDGET_ENABLED=false    # Disable widgets

Alerting Configuration

ALERTS_ENABLED

  • Type: Boolean
  • Default: true
  • Required: No
  • Description: Enable or disable the alerting engine and Alerting page/API. When disabled, alert rules and channels remain stored but are not evaluated.
  • Example: 
    ALERTS_ENABLED=true     # Evaluate alert rules (default)
ALERTS_ENABLED=false    # Disable alert evaluation

ALERTS_EVAL_INTERVAL

  • Type: Duration
  • Default: 30s
  • Required: No
  • Description: How often the alerting engine evaluates enabled rules against recent request data.
  • Format: Go duration format (e.g., 15s, 30s, 1m, 5m)
  • Example: 
    ALERTS_EVAL_INTERVAL=30s
ALERTS_EVAL_INTERVAL=1m

Alert notification credentials are configured per channel in the UI or API and stored in the database as channel-specific JSON. Supported channel types are Discord, Email/SMTP, Telegram, and generic HTTPS webhooks.

Anonymous Usage Telemetry

LogLynx can send an anonymous heartbeat ping to the project maintainers so they can estimate the number of active instances. No personal data, hostnames, IP addresses, domain names, log paths, or traffic data are ever sent. The only information included is a hashed instance identifier, the app version, and the Go runtime version.

LOGLYNX_USAGE_TELEMETRY

  • Type: Boolean
  • Default: true
  • Required: No
  • Description: Enable or disable anonymous usage telemetry. Set to false to opt out entirely.
  • Example: 
    LOGLYNX_USAGE_TELEMETRY=true     # Opt in (default)
LOGLYNX_USAGE_TELEMETRY=false    # Opt out

LOGLYNX_USAGE_TELEMETRY_ENDPOINT

  • Type: String (URL)
  • Default: "" (uses the endpoint embedded at build time via -ldflags)
  • Required: No
  • Description: Override the telemetry endpoint URL. Official Docker images have the endpoint embedded at build time; self-built binaries can set this to point to a custom collector or leave it empty to disable sending.
  • Example: 
    LOGLYNX_USAGE_TELEMETRY_ENDPOINT=     # Use embedded build endpoint (default)

LOGLYNX_USAGE_TELEMETRY_INTERVAL

  • Type: Duration
  • Default: 1h
  • Required: No
  • Description: How often to send heartbeat pings after the initial startup ping.
  • Format: Go duration format (e.g., 30m, 1h, 6h)
  • Example: 
    LOGLYNX_USAGE_TELEMETRY_INTERVAL=1h    # Ping every hour (default)
LOGLYNX_USAGE_TELEMETRY_INTERVAL=6h    # Less frequent pings

Logging Configuration

LOG_LEVEL

  • Type: String (enum)
  • Default: info
  • Required: No
  • Description: Application log level. Controls verbosity of application logs.
  • Values: trace, debug, info, warn, error, fatal
  • Example: 
    LOG_LEVEL=info     # Normal operation (recommended)
LOG_LEVEL=debug    # Detailed debugging information
LOG_LEVEL=warn     # Only warnings and errors
LOG_LEVEL=error    # Only errors and fatal messages

Log Level Guide:

  • trace: Extremely verbose, shows every operation
  • debug: Detailed debugging information for troubleshooting
  • info: Normal operation, informational messages
  • warn: Warnings that don't affect operation
  • error: Errors that need attention
  • fatal: Critical errors that cause shutdown

Performance Tuning

METRICS_INTERVAL

  • Type: Duration
  • Default: 5s (5 seconds)
  • Required: No
  • Description: How often to collect real-time metrics. Lower values provide more granular data but increase CPU usage.
  • Format: Go duration format (e.g., 1s, 5s, 10s)
  • Recommended: 5-10 seconds
  • Example: 
    METRICS_INTERVAL=5s     # Update every 5 seconds (default)
METRICS_INTERVAL=10s    # Update every 10 seconds (lower CPU)
METRICS_INTERVAL=1s     # Update every second (higher granularity)

BATCH_SIZE

  • Type: Integer
  • Default: 1000
  • Required: No
  • Description: Batch size for bulk database inserts. Higher values improve throughput but increase memory usage.
  • Recommended: 500-5000 depending on traffic volume and available memory
  • Example: 
    BATCH_SIZE=1000    # Default (good balance)
BATCH_SIZE=500     # Smaller batches (lower memory)
BATCH_SIZE=5000    # Larger batches (higher throughput)

WORKER_POOL_SIZE

  • Type: Integer
  • Default: 4
  • Required: No
  • Description: Number of worker goroutines for parallel log processing. Should typically match CPU core count.
  • Recommended: Equal to CPU core count
  • Example: 
    WORKER_POOL_SIZE=4     # 4-core CPU (default)
WORKER_POOL_SIZE=8     # 8-core CPU
WORKER_POOL_SIZE=2     # 2-core CPU or resource-constrained

Complete Reference Table

Variable Type Default Required Description
Database
DB_PATH string loglynx.db No SQLite database file path
DB_MAX_OPEN_CONNS integer 10 No Maximum open connections
DB_MAX_IDLE_CONNS integer 3 No Maximum idle connections
DB_CONN_MAX_LIFE duration 1h No Connection max lifetime
DB_RETENTION_DAYS integer 60 No Data retention period (0=unlimited)
DB_CLEANUP_INTERVAL duration 1h No Cleanup check interval
DB_CLEANUP_TIME string 02:00 No Daily cleanup time (HH:MM)
DB_VACUUM_ENABLED boolean true No Enable VACUUM after cleanup
GeoIP
GEOIP_ENABLED boolean true No Enable GeoIP enrichment
GEOIP_CITY_DB string geoip/GeoLite2-City.mmdb No City database path
GEOIP_COUNTRY_DB string geoip/GeoLite2-Country.mmdb No Country database path
GEOIP_ASN_DB string geoip/GeoLite2-ASN.mmdb No ASN database path
GEOIP_CACHE_SIZE integer 10000 No In-memory cache size (reserved)
Log Sources
TRAEFIK_LOG_PATH string traefik/logs/access.log No Traefik log file path
TRAEFIK_LOG_FORMAT string auto No Log format (auto/json/clf)
LOG_AUTO_DISCOVER boolean true No Auto-discover log files
INITIAL_IMPORT_DAYS integer 60 No Initial import limit (0=all)
INITIAL_IMPORT_ENABLE boolean true No Enable initial import limiting
Web Server
SERVER_HOST string 0.0.0.0 No Server bind address
SERVER_PORT integer 8080 No Server listen port
SERVER_PRODUCTION boolean false No Production mode flag
TIMEZONE string UTC No Dashboard timezone; falls back to TZ if unset
DASHBOARD_ENABLED boolean true No Enable dashboard UI (false = API-only mode)
SPLASH_SCREEN_ENABLED boolean true No Show splash screen during initial ingestion
WIDGET_ENABLED boolean true No Enable widget page and endpoints
Alerting
ALERTS_ENABLED boolean true No Enable alert rule evaluation
ALERTS_EVAL_INTERVAL duration 30s No Alert rule evaluation interval
Telemetry
LOGLYNX_USAGE_TELEMETRY boolean true No Enable anonymous heartbeat telemetry
LOGLYNX_USAGE_TELEMETRY_ENDPOINT string "" No Telemetry endpoint URL override
LOGLYNX_USAGE_TELEMETRY_INTERVAL duration 1h No Heartbeat ping interval
Logging
LOG_LEVEL string info No Log level (trace/debug/info/warn/error/fatal)
Performance
METRICS_INTERVAL duration 1s No Metrics collection interval
BATCH_SIZE integer 1000 No Bulk insert batch size
WORKER_POOL_SIZE integer 4 No Log processing workers

Docker Environment Variables

When running LogLynx in Docker, environment variables can be set in multiple ways:

Using -e Flag

docker run -d \
  -e DB_PATH=/data/loglynx.db \
  -e SERVER_PORT=8080 \
  -e GEOIP_ENABLED=true \
  -p 8080:8080 \
  loglynx:latest

Using --env-file

# Create env file
cat > loglynx.env <<EOF
DB_PATH=/data/loglynx.db
DB_RETENTION_DAYS=90
GEOIP_ENABLED=true
SERVER_PORT=8080
LOG_LEVEL=info
EOF

# Run with env file
docker run -d --env-file loglynx.env -p 8080:8080 loglynx:latest

Using Docker Compose

version: '3.8'

services:
  loglynx:
    image: loglynx:latest
    environment:
      - DB_PATH=/data/loglynx.db
      - DB_RETENTION_DAYS=90
      - GEOIP_ENABLED=true
      - GEOIP_CITY_DB=/app/geoip/GeoLite2-City.mmdb
      - TRAEFIK_LOG_PATH=/traefik/logs/access.log
      - SERVER_PORT=8080
      - LOG_LEVEL=info
    ports:
      - "8080:8080"
    volumes:
      - ./data:/data
      - ./geoip:/app/geoip
      - /var/log/traefik:/traefik/logs:ro

Configuration Examples

Minimal Configuration (Defaults)

# Use all defaults - works out of the box
# No .env file needed

Development Configuration

# .env for local development
DB_PATH=dev.db
DB_RETENTION_DAYS=7
SERVER_PORT=3000
SERVER_PRODUCTION=false
LOG_LEVEL=debug
GEOIP_ENABLED=false
INITIAL_IMPORT_DAYS=7

Production Configuration

# .env for production deployment
DB_PATH=/data/loglynx.db
DB_MAX_OPEN_CONNS=25
DB_MAX_IDLE_CONNS=10
DB_RETENTION_DAYS=90
DB_CLEANUP_TIME=03:00
DB_VACUUM_ENABLED=true

GEOIP_ENABLED=true
GEOIP_CITY_DB=/app/geoip/GeoLite2-City.mmdb
GEOIP_COUNTRY_DB=/app/geoip/GeoLite2-Country.mmdb
GEOIP_ASN_DB=/app/geoip/GeoLite2-ASN.mmdb

TRAEFIK_LOG_PATH=/var/log/traefik/access.log
TRAEFIK_LOG_FORMAT=json
INITIAL_IMPORT_DAYS=60

SERVER_HOST=0.0.0.0
SERVER_PORT=8080
SERVER_PRODUCTION=true
LOG_LEVEL=info

METRICS_INTERVAL=5s
BATCH_SIZE=2000
WORKER_POOL_SIZE=8

High-Traffic Configuration

# .env for high-traffic scenarios
DB_PATH=/data/loglynx.db
DB_MAX_OPEN_CONNS=50
DB_MAX_IDLE_CONNS=20
DB_CONN_MAX_LIFE=30m
DB_RETENTION_DAYS=30
DB_CLEANUP_TIME=04:00

GEOIP_ENABLED=true
GEOIP_CACHE_SIZE=50000

TRAEFIK_LOG_PATH=/var/log/traefik/access.log
TRAEFIK_LOG_FORMAT=json

SERVER_PRODUCTION=true
LOG_LEVEL=warn

METRICS_INTERVAL=10s
BATCH_SIZE=5000
WORKER_POOL_SIZE=16

Troubleshooting

Database Lock Errors

If you encounter "database is locked" errors:

# Reduce connection pool size
DB_MAX_OPEN_CONNS=5
DB_MAX_IDLE_CONNS=2

High Memory Usage

If LogLynx consumes too much memory:

# Reduce batch size and cache
BATCH_SIZE=500
GEOIP_CACHE_SIZE=5000

Slow Performance

To improve performance:

# Increase parallelism
WORKER_POOL_SIZE=8
BATCH_SIZE=2000

# Increase connection pool
DB_MAX_OPEN_CONNS=25

Missing GeoIP Data

If geographic data isn't showing:

# Check GeoIP settings
GEOIP_ENABLED=true
GEOIP_CITY_DB=geoip/GeoLite2-City.mmdb

# Verify files exist
ls -la geoip/

Log Files Not Processing

If logs aren't being processed:

# Enable debug logging
LOG_LEVEL=debug

# Check log path
TRAEFIK_LOG_PATH=/var/log/traefik/access.log

# Try auto-discovery
LOG_AUTO_DISCOVER=true

Environment Variable Loading Order

LogLynx loads configuration in the following order (later sources override earlier ones):

  1. Compiled defaults - Built into the application
  2. .env file - Loaded from current directory
  3. System environment variables - OS-level environment variables
  4. Docker/Kubernetes env - Container-level environment variables

Validation

LogLynx validates all environment variables on startup. Invalid values will result in warnings or errors:

Example validation errors:

ERROR: DB_RETENTION_DAYS must be >= 0
ERROR: SERVER_PORT must be between 1 and 65535
ERROR: LOG_LEVEL must be one of: trace, debug, info, warn, error, fatal
ERROR: TRAEFIK_LOG_FORMAT must be one of: auto, json, clf

Security Considerations

  • File Permissions: Ensure .env file has restricted permissions (chmod 600 .env)
  • Secrets Management: For production, consider using secret management tools instead of .env files
  • Database Path: Ensure database directory has proper permissions
  • Log File Access: LogLynx needs read access to Traefik log files

Last Updated: June 2026

LogLynx Wiki

Getting Started

Deployment

Reverse proxy recommended configuration

Key features

Side features

Quick Links

API Endpoints

Configuration

Deployment

Support

Clone this wiki locally