FAIRVISOR Docs
⌘K
GitHub fairvisor.com

Environment Variables

Fairvisor Edge is configured entirely through environment variables. The entrypoint.sh validates required variables at startup and fails fast if the configuration is invalid.

Core variables

Variable Type Required Default Description
FAIRVISOR_MODE string No decision_service Operating mode. decision_service or reverse_proxy.
FAIRVISOR_CONFIG_FILE string Conditional — Path to local policy bundle JSON. Required when FAIRVISOR_SAAS_URL is not set.
FAIRVISOR_SAAS_URL string Conditional — Base URL for SaaS config delivery (e.g., https://api.fairvisor.com).
FAIRVISOR_EDGE_ID string Conditional — Edge instance identifier. Required when FAIRVISOR_SAAS_URL is set.
FAIRVISOR_EDGE_TOKEN string Conditional — Bearer token for SaaS API authentication. Required when FAIRVISOR_SAAS_URL is set.
FAIRVISOR_BACKEND_URL string Conditional http://127.0.0.1:8081 Upstream backend URL. Required when FAIRVISOR_MODE=reverse_proxy.

Timing variables

Variable Type Default Description
FAIRVISOR_CONFIG_POLL_INTERVAL integer (seconds) 30 How often to poll SaaS for a new config bundle. Must be > 0.
FAIRVISOR_HEARTBEAT_INTERVAL integer (seconds) 5 How often to send a heartbeat to SaaS. Must be > 0.
FAIRVISOR_EVENT_FLUSH_INTERVAL integer (seconds) 60 How often to flush the event buffer to SaaS. Must be > 0.

Runtime tuning

Variable Type Default Description
FAIRVISOR_SHARED_DICT_SIZE string 128m Size of the Lua shared dict that holds all counter state. Accepts nginx size syntax: 128m, 256m, 1g.
FAIRVISOR_LOG_LEVEL string info Nginx error_log level. Valid values: debug, info, notice, warn, error, crit, alert, emerg.
FAIRVISOR_WORKER_PROCESSES string auto Nginx worker_processes directive. Set to a number (e.g., 4) or auto.
FAIRVISOR_DEBUG_SESSION_SECRET string — Enables the per-session debug endpoints (POST /v1/debug/session, POST /v1/debug/logout). When set, requests carrying a valid signed debug cookie receive X-Fairvisor-Debug-* headers.

Validation rules

The startup script (entrypoint.sh) enforces these rules and exits non-zero if violated:

1. FAIRVISOR_MODE must be "decision_service" or "reverse_proxy"
2. If FAIRVISOR_MODE = "reverse_proxy":
     → FAIRVISOR_BACKEND_URL is required
3. If FAIRVISOR_SAAS_URL is set:
     → FAIRVISOR_EDGE_ID is required
     → FAIRVISOR_EDGE_TOKEN is required
4. Else (no SAAS_URL):
     → FAIRVISOR_CONFIG_FILE is required
5. *_INTERVAL values must be positive integers

Mode reference

Standalone

FAIRVISOR_MODE=decision_service
FAIRVISOR_CONFIG_FILE=/etc/fairvisor/policy.json

SaaS

FAIRVISOR_MODE=decision_service
FAIRVISOR_SAAS_URL=https://api.fairvisor.com
FAIRVISOR_EDGE_ID=edge-prod-us-east-1
FAIRVISOR_EDGE_TOKEN=fvt_live_xxxxxxxxxxxxx
FAIRVISOR_HEARTBEAT_INTERVAL=5
FAIRVISOR_CONFIG_POLL_INTERVAL=30
FAIRVISOR_EVENT_FLUSH_INTERVAL=60

Reverse proxy

FAIRVISOR_MODE=reverse_proxy
FAIRVISOR_CONFIG_FILE=/etc/fairvisor/policy.json
FAIRVISOR_BACKEND_URL=http://my-api-service:3000

Sensitive values

FAIRVISOR_EDGE_TOKEN is a bearer secret. Do not log or expose it:

  • In Docker: use a secrets mount or pass it at runtime (-e)
  • In Kubernetes: mount as a Secret volume or use envFrom
  • In CI/CD: store as a masked/protected variable, never in source code

MD