Environment variables
This page describes the dashboard variables, then the essential variables of the other components. It follows the System page of the dashboard, reserved to administrators, which shows for each setting its current value, its default value and where to change it.
General rules
- Variables go in the
.env file next to the compose file. No quotes around values.
- For a given setting, the priority is: environment variable, then the YAML file in
config/ when it exists, then the default value. A value defined in .env therefore always wins.
- No secret is required to start. When they are missing, the dashboard generates the following secrets once and keeps them in
config/.generated-secrets.json: SESSION_SECRET, WAF_TOKEN, SHIPPER_LOCAL_TOKEN, NC_SECRET and INSTANCE_ID.
- Secrets are shown in the System page as "configured" or "not configured", never in clear text.
- A variable marked build is set when the image is built (
build.args in the compose) and can also be overridden at runtime.
- To generate a secret:
openssl rand -hex 32.
Dashboard
General
| Variable |
Default |
Role |
PORT |
3000 |
Internal listening port. The published port is set in ports: of the compose |
NGINX_CONTAINER |
nginx |
Name of the Nginx container to control (test, reload, statistics) |
NGINX_IMAGE |
detected |
Image of the ephemeral container that tests a configuration before deployment |
NGINX_NETWORK |
nginx-net |
Shared Docker network, used for the test container and DNS resolution |
NGINX_VTS_URL |
http://nginx:8080/status.json |
Endpoint of the VTS module that provides per-vhost statistics |
NGINX_CONF_FILE |
/etc/nginx/nginx.conf |
Path of nginx.conf in the Nginx container |
NOTIF_POLL_INTERVAL_SEC |
5 |
How often the browser polls notifications (minimum 2) |
INSTANCE_ID |
generated |
Unique identifier of the installation (UUID), not a secret |
HTTP_USER_AGENT |
NGXOps |
User-Agent of all outgoing requests, without a version number so it can be filtered |
DOCKER_SOCKET |
/var/run/docker.sock |
Docker socket used to control Nginx and managed containers |
Security and sessions
| Variable |
Default |
Role |
SESSION_SECRET |
generated |
Session signing key |
SESSION_TTL_HOURS |
8 |
Session duration, renewed while the user is active |
SESSION_MAX_HOURS |
24 |
Maximum session duration, even when active |
LOGIN_MAX_ATTEMPTS |
10 |
Failed logins tolerated before a temporary lockout |
LOGIN_WINDOW_MIN |
15 |
Window for counting failures, in minutes |
LOGIN_LOCKOUT_MIN |
15 |
Lockout duration, in minutes |
API_TOKEN |
disabled |
REST API token (Authorization: Bearer). It stays inactive if empty, if it starts with changeme or if it is shorter than 16 characters |
WEBHOOK_SECRET |
not configured |
Signing secret for outgoing webhooks |
CORS_ORIGIN |
empty |
Origin allowed cross-origin. Empty: same origin only, which is recommended |
TRUSTED_PROXIES |
private networks and loopback |
Addresses allowed to set X-Forwarded-For |
HEALTH_PUBLIC |
true |
Public /health route. false disables it |
MFA_RP_ID |
derived from Host |
WebAuthn domain for security keys. Set it behind a proxy that rewrites Host |
MFA_ORIGIN |
derived |
HTTPS origins allowed for WebAuthn, comma-separated |
The API and webhooks can also be set from the System page: the Generate button shows the value once and only keeps its fingerprint.
Deployment and backups
| Variable |
Default |
Role |
ALLOW_EDIT |
false |
Allows editing configuration files from the interface |
ALLOW_CREATE |
false |
Allows creating files. No effect when Git is configured |
DEPLOY_SYNC_SSL |
true |
Includes ssl/ in the Git deployment. certs/ is never synchronized |
GIT_REPO_URL |
empty |
Reference repository. Empty: Git deployment disabled |
GIT_BRANCH |
main |
Source branch |
GIT_BACKUP_BRANCH |
backup |
Branch that receives the previous state before each deployment |
GIT_TOKEN |
empty |
HTTPS token of the repository |
GIT_SSH_KEY |
empty |
Path of the SSH key in the container, to mount as a volume |
GIT_USER_NAME, GIT_USER_EMAIL |
Nginx Dashboard, dashboard@localhost |
Commit identity |
BACKUP_KEEP |
20 |
Number of local ZIP backups kept |
BACKUP_PASSPHRASE |
empty |
Common fallback passphrase for encrypted archives |
HUB_BACKUP_PASSPHRASE |
empty |
Passphrase of the backups sent to the Hub |
S3_BACKUP_PASSPHRASE |
empty |
Passphrase of the archive sent to S3 |
A lost passphrase makes the encrypted archive unrecoverable: keep them outside the dashboard.
Directories
The DIR_* variables tell where volumes are mounted inside the dashboard container. They must match the volumes of the compose.
| Variable |
Default |
DIR_SITES |
/nginx/sites |
DIR_CONF |
/nginx/conf |
DIR_SNIPPETS |
/nginx/snippets |
DIR_STREAMS |
/nginx/streams |
DIR_SSL |
/nginx/ssl |
DIR_CERTS |
/nginx/certs |
DIR_LOGS |
/nginx/logs |
DIR_CACHE |
empty, which disables the cache purge button |
DIR_BACKUPS |
/nginx/backups |
DIR_GIT_WORK |
/git-work |
DIR_GOACCESS |
/nginx/goaccess |
DIR_GEOIP |
/geoip |
HOST_LOGS and HOST_GOACCESS are different: they are absolute paths on the host, used for the volumes of the containers the dashboard creates. Docker resolves these paths on the host side; a path that only exists inside the dashboard container would mount an empty folder.
Integrations
| Variable |
Default |
Role |
CROWDSEC_PROMETHEUS_URL |
empty |
Prometheus endpoint of the CrowdSec engine (recommended) |
CROWDSEC_LOCAL_ONLY |
false |
Shows local decisions only |
CROWDSEC_URL, CROWDSEC_API_KEY |
empty |
CrowdSec local API and bouncer key, read-only |
CROWDSEC_MACHINE_ID, CROWDSEC_MACHINE_PASSWORD |
empty |
Machine identity, required to ban, unban and manage allowlists |
GOACCESS_IMAGE |
allinurl/goaccess:latest |
GoAccess image |
GOACCESS_LOG_FORMAT |
COMBINED |
Log format read by GoAccess |
GOACCESS_REFRESH |
30 |
Report regeneration, in seconds |
GEOIP_CITY_DB, GEOIP_COUNTRY_DB, GEOIP_ASN_DB |
/geoip/GeoLite2-*.mmdb |
Paths of the MaxMind databases |
GODNS_IP_CHECK |
true |
Checks the public IP reported by GoDNS against several services |
GODNS_IP_CHECK_URLS |
ipify, icanhazip, ifconfig.me |
Services queried for this check |
REDIS_URL |
empty |
Address of the optional Redis, for example redis://redis:6379/0 |
REDIS_PASSWORD |
empty |
Redis password, required when Redis is used |
REDIS_PREFIX |
INSTANCE_ID or ngx |
Prefix of Redis keys |
Analysis, WAF, challenge and centralized logs
| Variable |
Default |
Role |
ANALYZER_DEFAULT_IMAGE |
suite analyzer image (build) |
Default image of the analysis container |
WAF_DEFAULT_IMAGE |
ANALYZER_DEFAULT_IMAGE (build) |
Emulated WAF image |
WAF_TOKEN |
generated |
Secret shared with the emulated WAF |
CHALLENGE_DEFAULT_IMAGE |
suite challenge image (build) |
Browser challenge image |
ANUBIS_DEFAULT_IMAGE |
ghcr.io/techarohq/anubis:latest (build) |
Anubis engine image |
AGENT_DEFAULT_IMAGE |
suite agent image (build) |
Image offered in the agent deployment kit |
NC_SECRET |
generated |
Signing secret for challenge cookies |
NC_DIFFICULTY_BITS |
16 |
Proof-of-work difficulty (8 to 64) |
NC_COOKIE_HOURS |
24 |
Validity of the "verified browser" cookie, from 1 to 720 hours |
NC_GOODBOTS |
true |
Lets through crawlers whose reverse DNS is confirmed |
NC_GOODBOTS_EXTRA |
empty |
Extra crawlers: name, User-Agent regular expression and DNS suffix, separated by a vertical bar (detailed format in sample.env) |
NC_LANG |
auto |
Language of the verification page: auto, fr or en |
SHIPPER_DEFAULT_IMAGE |
ANALYZER_DEFAULT_IMAGE |
Shipper image |
SHIPPER_LOCAL_TOKEN |
generated |
Local token shared between dashboard, shipper and WAF (24 characters minimum) |
LOGSINK_TOKEN |
empty |
write token of this instance, used by the shipper |
LOGSTORE_READ_TOKEN |
empty |
read token of the log store, used by the Logs page |
INTEL_API_URL |
empty (build) |
Address of the Intelligence platform |
INTEL_TOKEN |
empty |
Token for Intelligence identified mode |
The settings of these features (activation, limits, paths) are in the config/ files: analyzer.yml, waf.yml, challenge.yml, logstore.yml, intelligence.yml. They can be changed from the matching dashboard pages.
Retention and maintenance
| Variable |
Default |
Role |
EVENTS_RETENTION_DAYS |
30 |
Retention of the event log |
MONITOR_RETENTION_DAYS |
30 |
Retention of the monitoring history. An open incident is never purged |
NOTIF_CENTER_RETENTION_DAYS |
90 |
Retention of notifications |
DB_COMPACT_ON_START |
auto |
SQLite compaction at startup: auto, always or off |
DB_COMPACT_MIN_FREE_MB |
16 |
Minimum free space that triggers compaction in auto mode |
DB_COMPACT_MIN_FREE_PCT |
20 |
Minimum share of free pages that triggers compaction in auto mode |
Interface and menu
| Variable |
Default |
Role |
BRANDING_HEADER_TEXT |
empty |
Text shown in the header (customer name, environment) |
BRANDING_DOC, BRANDING_DOC_LABEL |
empty, Documentation |
Link to the documentation, at the bottom of the menu (build) |
BRANDING_SITE, BRANDING_SITE_LABEL |
empty |
Link to a site (build) |
BRANDING_REPO, BRANDING_REPO_LABEL |
empty, Source repository |
Link to the repository (build) |
BRANDING_KOFI, BRANDING_KOFI_LABEL |
empty, Support on Ko-fi |
Support link. Empty: hidden (build) |
MENU_WAF, MENU_GODNS, MENU_API, MENU_WEBHOOKS, MENU_DOCKER_AUTOCONFIG, MENU_AGENTS, MENU_GOACCESS |
auto |
Visibility of optional menus: auto, show or hide (GoDNS has no auto mode: show by default). Can also be set in menu.yml |
Updates and synchronization
| Variable |
Default |
Role |
SYNC_REF_URL |
empty |
Reference repository for snippet and configuration synchronization |
SYNC_REF_PATH_PREFIX |
empty |
Subfolder of the reference repository, if conf, sites, snippets and streams are not at its root |
DASHBOARD_VERSION_URL, NGINX_VERSION_URL |
empty |
Addresses queried to detect a new version. Empty: check disabled |
CHANGELOG_URL |
empty |
Address of the changelog shown by the Changelog button |
ALERTING_URL, ALERTING_POLL_INTERVAL_MIN |
empty, 60 |
Important messages delivered through a Markdown address, with a minimum interval of 5 minutes |
Nginx
Variables read by the compose, in .env:
| Variable |
Default |
Role |
NGINX_TAG |
see sample.env |
Nginx image tag |
NGINX_RESTART_POLICY |
always |
Restart policy |
NGINX_WORKER_PROCESSES |
auto |
Number of worker processes |
NGINX_WORKER_CONNECTIONS |
768 |
Connections per process |
Hub
.env file of nginx-hub/. The rest of the configuration is in config/hub.yml.
| Variable |
Role |
HUB_SECRET_KEY |
Master key that encrypts instance tokens. Generate it with docker compose run --rm hub node bin/hub-admin.js generate-key. Back it up with the data |
HUB_PORT |
Listening port, 8090 by default |
HUB_BOOTSTRAP_ADMIN_PASSWORD |
Initial password forced on the admin account (12 characters minimum, change required at first login). Without it, a random password is shown once in the logs |
HUB_LOG_LEVEL |
Logging level, info by default |
HUB_LOGSTORE_TOKEN, HUB_LOGSTORE_URL |
Global read token and address of the log store, for the Logs view |
HUB_DB_DRIVER, HUB_DB_HOST |
Use PostgreSQL instead of SQLite |
In production, prefer a Docker secret (HUB_SECRET_KEY_FILE, HUB_LOGSTORE_TOKEN_FILE) to a plain variable.
Log store
| Variable |
Default |
Role |
LOGSTORE_DB_PASSWORD |
to define |
PostgreSQL password |
LOGSTORE_ADMIN_TOKEN |
to define |
Administration token (32 characters minimum) used to create write and read tokens |
LOGSTORE_IP_MODE |
clear |
Initial IP address mode: clear, pseudonymized or truncated |
LOGSTORE_PSEUDO_KEY |
empty |
Pseudonymization key, required in pseudonymized mode (32 characters minimum) |
LOGSTORE_RETENTION_DAYS |
30 |
Initial retention of raw logs, from 7 to 30 days |
LOGSTORE_TLS_CERT, LOGSTORE_TLS_KEY |
empty |
TLS certificate mounted in the container |
LOGSTORE_INSECURE_HTTP |
true in the example |
Plain HTTP, reserved to the internal network or behind a trusted TLS proxy |
LOGSTORE_LISTEN |
:8443 |
Listening address |
LOGSTORE_REQUIRE_TIMESCALE |
see sample.env |
Refuses to start without TimescaleDB |
LOGSTORE_RATE_READ, LOGSTORE_RATE_WRITE |
20, 10 |
Requests per second per token |
LOGSTORE_MAX_BODY_BYTES, LOGSTORE_MAX_BATCH_EVENTS |
4194304, 5000 |
Batch limits |
LOGSTORE_QUERY_TIMEOUT_SECONDS |
15 |
Maximum duration of a query |
LOGSTORE_MAINTENANCE, LOGSTORE_MAINTENANCE_HOURS |
true, 24 |
Scheduled database maintenance and its interval |
LOGSTORE_UI |
true |
/ui/ web interface for token management |
Agent
.env file of the nginx-agent/ folder, on the remote server. The dashboard can generate this file and the compose file from the remote hosts page.
| Variable |
Default |
Role |
DASHBOARD_URL |
to define |
Dashboard address, reachable from the remote server |
AGENT_HOSTNAME |
container name |
Name proposed at enrollment |
AGENT_FINGERPRINT |
empty |
Free fingerprint shown to the operator at approval time |
POLL_INTERVAL |
30s |
Interval between two manifest pushes |
TUNNEL_ENABLE |
true |
Opens the tunnel connection when a vhost is in tunnel mode |
RELAY_HTTP_LISTEN, RELAY_HTTPS_LISTEN |
empty |
Listening ports of relay mode. Empty: relay disabled |
RELAY_HTTP_ADVERTISE, RELAY_HTTPS_ADVERTISE |
empty |
Full address (http://ip:port) Nginx will use to reach the relay |
RELAY_HTTPS_CERT, RELAY_HTTPS_KEY |
empty |
Certificate of the HTTPS relay. Empty: self-signed certificate generated in memory |
RELAY_BACKEND_INSECURE_SKIP_VERIFY |
false |
Accepts an HTTPS backend with a self-signed certificate |
TARGETS_FILE |
empty |
JSON file describing several target dashboards |
INSECURE_SKIP_VERIFY |
false |
Disables TLS verification of the dashboard. Never enable in production |
The details of direct, tunnel and relay modes are in Remote agents: modes and options.