Skip to content

Home

Jump to bottom
Kolin edited this page Nov 15, 2025 · 2 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

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)

DASHBOARD_ENABLED

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

SPLASH_SCREEN_ENABLED

  • Type: Boolean
  • Default: true
  • Required: No
  • Description: Enable or disable the splash screen on startup. When enabled, shows a loading screen while initial logs are being processed. Provides visual feedback during application initialization.
  • Values: true, false
  • Example: 
    SPLASH_SCREEN_ENABLED=true     # Show loading screen (default)
SPLASH_SCREEN_ENABLED=false    # Skip splash screen

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
DASHBOARD_ENABLED boolean true No Enable dashboard UI (false for API-only)
SPLASH_SCREEN_ENABLED boolean true No Enable startup splash screen
Logging
LOG_LEVEL string info No Log level (trace/debug/info/warn/error/fatal)
Performance
METRICS_INTERVAL duration 5s 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
      - SERVER_PRODUCTION=true
      - DASHBOARD_ENABLED=true
      - SPLASH_SCREEN_ENABLED=true
      - 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
DASHBOARD_ENABLED=true
SPLASH_SCREEN_ENABLED=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
DASHBOARD_ENABLED=true
SPLASH_SCREEN_ENABLED=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
DASHBOARD_ENABLED=true
SPLASH_SCREEN_ENABLED=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: November 2025

LogLynx Wiki

Getting Started

Deployment

Reverse proxy recommended configuration

Key features

Quick Links

API Endpoints

Configuration

Deployment

Support

Clone this wiki locally