Installation & Getting Started

How to easily and quickly install Nginx Proxy Guard using Docker

Prerequisites

Docker 24.0+ and Docker Compose 2.20+
Minimum 1GB RAM, 10GB disk space
(Optional) Domain name for SSL certificates
(Optional) MaxMind license key for GeoIP

Quick Start

# Create installation directory
mkdir -p ~/nginx-proxy-guard && cd ~/nginx-proxy-guard

# Download required files
wget https://raw.githubusercontent.com/svrforum/nginxproxyguard/main/docker-compose.yml
wget -O .env https://raw.githubusercontent.com/svrforum/nginxproxyguard/main/env.example

# Generate security secrets (Important!)
sed -i "s/DB_PASSWORD=.*/DB_PASSWORD=$(openssl rand -base64 24)/" .env
sed -i "s/JWT_SECRET=.*/JWT_SECRET=$(openssl rand -hex 32)/" .env

# Start services (volumes created automatically)
docker compose up -d

Access UI

Admin Panel: https://localhost:81
Proxy: http://localhost:80 / https://localhost:443

Default Credentials

Important: Change the default credentials immediately after first login.

Username: admin
Password: admin

Configuration

Edit the .env file to configure the system.

Required Settings

# Security secrets (Must change!)
DB_PASSWORD=<strong_password>
JWT_SECRET=<32_char_hex_string>

Optional Settings

# MaxMind GeoIP (For country-based blocking)
MAXMIND_LICENSE_KEY=<license_key>
MAXMIND_ACCOUNT_ID=<account_id>

# Let's Encrypt (For automatic SSL certificate issuance)
ACME_EMAIL=admin@example.com
ACME_STAGING=false

# Timezone
TZ=Asia/Seoul

Docker Services

Service	Description	Port
`nginx`	Reverse Proxy + WAF	80, 443 (TCP/UDP)
`ui`	Admin Web Interface	81
`api`	Go Backend API	8080 (internal)
`db`	PostgreSQL 17	5432 (internal)
`valkey`	Redis-compatible Cache	6379 (internal)

Docker Volumes

Volume	Purpose
`npg_postgres_data`	Database storage
`npg_valkey_data`	Cache data
`npg_nginx_data`	Nginx configs, certs, logs
`npg_api_data`	Backups and API data
`npg_ui_data`	UI SSL certificates

Port Configuration

Default Ports

Port	Protocol	Purpose
80	TCP	HTTP
443	TCP	HTTPS (HTTP/2)
443	UDP	HTTPS (HTTP/3 QUIC)
81	TCP	Admin UI

Changing Ports

Modify port mappings in docker-compose.yml:

services:
  nginx:
    ports:
      - "8080:80"        # Change HTTP port
      - "8443:443/tcp"   # Change HTTPS port
      - "8443:443/udp"   # Change HTTP/3 port
  ui:
    ports:
      - "3000:443"       # Change Admin UI port

Upgrade

# Navigate to installation directory
cd ~/nginx-proxy-guard

# Download latest docker-compose.yml
wget -O docker-compose.yml https://raw.githubusercontent.com/svrforum/nginxproxyguard/main/docker-compose.yml

# Restart services with latest images
docker compose pull && docker compose up -d

Backup & Restore

Backup

Create a backup through Settings > Backup menu in Admin UI, or:

# Manual backup (inside container)
docker exec npg-api /app/backup.sh

Restore

# Restore from backup file
docker exec npg-api /app/restore.sh /path/to/backup.tar.gz

Initial Setup Checklist

Change default password - Immediately after first login
Enable 2FA - Set up TOTP in Settings > Account
Configure HTTPS - Set up certificate for Admin UI
Configure GeoIP - Enter MaxMind license key
Set up DNS Provider - For Let's Encrypt auto-issuance
Set backup schedule - Automate regular backups

Troubleshooting

Container won't start

# Check logs
docker compose logs -f

# Check specific service logs
docker logs npg-api
docker logs npg-proxy
docker logs npg-db

Database connection failed

# Check DB container status
docker ps | grep npg-db

# Test DB connection
docker exec -it npg-db psql -U postgres -d nginx_proxy_guard -c "SELECT 1;"

Nginx configuration error

# Check Nginx config syntax
docker exec npg-proxy nginx -t

# Reload Nginx
docker exec npg-proxy nginx -s reload

Permission issues

# Check volume permissions
docker exec npg-proxy ls -la /etc/nginx/conf.d/
docker exec npg-api ls -la /app/data/