Environment Variables

Agent Environment Variables

The agent is a lightweight Go service that reads and serves Traefik logs.

Variable	Description	Default	Required
`TRAEFIK_LOG_DASHBOARD_ACCESS_PATH`	Path to Traefik access log file or directory	`/var/log/traefik/access.log`	Yes
`TRAEFIK_LOG_DASHBOARD_ERROR_PATH`	Path to Traefik error log file or directory	`/var/log/traefik/traefik.log`	No
`TRAEFIK_LOG_DASHBOARD_AUTH_TOKEN`	Bearer token for authentication	-	Yes
`TRAEFIK_LOG_DASHBOARD_LOG_FORMAT`	Log format (`json` or `common`)	`json`	No
`TRAEFIK_LOG_DASHBOARD_SYSTEM_MONITORING`	Enable CPU/memory/disk monitoring	`true`	No
`TRAEFIK_LOG_DASHBOARD_MONITOR_INTERVAL`	System monitoring interval (ms)	`2000`	No
`POSITION_FILE`	File to store log read positions	`/data/.position`	No
`PORT`	Agent listen port	`5000`	No

Example Agent Configuration

environment:
  - TRAEFIK_LOG_DASHBOARD_ACCESS_PATH=/logs/access.log
  - TRAEFIK_LOG_DASHBOARD_ERROR_PATH=/logs/traefik.log
  - TRAEFIK_LOG_DASHBOARD_AUTH_TOKEN=your-secret-token
  - TRAEFIK_LOG_DASHBOARD_SYSTEM_MONITORING=true
  - TRAEFIK_LOG_DASHBOARD_LOG_FORMAT=json
  - PORT=5000

Dashboard Environment Variables

The dashboard server reads runtime environment variables directly (Docker Compose-friendly).

Agent Configuration (Environment-Managed)

Variable	Description	Default	Required
`AGENT_1_URL`	URL of first environment agent	-	Yes (or `DASHBOARD_AGENTS_JSON`)
`AGENT_1_TOKEN`	Token for first environment agent	`""`	No
`AGENT_1_NAME`	Display name for first environment agent	`Agent 1`	No
`AGENT_1_ID`	Stable agent id (must be unique)	`agent-env-1`	No
`AGENT_1_LOCATION`	`on-site` or `off-site`	`on-site`	No
`AGENT_1_DESCRIPTION`	Optional description	-	No
`AGENT_1_TAGS`	Comma-separated tags	-	No
`AGENT_2_URL`, `AGENT_3_URL`, ...	Additional agents using the same key pattern	-	No
`DASHBOARD_AGENTS_JSON`	JSON array alternative for multi-agent config	-	No
`DASHBOARD_AGENTS_ENV_ONLY`	Disable UI/API agent mutations (`true` = env-only)	`false`	No

Legacy fallback (kept for compatibility): AGENT_API_URL, AGENT_API_TOKEN, AGENT_NAME.

Display Configuration

Variable	Description	Default	Required
`DASHBOARD_REFRESH_INTERVAL_MS`	Refresh/poll interval	`5000`	No
`DASHBOARD_MAX_LOGS_DISPLAY`	Maximum logs retained in dashboard state	`1000`	No
`DASHBOARD_TRAFFIC_TOP_ITEMS_LIMIT`	Top-N shown in Traffic cards/lists	`10`	No
`DASHBOARD_PARSER_TREND_WINDOW_MINUTES`	Parser trend window in System tab (15-30)	`30`	No
`DASHBOARD_HIDE_INTERNAL_TRAFFIC_DEFAULT`	Default state for header toggle to hide dashboard/agent noise traffic	`true`	No
`DASHBOARD_INTERNAL_NOISE_PATH_PREFIXES`	Comma-separated request path prefixes treated as internal noise	`/api/system/resources,/api/logs/status,/api/location,/api/dashboard/agents/check-status`	No
`DASHBOARD_INTERNAL_NOISE_SERVICE_PATTERNS`	Comma-separated `ServiceName`/`RouterName` substrings treated as internal noise	`dashboard,agent,traefik-log-dashboard,log-dashboard`	No
`SHOW_DEMO_PAGE`	Show demo dashboard link	`true`	No
`DASHBOARD_DENSITY`	UI density (`compact`, `comfortable`)	`comfortable`	No

GeoIP Configuration

