Nginx Proxy Manager is a reverse proxy management UI with SSL automation. This add-on wraps the official jc21/nginx-proxy-manager image with HA Supervisor integration, secrets support and optional MariaDB backend.

#Wiki Pages

Page	Purpose
Installation	Add repository, install, start.
Configuration	SQLite vs MariaDB, secrets, JWT.
First Start	Default login, change credentials.
SSL & Let's Encrypt	DNS-01, DuckDNS, wildcard certs.
Troubleshooting	Port conflicts, cert failures, DB issues.

#Minimum Operating Model

Browser → NPM Admin UI :81
NPM     → manages nginx configs, SSL certs
nginx   → proxies :80/:443 to internal services

#Step 1 — Add Repository

1. Open Home Assistant.
2. Go to Settings → Add-ons → Add-on Store.
3. Open ⋮ → Repositories.
4. Add:

https://github.com/pol4rfuchs/ha-apps

#Step 2 — Install

1. Search for Nginx Proxy Manager.
2. Click Install.

#Step 3 — Start

1. Enable Start on boot.
2. Click Start.
3. Open the Admin UI at port 81.

Ports 80 and 443 must be free on the host. Disable any other service using these before starting.

#SQLite (Default)

No configuration required. NPM creates its own SQLite database on first start.

#MariaDB Backend

use_mariadb: true
mariadb_host: "core-mariadb"
mariadb_port: 3306
mariadb_database: "npm"
mariadb_username: !secret npm_db_user
mariadb_password: !secret npm_db_password
npm_jwt_secret: !secret npm_jwt_secret

Create the MariaDB database and user before enabling this option. Use !secret references to keep credentials out of the add-on config.

#All Options

Option	Default	Description
use_mariadb	false	Use MariaDB instead of SQLite.
mariadb_host	core-mariadb	MariaDB add-on hostname.
mariadb_port	3306	MariaDB port.
mariadb_database	npm	Database name.
mariadb_username	—	MariaDB user.
mariadb_password	—	MariaDB password.
npm_jwt_secret	—	JWT secret for session tokens.

#Default Login

URL:      http://homeassistant.local:81
Email:    admin@example.com
Password: changeme

Change the email and password immediately after first login.

#Create Your First Proxy Host

1. Click Proxy Hosts → Add Proxy Host.
2. Set the domain name (e.g. ha.yourdomain.com).
3. Set the forward hostname to homeassistant.local or HA IP.
4. Set the forward port to 8123.
5. Enable SSL under the SSL tab.

#HTTP-01 Challenge

Requires port 80 to be forwarded to your HA host. Works for standard domain certificates.

#DNS-01 Challenge (Recommended)

Works without port forwarding. Supports wildcard certificates. Available providers in NPM include Cloudflare, DuckDNS, Route53 and more.

1. SSL Certificates → Add SSL Certificate → Let's Encrypt.
2. Enable Use DNS Challenge.
3. Select your DNS provider.
4. Enter your API credentials.

#DuckDNS Setup

Provider:     DuckDNS
Token:        your-duckdns-token
Domain:       your-subdomain.duckdns.org

DuckDNS wildcard certs cover *.your-subdomain.duckdns.org — useful for multiple subdomains on one certificate.

#Auto-Renewal

NPM renews certificates automatically before expiry. No manual action required after initial setup.

Port	Protocol	Purpose	Expose publicly?
80/tcp	HTTP	Proxy + ACME HTTP-01 challenge	Yes (for HTTP)
443/tcp	HTTPS	Proxy (SSL)	Yes (for HTTPS)
81/tcp	HTTP	NPM Admin UI	No — LAN only

Never expose the Admin UI (port 81) to the internet. Keep it behind your LAN or VPN.

/data/
├── database.sqlite    # NPM database (if not using MariaDB)
├── nginx/             # Generated nginx configurations
└── letsencrypt/       # Let's Encrypt certificates and ACME data

Important: The letsencrypt/ folder contains your private keys and certificates. HA backups include it automatically.

#Backup Workflow

1. Settings → System → Backups → Create Backup.
2. This captures NPM config, certificates and (if SQLite) the database.
3. For MariaDB: also back up the MariaDB add-on data.

Symptom	Cause	Fix
Port 81 not accessible	Port not mapped in Network tab.	Add port mapping in add-on Network settings.
Port 80/443 conflict	Another service uses these ports.	Stop conflicting service or change its port.
Let's Encrypt fails	Port 80 not forwarded (HTTP-01).	Use DNS-01 challenge or forward port 80 on router.
MariaDB connection refused	Wrong credentials or MariaDB not running.	Verify MariaDB add-on is running and credentials match.
White screen on UI	Browser cache issue.	Clear cache and try direct URL: http://HA-IP:81
Proxy host returns 502	Upstream service not running or wrong port.	Verify the forwarded service is running and the port is correct.

Unofficial, community-maintained wrapper for jc21/nginx-proxy-manager. NPM is MIT licensed. Add-on wrapper is MIT licensed.