Install Nginx Proxy Manager
Install Nginx Proxy Manager with Docker on Debian or Ubuntu, keep its interface off the Internet, publish a service over HTTPS, restrict access, then update and back up.
On this page
Your values
Enter them once and the commands in this guide update.
Nginx Proxy Manager (NPM) is a reverse proxy based on Nginx, controlled from a web interface. It receives visitors on ports 80 and 443, requests Let's Encrypt certificates and forwards requests to your services, without you having to write any Nginx configuration.
By the end of the guide, NPM runs in Docker and its admin interface is reachable only through an SSH tunnel. A test service answers on https://app.your-domain.com, and you know how to restrict access, update NPM and back up its data.
The version used is 2.17.0, the latest stable release at the time of writing, in November 2026.
Order a Server
This guide applies to servers that you administer yourself:
Prerequisites
- A server running Debian 12 or 13, or Ubuntu 22.04 or 24.04, on amd64 or arm64 architecture
- SSH access with a user that has
sudoand belongs to thedockergroup - Docker Engine and Docker Compose, installed with the guide Install Docker Engine and Docker Compose
- A domain name whose DNS zone you manage
- No other software on ports 80 and 443, such as Nginx, Apache, Caddy or Traefik
Ports Used
| Port | Direction | Purpose | To open |
|---|---|---|---|
| 80/tcp | Inbound | Let's Encrypt validation and redirect to HTTPS | Yes |
| 443/tcp | Inbound | Sites published over HTTPS | Yes |
| 81/tcp | Local | Admin interface, on 127.0.0.1 |
No |
Step 1: Point the Domain to the Server
Create an A record for app.your-domain.com pointing to YOUR_SERVER_IP. If your domain is managed at HostMyServers, follow the guide Create an A record.
Then check the result from the server:
sudo apt update
sudo apt install -y bind9-dnsutils
dig +short A app.your-domain.com
dig +short AAAA app.your-domain.comThe first command must return your server's address. If the second returns an IPv6 address, it must also match this server. Otherwise, delete that AAAA record.
Step 2: Prepare the Folder and the Network
Create the project folder, then a Docker network shared between NPM and the services to publish:
sudo install -d -o "$USER" -g "$USER" /opt/npm
docker network create proxyStep 3: Write the Compose File
nano /opt/npm/compose.yamlservices:
npm:
image: jc21/nginx-proxy-manager:2.17.0
container_name: nginx-proxy-manager
restart: unless-stopped
ports:
- "80:80"
- "443:443"
- "127.0.0.1:81:81"
environment:
TZ: "Europe/Paris"
volumes:
- ./data:/data
- ./letsencrypt:/etc/letsencrypt
networks:
- proxy
networks:
proxy:
external: true| Element | Purpose |
|---|---|
127.0.0.1:81:81 |
Makes the interface reachable only from the server |
./data |
SQLite database, application keys, host configuration and logs |
./letsencrypt |
Certificates and private keys |
proxy |
Network through which NPM reaches your services |
Step 4: Start NPM
cd /opt/npm
docker compose config --quiet
docker compose up -d
docker compose ps
docker compose logs -f npmThe first startup initializes the database and generates the keys, which can take a few minutes. Exit the logs with Ctrl+C, then check the ports:
sudo ss -ltnp | grep -E ':(80|81|443) 'Port 81 must appear only on 127.0.0.1.
Step 5: Check the Firewall
Docker publishes ports 80 and 443 with its own rules, applied before those of UFW. These two ports are therefore reachable even without ufw allow, and UFW cannot restrict them. This is why port 81 must be limited in compose.yaml, not in UFW. The guide Configure the UFW Firewall explains how this works.
If you use your instance's built-in firewall, also allow ports 80 and 443 from your client area.
Step 6: Create the Administrator Account
From your computer, open an SSH tunnel and leave this terminal open:
ssh -N -L 8181:127.0.0.1:81 YOUR_USER@YOUR_SERVER_IPThen open http://127.0.0.1:8181 in your browser. The traffic goes through the encrypted tunnel.
NPM displays a Welcome! screen to create the account. Fill in Full Name, Email address and Password (8 characters minimum, but choose a long, unique one), then confirm. This email address is also used to register with Let's Encrypt: enter a valid one.
Menus are quoted here in English, the interface's default language. You can change the language from the interface.
Then harden the installation:
- Open your account menu, at the top right, then Two-Factor Auth. Enable two-factor authentication and keep the backup codes.
- In Settings, open Default Site and choose No Response (444). Requests that match none of your names will no longer receive a landing page.
Step 7: Publish a Service
Create a test service attached to the proxy network. It publishes no port on the server:
sudo install -d -o "$USER" -g "$USER" /opt/whoami
nano /opt/whoami/compose.yamlservices:
whoami:
image: traefik/whoami:v1.12.0
restart: unless-stopped
networks:
- proxy
networks:
proxy:
external: truecd /opt/whoami
docker compose up -dIn NPM, open Hosts, then Proxy Hosts, and click Add Proxy Host. In the Details tab:
| Field | Value |
|---|---|
| Domain Names | app.your-domain.com |
| Scheme | http |
| Forward Hostname / IP | whoami |
| Forward Port | 80 |
| Access List | Publicly Accessible |
| Block Common Exploits | Enabled |
The name whoami is the Compose service name, and 80 is its port inside the container. Enable Websockets Support if your application needs it. Attach only trusted services to the proxy network: they can reach NPM's port 81 inside that network.
In the SSL tab:
- In SSL Certificate, choose Request a new Certificate.
- Enable Force SSL and HTTP/2 Support.
- Leave Use DNS Challenge disabled: validation goes through port 80.
Click Save. Enable HSTS Enabled only once you are sure you will keep this name on HTTPS: browsers remember this choice.
NPM checks certificates every hour and renews those that expire in less than 30 days.
Check the Result
From the server or your computer:
curl -I http://app.your-domain.com
curl -I https://app.your-domain.com
echo | openssl s_client -connect app.your-domain.com:443 -servername app.your-domain.com 2>/dev/null | openssl x509 -noout -issuer -datesThe HTTP request must return a redirect to HTTPS, and the HTTPS request a 200 code. The certificate issuer must be Let's Encrypt.
From your computer, the admin port must not respond:
curl -m 5 http://YOUR_SERVER_IP:81Restrict Access to a Service
In Access Lists, click Add Access List:
- In Details, give the list a name. Leave Satisfy Any disabled to require all conditions, and Pass Auth to Upstream disabled.
- In Authorizations, add a username and a password.
- In Rules, add an Allow rule with
YOUR_IP. NPM adds a finaldeny allas soon as a rule exists.
Save, then select this list in the Proxy Host's Access List field.
Access the Interface Through a Domain Name
The SSH tunnel remains the safest option. If you prefer a domain name, place the interface behind NPM and limit it to your IP address:
- Create an A record for
npm.your-domain.com, with no AAAA record. An IPv6 connection may arrive with the Docker gateway's address and would be refused. - Create an access list containing only the Allow rule
YOUR_IP, with no user: NPM's own interface uses theAuthorizationheader. - Create a Proxy Host
npm.your-domain.comusinghttpto127.0.0.1, port81, with this access list. - In SSL, request a certificate and enable Force SSL.
Keep the 127.0.0.1:81:81 publication: it lets you fall back to the SSH tunnel in case of a mistake. If your IP address changes often, prefer a private network with WireGuard or Tailscale.
Update
First read the release notes. For example, version 2.17.0 updates Certbot and may break some DNS plugins. Then back up NPM, change the image tag in compose.yaml, and run:
cd /opt/npm
docker compose pull
docker compose up -d
docker compose logs --tail 50 npmThen check that you can log in to the interface and that your services are reachable.
Back Up and Restore
Everything is in /opt/npm: the compose.yaml file, data and letsencrypt. Stop NPM while the archive is created to get a consistent SQLite database:
cd /opt/npm
docker compose stop
sudo tar -czf /root/npm-$(date +%F).tar.gz -C /opt npm
sudo chmod 600 /root/npm-$(date +%F).tar.gz
docker compose startThis archive contains private keys: copy it off the server to an encrypted location. If you configured DNS validation, it may also contain your API credentials.
To restore the archive, replacing YYYY-MM-DD with its date, create the network if it does not exist yet on this server:
cd /opt/npm 2>/dev/null && docker compose down
sudo tar -xzf /root/npm-YYYY-MM-DD.tar.gz -C /opt
docker network create proxy
cd /opt/npm
docker compose up -dTroubleshooting
General logs are shown with docker compose logs --tail 100 npm, from /opt/npm. Each Proxy Host's logs are in /opt/npm/data/logs/, as proxy-host-1_access.log and proxy-host-1_error.log. Read them with sudo.
port is already allocated or address already in use
Another service is using port 80 or 443:
sudo ss -ltnp | grep -E ':(80|443) 'Stop that service if it is no longer needed, for example with sudo systemctl disable --now nginx.
Address family not supported by protocol
The server has no IPv6. Add this variable to environment, then restart with docker compose up -d:
DISABLE_IPV6: "true"channel 2: open failed: connect failed: Connection refused
The SSH tunnel works, but nothing is listening on port 81. NPM is still starting or has stopped: check docker compose ps and its logs.
502 Bad Gateway
NPM cannot reach the service. Check that the container is running, that it is attached to the proxy network, then that the Proxy Host's name and port are correct:
docker network inspect proxy --format '{{range .Containers}}{{.Name}} {{end}}'In Forward Hostname / IP, 127.0.0.1 refers to the NPM container itself, not the server. The service must also listen on 0.0.0.0 inside its container.
The Certificate Is Not Issued
Since version 2.17, the interface shows the reason given by Certbot:
NXDOMAIN: the name does not exist in DNS yet.Timeout during connectorConnection refused: port 80 is not reachable from the Internet. Check the A and AAAA records, then your instance's firewall. If everything is correct, contact support from your client area.CAA record: a CAA record forbids Let's Encrypt.too many certificatesortoo many failed authorizations: a Let's Encrypt limit has been reached. Wait until the date given in the message.
403 Forbidden on a Protected Service
Your address is not in the access list. Compare it with the one in the Proxy Host's access log, then fix the rule.
Login to the Application Loops After Adding a Password
This is the Authorization header conflict described above. Remove the users from the access list and keep only the IP address rules.
Redirect Loop
The application forces HTTPS without recognizing the X-Forwarded-Proto header. Enable the "trust proxy" option or its equivalent in the application. If the domain goes through Cloudflare's proxy, set the SSL/TLS mode to Full (strict).