Geographic lookup is handled by the dashboard /api/location/* service.

Variable	Description	Default	Required
`GEOIP_LOOKUP_ENABLED`	Enable/disable GeoIP lookup service	`true`	No
`GEOIP_LOCAL_DB_PATH`	Optional local GeoLite2/MaxMind MMDB path (country or city DB)	`""`	No
`GEOIP_PROVIDER_BASE_URL`	Geo provider base URL	`https://ipwho.is`	No
`GEOIP_PROVIDER_URLS`	Comma-separated provider list for ordered HTTP fallback	Uses `GEOIP_PROVIDER_BASE_URL`	No
`GEOIP_LOOKUP_TIMEOUT_MS`	Lookup timeout (ms)	`3500`	No
`GEOIP_LOOKUP_MAX_IPS`	Max IPs per lookup request	`256`	No
`GEOIP_LOOKUP_CONCURRENCY`	Parallel lookups per request	`10`	No
`GEOIP_LOOKUP_CACHE_TTL_MS`	Cache TTL (ms)	`3600000`	No
`GEOIP_UNKNOWN_CACHE_TTL_MS`	Cache TTL for unresolved (`Unknown`) lookups	`300000`	No
`GEOIP_LOOKUP_CACHE_MAX_ENTRIES`	Max cache entries	`10000`	No

Server Configuration

Variable	Description	Default	Required
`NODE_ENV`	Node environment	`production`	No
`PORT`	Dashboard listen port	`3000`	No
`DATA_DIR`	Data directory for dashboard SQLite	`/data`	No
`BASE_PATH`	Base path for reverse-proxy deployments	`""`	No
`BASE_DOMAIN`	Base domain override	`""`	No

Security Configuration

Variable	Description	Default	Required
`ALERTS_API_KEY`	API key required for alert mutation endpoints	`""`	No
`ALERT_ALLOW_PRIVATE_WEBHOOKS`	Allow private network webhook targets	`false`	No

Alert Scheduler Configuration

Variable	Description	Default	Required
`ALERT_SCHEDULER_INTERVAL_MS`	Scheduler execution interval	`300000` (5 min)	No
`ALERT_FETCH_LINES`	Access lines fetched per alert evaluation	`5000`	No

Example Dashboard Configuration (Compose)

environment:
  # Multi-agent env configuration
  - AGENT_1_NAME=Primary
  - AGENT_1_URL=http://traefik-agent:5000
  - AGENT_1_TOKEN=your-secret-token
  - AGENT_2_NAME=Staging
  - AGENT_2_URL=http://staging-agent:5000
  - AGENT_2_TOKEN=staging-secret-token
  - DASHBOARD_AGENTS_ENV_ONLY=true

  # Display / UI
  - DASHBOARD_REFRESH_INTERVAL_MS=5000
  - DASHBOARD_MAX_LOGS_DISPLAY=1000
  - DASHBOARD_TRAFFIC_TOP_ITEMS_LIMIT=25
  - DASHBOARD_PARSER_TREND_WINDOW_MINUTES=30
  - DASHBOARD_HIDE_INTERNAL_TRAFFIC_DEFAULT=true
  - DASHBOARD_INTERNAL_NOISE_PATH_PREFIXES=/api/system/resources,/api/logs/status,/api/location,/api/dashboard/agents/check-status
  - DASHBOARD_INTERNAL_NOISE_SERVICE_PATTERNS=dashboard,agent,traefik-log-dashboard,log-dashboard
  - SHOW_DEMO_PAGE=true
  - GEOIP_LOOKUP_ENABLED=true
  - GEOIP_LOCAL_DB_PATH=/geoip/GeoLite2-City.mmdb
  - GEOIP_PROVIDER_URLS=https://ipwho.is,https://ip-api.com/json
  - GEOIP_PROVIDER_BASE_URL=https://ipwho.is
  - GEOIP_UNKNOWN_CACHE_TTL_MS=300000

  # Server
  - NODE_ENV=production
  - PORT=3000

Compose Compatibility Notes

Runtime dashboard variables above can all be set directly in docker-compose.yml.
Build-time VITE_* values are development/build variables, not runtime container settings.

CLI Environment Variables

The CLI is a terminal-based dashboard application.

Variable	Description	Default	Required
`TRAEFIK_LOG_DASHBOARD_ACCESS_PATH`	Path to Traefik access log	-	Yes (file mode)
`TRAEFIK_LOG_DASHBOARD_AGENT_URL`	Agent API URL	-	Yes (agent mode)
`TRAEFIK_LOG_DASHBOARD_AUTH_TOKEN`	Agent authentication token	-	Yes (agent mode)

Complete Docker Compose Example

services:
  traefik-agent:
    image: hhftechnology/traefik-log-dashboard-agent:latest
    environment:
      - TRAEFIK_LOG_DASHBOARD_ACCESS_PATH=/logs/access.log
      - TRAEFIK_LOG_DASHBOARD_ERROR_PATH=/logs/traefik.log
      - TRAEFIK_LOG_DASHBOARD_AUTH_TOKEN=your-secret-token
      - TRAEFIK_LOG_DASHBOARD_SYSTEM_MONITORING=true
      - TRAEFIK_LOG_DASHBOARD_LOG_FORMAT=json
      - PORT=5000
    volumes:
      - /var/log/traefik:/logs:ro
      - ./data/positions:/data

  traefik-dashboard:
    image: hhftechnology/traefik-log-dashboard:latest
    environment:
      - AGENT_API_URL=http://traefik-agent:5000
      - AGENT_API_TOKEN=your-secret-token
      - AGENT_NAME=Production Agent
      - NODE_ENV=production
      - PORT=3000
    volumes:
      - ./data/dashboard:/app/data
    depends_on:
      - traefik-agent

On this page