Configuration Guide

This guide covers the environment variables and initial setup for Nginx Proxy Guard.

Environment Variables

The only variables you set yourself in the .env file are the ones defined in env.example (below). Other runtime options (GeoIP, ACME, etc.) are managed in the Admin UI.

Required Settings

Variable	Description	Default	Required
`DB_PASSWORD`	Database password	-	O
`JWT_SECRET`	JWT signing secret (32-char hex)	-	O

Optional Settings

Variable	Description	Default
`TZ`	Timezone	`UTC`
`DB_USER`	DB user	`postgres`
`DB_NAME`	DB name	`nginx_proxy_guard`
`DOCKER_API_VERSION`	Docker API version (only when auto-detection fails, e.g. Synology DSM)	auto-detect

env.example also includes commented-out port/network variables such as UI_PORT, NGINX_HTTP_PORT, NGINX_HTTPS_PORT, API_HOST_PORT, and DNS_RESOLVER. Uncomment these only when the default ports (80/443/81) conflict with other services.

GeoIP / MaxMind

GeoIP is not configured through environment variables. Enter your MaxMind Account ID and license key under Settings > GeoIP in the Admin UI. They are stored in the system_settings DB table (maxmind_account_id, maxmind_license_key, geoip_enabled, geoip_auto_update, geoip_update_interval), and the app downloads and auto-updates the GeoIP database on a schedule.

ACME (Let's Encrypt)

ACME email, staging mode, and related options are managed in the Admin UI (Settings > SSL/ACME).

Database Structure

Core Tables

Table	Description
`users`	User authentication (including TOTP 2FA)
`api_tokens`	API authentication tokens
`audit_logs`	Administrator activity audit logs

Proxy Configuration Tables

Table	Description
`proxy_hosts`	Proxy host configuration (includes DDNS columns `ddns_enabled`, `ddns_provider_id` and Docker container columns `forward_container_name`, `forward_container_network`)
`certificates`	SSL/TLS certificates
`dns_providers`	DNS Provider configuration (ACME DNS-01 / DDNS credentials)
`ddns_records`	DDNS managed records (host-linked or manual)
`upstreams`	Load-balancing upstream pools (per proxy host)
`upstream_servers`	Upstream backend servers
`access_lists`	IP access control lists
`redirect_hosts`	URL redirect rules

Security Configuration Tables

Table	Description
`rate_limits`	Rate limiting configuration
`fail2ban_configs`	Fail2ban configuration
`bot_filters`	Bot filtering configuration
`geo_restrictions`	GeoIP regional restrictions
`waf_rule_exclusions`	WAF rule exclusions (per host)
`global_waf_rule_exclusions`	WAF rule exclusions (global)
`banned_ips`	Banned IPs
`ip_ban_history`	IP ban history
`security_headers`	Security header configuration
`uri_blocks`	URI block rules
`global_uri_blocks`	Global URI blocks
`challenge_configs`	CAPTCHA challenge configuration
`challenge_tokens`	Challenge authentication tokens
`cloud_provider_blocks`	Cloud provider blocks
`filter_subscriptions`	External IP/CIDR blocklist subscriptions
`filter_subscription_entries`	IP/CIDR entries synced from subscriptions
`filter_subscription_host_exclusions`	Hosts excluded from a subscription
`filter_subscription_entry_exclusions`	Individual entries excluded from a subscription

Logging Tables

Table	Description
`logs`	Unified logs (monthly partitions)
`system_logs`	System logs (monthly partitions)
`geoip_history`	GeoIP update history

Configuration Tables

Table	Description
`global_settings`	Global Nginx settings
`system_settings`	System settings (includes DDNS refresh interval `ddns_check_interval_minutes`)
`backups`	Backup metadata
`waf_rule_snapshots`	WAF configuration snapshots

Troubleshooting

Certificate Issuance Failure

Check DNS settings (whether the domain points to the server IP)
Verify DNS Provider API token permissions
Check Let's Encrypt rate limits
Test in the staging environment (ACME_STAGING=true) first

# Check certificate logs
docker logs npg-api | grep -i cert

WAF False Positives

Use the WAF test feature to identify which rule is triggered
Add that rule ID to the per-host exclusion list
Switch to detection mode, monitor, then apply blocking mode

GeoIP Not Working

Verify the MaxMind Account ID + license key under Settings > GeoIP
Verify the GeoIP database exists (/etc/nginx/geoip/)
Check the status card under Settings > GeoIP (Country DB / ASN DB)
Run a manual update with the "Update Now" button

Slow Log Queries

Reduce the log retention period (system settings)
Narrow the filter scope
Check partition status

# Check partitions
docker exec -it npg-db psql -U postgres -d nginx_proxy_guard -c "SELECT tablename FROM pg_tables WHERE tablename LIKE 'logs_%';"

Backend Connection Failure

Check backend server status
Check network connectivity
Check firewall settings
Check the Docker network

# Test network connectivity
docker exec -it npg-proxy curl -v http://backend:port

High Memory Usage

Reduce the log retention period
Clean up old partitions
Adjust the number of Nginx worker processes

Security Recommendations

Required Changes

Change the default password: Change it immediately after first login

Generate strong secrets:

# DB password
openssl rand -base64 24

# JWT secret
openssl rand -hex 32

Enable 2FA: Set up TOTP-based two-factor authentication

Network Security

Restrict access to the management port (81)
Allow DB/Redis access only from the internal network
Enforce HTTPS

API Security

Configure IP restrictions for API tokens
Apply the principle of least privilege
Set token expiration dates