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 under /data/npm/ on first start.

#MariaDB Backend

Install and start the HA MariaDB add-on, then create the database and user before enabling this option.

db_type: mariadb
mariadb_host: core-mariadb
mariadb_port: 3306
mariadb_name: npm
mariadb_user: npm

Password goes in secrets.yaml, not the add-on config:

mariadb_password: "dein_passwort"
npm_jwt_secret: "einlangesrandommjwtsecret"

The DB password and JWT secret are no longer add-on config options — they were moved out of options/schema into secrets.yaml for security.

#All Options

Option	Default	Description
db_type	sqlite	sqlite or mariadb. (Replaces the old use_mariadb boolean.)
mariadb_host	empty	MariaDB add-on hostname, e.g. core-mariadb.
mariadb_port	3306	MariaDB port.
mariadb_name	npm	Database name. (Renamed from mariadb_database.)
mariadb_user	npm	MariaDB user. (Renamed from mariadb_username.)
http_port	80	HTTP port.
https_port	443	HTTPS port.
disable_ipv6	false	Disable IPv6.
log_level	info	info / warning / error / debug.

#Secrets (secrets.yaml)

Key	Description
mariadb_password	Password for the MariaDB connection.
npm_jwt_secret	Custom JWT secret (optional).

#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.