gghstats.env.example

# /etc/gghstats/gghstats.env — gghstats environment (systemd EnvironmentFile)
# Installed by .deb/.rpm as /etc/gghstats/gghstats.env (config|noreplace).
# From source:
#   sudo mkdir -p /etc/gghstats /var/lib/gghstats
#   sudo cp contrib/gghstats.env.example /etc/gghstats/gghstats.env
#   sudo chmod 600 /etc/gghstats/gghstats.env   # required when token is set
#   sudo systemctl enable --now gghstats
#
# Format: KEY=value (no "export"). See README "Configuration" and contrib/systemd/README.md.

# Required (unless demo mode)
GGHSTATS_GITHUB_TOKEN=

# Demo UI with sample data (no token, no GitHub sync). Unset for production.
# GGHSTATS_DEMO=true

# SQLite (keep on persistent disk). Absolute path for daemons.
# Default when unset is the platform config dir (Linux ~/.config/gghstats/, macOS ~/Library/Application Support/gghstats/).
# Recommended: /var/lib/gghstats/gghstats.db (Linux), /var/db/gghstats/… (BSD),
#   ~/Library/Application Support/gghstats/gghstats.db (macOS LaunchAgent).
# See README "Data directory (SQLite paths)".
GGHSTATS_DB=/var/lib/gghstats/gghstats.db

# HTTP: 127.0.0.1 behind a reverse proxy on the same host. Public TLS/Traefik stacks: use gghstats-selfhosted instead.
GGHSTATS_HOST=127.0.0.1
GGHSTATS_PORT=8080

# Repo scope (avoid * on large accounts during first tests)
GGHSTATS_FILTER='your-github-user/*,!fork,!archived'

GGHSTATS_SYNC_INTERVAL=1h
GGHSTATS_SYNC_ON_STARTUP=true
GGHSTATS_SYNC_WORKERS=4
GGHSTATS_INCLUDE_PRIVATE=false

# Open default browser on startup (local try; same as gghstats serve --open)
# GGHSTATS_OPEN_BROWSER=true

# Optional API protection (sidebar sync, /api/repos, manual sync, dogfood JSON)
# GGHSTATS_API_TOKEN=

# API-only mode (gghstats >= 0.11.0) — skip HTML dashboard + /robots.txt + /sitemap.xml
# GGHSTATS_API_ONLY=true

# CORS for authenticated JSON (gghstats >= 0.11.0). Empty = *. Prefer explicit origins with API-only.
# GGHSTATS_CORS_ORIGINS=https://app.example.com

# CSP (gghstats >= 0.11.0): default Report-Only; set enforce only when HEAD_HTML is empty
# GGHSTATS_CSP=enforce

# Optional: public URL behind reverse proxy (badges, sitemap, robots). Set GGHSTATS_HOSTNAME in gghstats-selfhosted Traefik .env.
# GGHSTATS_PUBLIC_URL=https://stats.example.com

# UI locales (dashboard only)
GGHSTATS_DEFAULT_LOCALE=en
GGHSTATS_ENABLED_LOCALES=en,es,de,fr,pt-br

# GGHSTATS_LOG_LEVEL=info

# Rate limiting (enabled by default; set to false to disable)
# Rate limiting (gghstats >= 0.7.5) — exempt: /metrics, /healthz, /api/v1/badge/*
# GGHSTATS_RATE_LIMIT_ENABLED=true
# GGHSTATS_RATE_LIMIT_REQUESTS=120
# GGHSTATS_RATE_LIMIT_PERIOD=1m
# GGHSTATS_RATE_LIMIT_BURST=20
# Trusted proxies for client IP headers (gghstats >= 0.10.2).
# Empty/default = ignore X-Forwarded-For and X-Real-IP; set only to your proxy IP/CIDR.
# See README "Client IP behind reverse proxies" for situations A/B/C.
# GGHSTATS_TRUSTED_PROXIES=127.0.0.1/32,::1/128

# IP whitelist (gghstats >= 0.7.6) — /api/v1/badge/* stays public for README embeds
# GGHSTATS_WHITELIST=10.0.0.0/8,172.16.0.0/12
# GGHSTATS_WHITELIST_PATHS=/api/,/h2h

