watchdog/docs/configuration.md

Configuration

Watchdog supports multiple configuration sources with the following precedence (highest to lowest):

1. Command-line flags
2. Environment variables
3. Configuration file
4. Defaults

Configuration File

The primary configuration method is via YAML file. By default, Watchdog looks for:

• ./config.yaml (current directory)
• /etc/watchdog/config.yaml (system-wide)

Specify a custom location:

# Provide your configuration YAML file with --config
$ watchdog --config /path/to/config.yaml

See config.example.yaml for all available options.

Environment Variables

All configuration options can be set via environment variables with the WATCHDOG_ prefix.

Nested fields use underscore separators. For example:

# site.domains
$ export WATCHDOG_SITE_DOMAINS="example.com,blog.example.com"

# server.listen_addr
$ export WATCHDOG_SERVER_LISTEN_ADDR="127.0.0.1:8080"

# site.collect.pageviews
$ export WATCHDOG_SITE_COLLECT_PAGEVIEWS=true

# limits.max_paths
$ export WATCHDOG_LIMITS_MAX_PATHS=10000

Common Environment Variables

# Server
WATCHDOG_SERVER_LISTEN_ADDR="127.0.0.1:8080"
WATCHDOG_SERVER_METRICS_PATH="/metrics"
WATCHDOG_SERVER_INGESTION_PATH="/api/event"
WATCHDOG_SERVER_STATE_PATH="/var/lib/watchdog/hll.state"

# Site
WATCHDOG_SITE_DOMAINS="example.com" # comma-separated for multiple
WATCHDOG_SITE_SALT_ROTATION="daily"
WATCHDOG_SITE_SAMPLING=1.0

# Collection
WATCHDOG_SITE_COLLECT_PAGEVIEWS=true
WATCHDOG_SITE_COLLECT_COUNTRY=true
WATCHDOG_SITE_COLLECT_DEVICE=true
WATCHDOG_SITE_COLLECT_REFERRER="domain"
WATCHDOG_SITE_COLLECT_DOMAIN=false

# Limits
WATCHDOG_LIMITS_MAX_PATHS=10000
WATCHDOG_LIMITS_MAX_SOURCES=500
WATCHDOG_LIMITS_MAX_CUSTOM_EVENTS=100
WATCHDOG_LIMITS_MAX_EVENTS_PER_MINUTE=10000

# Security
WATCHDOG_SECURITY_CORS_ENABLED=false
WATCHDOG_SECURITY_METRICS_AUTH_ENABLED=false
WATCHDOG_SECURITY_METRICS_AUTH_USERNAME="admin"
WATCHDOG_SECURITY_METRICS_AUTH_PASSWORD="changeme"

Command-Line Flags

Command-line flags override both config file and environment variables:

# Override server address
watchdog --listen-addr :9090

# Override metrics path
watchdog --metrics-path /prometheus/metrics

# Override ingestion path
watchdog --ingestion-path /api/v1/event

# Combine multiple overrides
watchdog --config prod.yaml --listen-addr :9090 --metrics-path /metrics

Available flags:

• --config string - Path to config file
• --listen-addr string - Server listen address
• --metrics-path string - Metrics endpoint path
• --ingestion-path string - Ingestion endpoint path

Configuration Precedence Example

Given:

config.yaml:

server:
  listen_addr: ":8080"
  metrics_path: "/metrics"

Environment:

export WATCHDOG_SERVER_LISTEN_ADDR=":9090"

Command:

watchdog --metrics-path "/prometheus/metrics"

Result:

• listen_addr: :9090 (from environment variable)
• metrics_path: /prometheus/metrics (from CLI flag)

Systemd Integration

Environment variables work seamlessly with systemd:

[Service]
Environment="WATCHDOG_SERVER_LISTEN_ADDR=127.0.0.1:8080"
Environment="WATCHDOG_SITE_DOMAINS=example.com"
Environment="WATCHDOG_LIMITS_MAX_PATHS=10000"
ExecStart=/usr/local/bin/watchdog --config /etc/watchdog/config.yaml

Or use EnvironmentFile:

[Service]
EnvironmentFile=/etc/watchdog/env
ExecStart=/usr/local/bin/watchdog

/etc/watchdog/env:

WATCHDOG_SERVER_LISTEN_ADDR=127.0.0.1:8080
WATCHDOG_SITE_DOMAINS=example.com
WATCHDOG_LIMITS_MAX_PATHS=10000

NixOS Integration

NixOS configuration automatically converts to the correct format:

{
  services.watchdog = {
    enable = true;
    settings = {
      site.domains = [ "example.com" ];
      server.listen_addr = "127.0.0.1:8080";
      limits.max_paths = 10000;
    };
  };
}

This is equivalent to setting environment variables or using a config file.

Validation

Configuration is validated on startup. Invalid values will cause Watchdog to exit with an error:

$ watchdog
Error: config validation failed: site.domains is required

Common validation errors:

• site.domains is required - No domains configured
• limits.max_paths must be greater than 0 - Invalid cardinality limit
• site.collect.referrer must be 'off', 'domain', or 'url' - Invalid referrer mode
• site.sampling must be between 0.0 and 1.0 - Invalid sampling rate

Best Practices

1. Use config file for base configuration - Easier to version control and review
2. Use environment variables for secrets - Don't commit passwords to config files
3. Use CLI flags for testing/overrides - Quick temporary changes without editing files

Example hybrid approach:

config.yaml:

site:
  domains:
    - example.com
  collect:
    pageviews: true
    device: true

limits:
  max_paths: 10000

Environment (secrets):

export WATCHDOG_SECURITY_METRICS_AUTH_PASSWORD="$SECRET_PASSWORD"

CLI (testing):

watchdog --listen-addr :9090  # Test on different port