EN

Applications

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.

10 min read, updated on 18 November 2026

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 sudo and belongs to the docker group
  • 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:

Terminal
sudo apt update
sudo apt install -y bind9-dnsutils
dig +short A app.your-domain.com
dig +short AAAA app.your-domain.com

The 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:

Terminal
sudo install -d -o "$USER" -g "$USER" /opt/npm
docker network create proxy

Step 3: Write the Compose File

Terminal
nano /opt/npm/compose.yaml
YAML
services:
  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

Terminal
cd /opt/npm
docker compose config --quiet
docker compose up -d
docker compose ps
docker compose logs -f npm

The 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:

Terminal
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:

Terminal
ssh -N -L 8181:127.0.0.1:81 YOUR_USER@YOUR_SERVER_IP

Then 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:

  1. Open your account menu, at the top right, then Two-Factor Auth. Enable two-factor authentication and keep the backup codes.
  2. 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:

Terminal
sudo install -d -o "$USER" -g "$USER" /opt/whoami
nano /opt/whoami/compose.yaml
YAML
services:
  whoami:
    image: traefik/whoami:v1.12.0
    restart: unless-stopped
    networks:
      - proxy

networks:
  proxy:
    external: true
Terminal
cd /opt/whoami
docker compose up -d

In 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:

  1. In SSL Certificate, choose Request a new Certificate.
  2. Enable Force SSL and HTTP/2 Support.
  3. 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:

Terminal
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 -dates

The 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:

Terminal
curl -m 5 http://YOUR_SERVER_IP:81

Restrict Access to a Service

In Access Lists, click Add Access List:

  1. In Details, give the list a name. Leave Satisfy Any disabled to require all conditions, and Pass Auth to Upstream disabled.
  2. In Authorizations, add a username and a password.
  3. In Rules, add an Allow rule with YOUR_IP. NPM adds a final deny all as 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:

  1. 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.
  2. Create an access list containing only the Allow rule YOUR_IP, with no user: NPM's own interface uses the Authorization header.
  3. Create a Proxy Host npm.your-domain.com using http to 127.0.0.1, port 81, with this access list.
  4. 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:

Terminal
cd /opt/npm
docker compose pull
docker compose up -d
docker compose logs --tail 50 npm

Then 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:

Terminal
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 start

This 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:

Terminal
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 -d

Troubleshooting

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:

Terminal
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:

YAML
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:

Terminal
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 connect or Connection 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 certificates or too 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).

References