# Head HTML injection (gghstats >= 0.7.9) — raw HTML injected just before </head>
# on every page. Useful for analytics scripts, extra CSS, etc.
# GGHSTATS_HEAD_HTML='<script defer src="https://example.com/analytics.js"></script>'

# Reverse proxy rules (gghstats >= 0.7.9) — JSON array of local→remote mappings
# with optional custom headers. Keeps third-party scripts on the same domain.
# Must be single-quoted when using `source` in shell (to prevent brace expansion).
# GGHSTATS_REVERSE_PROXY_RULES='[{"local":"/kiko","url":"https://events.example.com","headers":{"Host":"kiko-backend"}}]'

# Anonymous usage collection (gghstats >= 0.7.9) — sends anonymous, non-identifying
# feature flags on startup. Set to "true" to enable.
# GGHSTATS_ENABLE_COLLECTOR=true

# Update check (gghstats >= 0.7.9) — checks GitHub API for newer releases on startup.
# Enabled by default. Set to "false" to disable.
# GGHSTATS_ENABLE_UPDATE_CHECK=false

# ---------------------------------------------------------------------------
# Opt-in alerts (0.10.x — sinks first; rules evaluate after sync). SPEC §8.
# Off by default. If ENABLED=true, at least one valid sink is required (fail closed).
# Put secrets in env vars; reference them from JSON via *_env (do not commit URLs).
# ---------------------------------------------------------------------------
# GGHSTATS_ALERTS_ENABLED=false
# GGHSTATS_SLACK_WEBHOOK_URL=
# GGHSTATS_DISCORD_WEBHOOK_URL=
# GGHSTATS_LOKI_URL=
# GGHSTATS_LOKI_TENANT=
# GGHSTATS_SMTP_HOST=
# GGHSTATS_SMTP_PORT=587
# GGHSTATS_SMTP_USER=
# GGHSTATS_SMTP_PASSWORD=
# GGHSTATS_SMTP_FROM=
# GGHSTATS_SMTP_TO=
# GGHSTATS_ALERT_SINKS='[
#   {"type":"slack","webhook_url_env":"GGHSTATS_SLACK_WEBHOOK_URL"},
#   {"type":"webhook","url_env":"GGHSTATS_DISCORD_WEBHOOK_URL","body":"discord"},
#   {"type":"loki","url_env":"GGHSTATS_LOKI_URL","headers_env":{"X-Scope-OrgID":"GGHSTATS_LOKI_TENANT"},"labels":{"job":"gghstats","source":"alert"}},
#   {"type":"smtp","host_env":"GGHSTATS_SMTP_HOST","port_env":"GGHSTATS_SMTP_PORT","user_env":"GGHSTATS_SMTP_USER","password_env":"GGHSTATS_SMTP_PASSWORD","from_env":"GGHSTATS_SMTP_FROM","to_env":"GGHSTATS_SMTP_TO"}
# ]'
# GGHSTATS_ALERT_RULES='[
#   {"repo":"hrodrig/pgwd","metric":"clones","window":"1d","op":"gte","value":225,"debounce":"once_per_utc_day"},
#   {"repo":"hrodrig/groot","metric":"clones","window":"1d","op":"eq","value":0,"debounce":"once_per_utc_day"},
#   {"scope":"all_repos","metric":"clones","window":"lifetime","op":"gte","value":30000,"debounce":"once","fire":"once"},
#   {"repo":"hrodrig/pgwd","metric":"stars","milestones":[100,500],"fire":"once"},
#   {"kind":"ops","event":"repo_fetch_failed","window":"this_sync","op":"gte","value":3,"level":"warn","debounce":"once_per_utc_day"},
#   {"kind":"ops","event":"sync_failed","window":"consecutive_runs","op":"gte","value":2,"level":"crit"},
#   {"kind":"ops","event":"rate_limit","op":"lt","value":100,"level":"warn","debounce":"once_per_utc_day"},
#   {"kind":"ops","event":"github_unreachable","window":"this_sync","op":"gte","value":1,"level":"crit"}
# ]'
#
# Smoke-test sinks without serve/sync (does not require ALERTS_ENABLED):
#   gghstats alert test
#   gghstats alert test --kind ops --sink loki
#   gghstats alert test --sink smtp
# Traffic + star milestones evaluate after each successful sync; ops after every sync attempt.