I ran Nginx Proxy Manager (jc21/nginx-proxy-manager:2.11.3, OpenResty 1.25.3.2) with Docker Compose on my Windows 11 PC (Docker Desktop, Docker Engine 27.5.1), placed a lightweight traefik/whoami backend behind it on a shared bridge network, and then broke the stack systematically. Below is the exact Compose configuration I used, how first-run administrator creation works across current and legacy releases, all four ways I reproduced a 502 Bad Gateway with the verbatim /data/logs/proxy-host-1_error.log line for each, why the green Online status indicator stays lit during an outage, and both ways port 81 stops answering.
Direct Answer: Fix Nginx Proxy Manager port 81 login failures and 502 Bad Gateway errors in Docker Compose by waiting for SQLite or MariaDB schema migrations to open port 3000, attaching backend containers to the shared npm_default custom bridge, and forwarding to container service names and internal ports.
Nginx Proxy Manager Port 81 Boot Race & Custom Bridge (npm_default) Matrix
| NPM Failure Plane | Port 81 / Proxy Symptom | NPM-Specific Root Cause (SQLite / MariaDB / Bridge) | Verified Docker Compose Fix |
|---|---|---|---|
| Port 81 Boot Race (SQLite vs MariaDB) | Port 81 refuses login or returns Bad Gateway for 5 to 25s | Node.js API (port 3000) waits on Knex schema init in /data/database.sqlite or jc21/mariadb-aria InnoDB startup | Wait for Listening on port 3000 ... in docker logs; add MariaDB service_healthy check |
Port 81 First Login (v2.13+ vs v2.11.3) | admin@example.com / changeme rejected on fresh stack | NPM 2.13.0+ removed seeded credentials and serves setup wizard when /api/ reports "setup":false | Create owner account in port 81 Welcome wizard (or inspect INITIAL_ADMIN_* env vars) |
Split Compose Stack (npm_default) | 502 Bad Gateway after 4.02 s while NPM dot stays green Online | App started in a separate docker-compose.yml sits outside NPM's custom bridge; OpenResty DNS 127.0.0.11 returns Server failure | Attach both stacks to an external bridge (npm_default or gfl-npm-net) and forward by service name |
| NPM Forward Host / Port Trap | 502 Bad Gateway in 0.02 s (errno 111: Connection refused) | Proxy Host dialog set to 127.0.0.1 or published host port (e.g. 8080) instead of container port (80) | Set Forward Hostname/IP to Compose service name and Forward Port to internal container port; check /data/logs/proxy-host-1_error.log |
Need custom proxy_read_timeout or client_max_body_size directives for Nginx Proxy Manager's Advanced tab, or converting docker run backends onto npm_default? Use our Nginx 502/504 Timeout Config Generator and Docker Run to Compose Converter.
TL;DR & 502 Bad Gateway Diagnostic Router
- First login & setup wizard: On current releases (
2.13.0+), there is no defaultadmin@example.com/changemelogin; visiting port81opens the "Welcome! Get started by creating your admin account" setup wizard when/api/reports"setup":false. On2.11.3/2.12.ximages that still seed those defaults, rotate both the email and password immediately via the user menu. - Four reproduced
502 Bad Gatewaycauses: A stopped backend container and a backend on a different Docker network both failed after~4.02 sand loggedcould not be resolved (2: Server failure). A wrong forward port (8080instead of80) and using127.0.0.1as the forward host both failed in0.02 sand loggedconnect() failed (111: Connection refused). - The status dot trap: The Proxy Hosts table continues to display a green Online badge (
nginx_online: true) while client requests receive502 Bad Gateway. Always check/data/logs/proxy-host-<ID>_error.loginstead of the UI dot. - Port 81 failures: Omitting
81:81fromports:caused host requests to fail withcurl: (7) Failed to connect to 127.0.0.1 port 81 after 2040 mseven though port81answered200inside the container. When another container already held127.0.0.1:81, Compose aborted withBind for 127.0.0.1:81 failed: port is already allocated. - Mandatory volumes: Keep both
/dataand/etc/letsencryptmounted. Omitting/etc/letsencryptstops container initialization immediately withERROR: /etc/letsencrypt is not mounted! Check your docker configuration.(exit code1).
| Symptom / HTTP Result | Measured Latency | Exact Log / CLI Signature | Root Cause | Verified Fix |
|---|---|---|---|---|
502 Bad Gateway | 4.03 s | whoami could not be resolved (2: Server failure) | Backend container is stopped (Exited) | docker start gfl-npm-whoami (200 OK in 0.02 s) |
502 Bad Gateway | 0.02 s | connect() failed (111: Connection refused) ... upstream: "http://172.18.0.2:8080/" | Wrong Forward Port (8080 vs container port 80) | Set Forward Port to internal container port 80 |
502 Bad Gateway | 4.02 s | gfl-npm-whoami2 could not be resolved (2: Server failure) | Backend is on an isolated Docker network | docker network connect gfl-npm-other gfl-npm-app or shared external network |
502 Bad Gateway | 0.02 s | connect() failed (111: Connection refused) ... upstream: "http://127.0.0.1:8081/" | Forward Host set to 127.0.0.1 (loops back inside NPM) | Use Compose service name whoami:80 or host.docker.internal:8081 |
curl: (7) on :81 | 2.04 s | Failed to connect to 127.0.0.1 port 81 after 2040 ms | 81:81 mapping missing under ports: | Restore '127.0.0.1:81:81' and run docker compose up -d |
Compose fails (exit 1) | Immediate | Bind for 127.0.0.1:81 failed: port is already allocated | Another container/process holds 127.0.0.1:81 | Remap host side to '127.0.0.1:8181:81' or stop the conflicting container |
What I Ran (Lab Environment Baseline)
| Stack Layer | Tested Lab Configuration |
|---|---|
| Nginx Proxy Manager | jc21/nginx-proxy-manager:2.11.3 (OpenResty 1.25.3.2, Node.js internal API on port 3000, SQLite /data/database.sqlite) |
| Docker Runtime | Docker Desktop on Windows 11, Docker Engine 27.5.1, user-defined bridge network gfl-npm-net (172.18.0.0/16) |
| Upstream Backend | traefik/whoami:latest (gfl-npm-whoami), a tiny Go HTTP server that echoes received request headers and container IP |
| Port Bindings | All host ports bound strictly to loopback (127.0.0.1:80:80, 127.0.0.1:81:81, 127.0.0.1:443:443). No public domain or router port forwarding |
| Automation & Verification | Headless Playwright browser session on port 81 paired with direct REST calls to http://127.0.0.1:81/api/ and curl probes |
From a cold start with the image already pulled (docker compose pull took 28.4 s; the uncompressed image is 1.91 GB on disk), docker compose up -d returned after 0.7 s. Port 81 answered HTTP 200 after 1.7 s, and GET /api/ responded at 2.8 s with {"status":"OK","setup":false,"version":{"major":2,"minor":11,"revision":3}}. Adding the opt-in /usr/bin/check-health probe moved the container state from starting at +5 s to healthy at +10 s:

Looking closely at the four diagnostic blocks in the first-start log above highlights three operational behaviors that catch administrators off guard during initial deployment. First, about five seconds after boot, steady-state memory usage settled at 113.8 MiB for gfl-npm-app and 3.14 MiB for gfl-npm-whoami, while Docker Compose created only the two named volumes (gfl-npm-data mounted at /data and gfl-npm-letsencrypt mounted at /etc/letsencrypt). Inside /data, the initialization scripts populated database.sqlite, keys.json, logs/, and nginx/, whereas /etc/letsencrypt remained empty because no Let's Encrypt certificate was requested.

/usr/bin/check-health (healthy at +10 s) prevents premature port 81 login errors, while attaching backend apps to the shared Docker Compose bridge eliminates 127.0.0.1 loopback 502 Bad Gateway traps.Second, the third block in that capture comes from a separate test container launched with only a /data volume and no /etc/letsencrypt mount. Instead of creating an ephemeral directory inside the container root filesystem, the s6-rc prepare service explicitly checks whether /etc/letsencrypt is a mountpoint and aborts immediately with ERROR: /etc/letsencrypt is not mounted! Check your docker configuration. and s6-rc: warning: unable to start service prepare: command exited 1. Even in a local HTTP-only lab, you must mount both volumes.
First Login on Port 81: Setup Wizard vs Legacy Default Credentials
Many older tutorials still instruct you to sign in on port 81 using admin@example.com and changeme. That was governed by backend/setup.js in versions up through 2.12.x when no environment variables were supplied. Starting in 2.13.0, the release notes replaced that seed step with an interactive first-run Setup Wizard whenever GET /api/ returns "setup":false:

http://127.0.0.1:81: creating the administrator account via the setup wizard or replacing the initial bootstrap credentials immediately invalidates default login vectors.When I opened http://127.0.0.1:81 in a fresh browser session against an uninitialized database, Nginx Proxy Manager rendered the Welcome! Get started by creating your admin account setup card rather than a login prompt. The wizard requires three fields, Full Name, Email address, and New Password (minimum 8 characters), and submitting the form sends a POST /api/users bootstrap request that creates administrator user ID 1, flips setup to true, and signs you straight into the dashboard.
To verify how Nginx Proxy Manager wires the Admin WebUI, the internal Node.js API, and the SQLite credential store together inside the container, I inspected the live process tree, listening TCP sockets (ss -tulpn), host port mappings (docker port gfl-npm-app), and the user and auth tables inside /data/database.sqlite right after account creation:

The socket and database inspection inside gfl-npm-app explains how port 81 actually works under the hood. A single nginx: master process (OpenResty 1.25.3.2, PID 246) listens on 0.0.0.0:80, 0.0.0.0:81, and 0.0.0.0:443 inside the container network namespace, while the backend Node.js application (node --abort_on_uncaught_exception --max_old_space_size=250 index.js, PID 261) listens exclusively on container loopback 127.0.0.1:3000. When your browser requests http://127.0.0.1:81/, OpenResty serves the static frontend bundle and proxies every /api/* call to http://127.0.0.1:3000.
Meanwhile, querying /data/database.sqlite (92.0 KB alongside the 2.2 KB RSA keypair file /data/keys.json) confirms that Nginx Proxy Manager stores the account record in the user table (id=1, email='admin@example.test', roles='["admin"]') and stores the password separately in the auth table with type='password' and a cost-13 bcrypt hash ($2b$13$WKga5gYCTg67KuBlshbOPO...). If you are running a 2.11.3 or 2.12.x container where the legacy admin@example.com / changeme account was seeded automatically, open the top-right user menu immediately, click Edit Profile to replace the default email, and click Change Password to rotate the secret:

Submitting the Change Password dialog sends PUT /api/users/1/auth with your current and new passwords, re-computing the $2b$13$ bcrypt hash in /data/database.sqlite. I verified the rotation immediately against POST /api/tokens: attempting to authenticate with the old password returned HTTP 400 Bad Request ({"error":{"message":"Invalid email or password"}}), whereas authenticating with the new password returned HTTP 200 OK and a fresh RS256 bearer token. If you ever get locked out of an existing instance because the password in auth.secret is lost, see our companion guide on resetting the Nginx Proxy Manager password in SQLite.
Setup: The Production-Hardened Docker Compose File
My lab stack starts from the official minimal configuration in the Nginx Proxy Manager Quick Setup guide, with five deliberate engineering improvements: every published port is bound explicitly to 127.0.0.1 so Docker does not expose port 81 on all interfaces; named volumes (gfl-npm-data and gfl-npm-letsencrypt) replace relative bind mounts; the project, containers, and bridge network use deterministic gfl- names; the opt-in /usr/bin/check-health healthcheck is included directly; and the whoami backend sits on the shared gfl-npm-net bridge without publishing any host ports of its own:
# File: docker-compose.yml
# Hardened Nginx Proxy Manager 2.11.3 + traefik/whoami lab stack on shared gfl-npm-net bridge
name: gfl-npm
services:
app:
image: 'jc21/nginx-proxy-manager:2.11.3'
container_name: gfl-npm-app
restart: unless-stopped
ports:
- '127.0.0.1:80:80' # Public HTTP (bound to loopback for local test)
- '127.0.0.1:81:81' # Admin WebUI (keep on 127.0.0.1; tunnel via SSH on VPS)
- '127.0.0.1:443:443' # Public HTTPS
volumes:
- gfl-npm-data:/data
- gfl-npm-letsencrypt:/etc/letsencrypt
healthcheck:
test: ["CMD", "/usr/bin/check-health"]
interval: 10s
timeout: 3s
networks:
- gfl-npm-net
whoami:
image: 'traefik/whoami:latest'
container_name: gfl-npm-whoami
networks:
- gfl-npm-net
networks:
gfl-npm-net:
name: gfl-npm-net
volumes:
gfl-npm-data:
name: gfl-npm-data
gfl-npm-letsencrypt:
name: gfl-npm-letsencrypt

If you prefer to keep the base docker-compose.yml minimal and layer the healthcheck only in environments that monitor container health status, you can split the healthcheck: block into a separate override file (docker-compose.healthcheck.yml) as documented in the NPM Advanced Configuration docs:
# File: docker-compose.healthcheck.yml
services:
app:
healthcheck:
test: ["CMD", "/usr/bin/check-health"]
interval: 10s
timeout: 3s
Before creating our first proxy host, it is worth contrasting this hardened stack against two common shortcuts people try in docker-compose.yml: dropping the /etc/letsencrypt volume when testing plain HTTP locally, and setting INITIAL_ADMIN_EMAIL plus INITIAL_ADMIN_PASSWORD in environment variables to skip the first-run login step. I tested both in isolated throwaway containers:

As the side-by-side comparison demonstrates, both shortcuts introduce immediate problems. Omitting /etc/letsencrypt causes s6-rc to halt container initialization before OpenResty or Node.js can even start (ERROR: /etc/letsencrypt is not mounted! Check your docker configuration.). Worse, when you pass INITIAL_ADMIN_EMAIL and INITIAL_ADMIN_PASSWORD via environment variables (documented under Auto Initial User Creation), the setup script echoes the raw password in plain text twice: once to container stdout (visible to anyone who can run docker logs) and once to disk inside /data/logs/ on the line Creating a new user: <email> with password: <plaintext>. Creating or rotating the account through the WebUI over 127.0.0.1:81 leaves zero plaintext passwords in your logs.
Creating a First Proxy Host & Verifying HTTP 200 Routing
With both gfl-npm-app and gfl-npm-whoami running on gfl-npm-net, I created Proxy Host #1 to route requests for whoami.localhost to the whoami container on port 80 and tested it from the host terminal with curl (for a side-by-side footprint comparison against Traefik and Caddy on the same backend, see our Traefik vs Caddy vs Nginx Proxy Manager Docker RAM benchmark; on managed WordPress stacks where Varnish sits ahead of Apache, compare our Cloudways 502 vs Varnish 503 diagnostic; and when reaching a native Windows listener from Docker Desktop, see fixing Docker ECONNREFUSED 127.0.0.1 on Windows 11):

http://whoami:80 on gfl-npm-net and returns HTTP 200 OK in 30 ms.Sending curl -i -H "Host: whoami.localhost" http://127.0.0.1/ returned HTTP/1.1 200 OK in 0.030 s (30 ms) with response headers Server: openresty and X-Served-By: whoami.localhost. The upstream traefik/whoami payload confirmed that container 6963d4bca755 received the request on its internal gfl-npm-net bridge IP 172.18.0.2 from NPM's bridge IP 172.18.0.3:48356, while OpenResty populated X-Forwarded-For: 172.18.0.1, X-Forwarded-Proto: http, X-Forwarded-Scheme: http, and X-Real-Ip: 172.18.0.1. At the same instant, /data/logs/proxy-host-1_access.log recorded [200 200] - GET http whoami.localhost "/" [Client 172.18.0.1] [Length 290] [Gzip -] [Sent-to whoami].
In the Admin UI under Hosts → Proxy Hosts → Add Proxy Host, achieving that clean route requires filling in exactly four fields on the Details tab while leaving the SSL tab set to None for local loopback testing:

Here is why each of those four fields in the Add Proxy Host modal matters when proxying to another Docker container:
- Step 1: Domain Names (
whoami.localhost): Sets theserver_namedirective inside OpenResty. Any HTTP request arriving on port80whoseHost:header matcheswhoami.localhostis routed to this virtual host. - Step 2: Scheme (
http): Specifies the protocol OpenResty uses between NPM and the backend container over the internal Docker bridge, not the external client protocol. Becausetraefik/whoamilistens for plain HTTP internally, this must behttpeven if you later enable HTTPS on the public side. - Step 3: Forward Hostname / IP (
whoami): Must be the Docker Compose service name (whoami) or container name (gfl-npm-whoami) on the sharedgfl-npm-netbridge, never127.0.0.1orlocalhost. - Step 4: Forward Port (
80): Must be the port the process listens on inside the backend container (80), not a host-mapped port.
To see how Nginx Proxy Manager translates that modal into actual Nginx directives, and why saving a proxy host succeeds even when the upstream host is offline, I inspected the generated virtual host file /data/nginx/proxy_host/1.conf and the included resolver configuration inside gfl-npm-app:

Inspecting /data/nginx/proxy_host/1.conf reveals three architectural details that explain every 502 Bad Gateway behavior we are about to see. First, instead of emitting a static upstream block, NPM writes three Nginx variables at the top of the server block: set $forward_scheme http;, set $server "whoami";, and set $port 80;, which are then passed to proxy_pass $forward_scheme://$server:$port$request_uri; inside /etc/nginx/conf.d/include/proxy.conf. Because $server is a runtime variable rather than a static hostname literal, OpenResty does not resolve whoami during nginx -t or config reload; instead, it queries Docker's embedded DNS server (resolver 127.0.0.11 valid=10s; in /etc/nginx/conf.d/include/resolvers.conf) when an HTTP request actually arrives.
Second, notice line 14 of 1.conf: error_log /data/logs/proxy-host-1_error.log warn;. Nginx Proxy Manager isolates upstream errors into a per-host log file named after the proxy host's numeric database ID. If you only check docker logs gfl-npm-app during a 502 Bad Gateway outage, you will miss the root cause completely. Always tail the specific proxy host error log:
docker exec gfl-npm-app tail -n 20 /data/logs/proxy-host-1_error.log
502 Bad Gateway: All Four Causes Reproduced with Exact Error Logs
Starting from the working whoami.localhost proxy host (ID 1), I broke one variable at a time, sent the same GET / request with Host: whoami.localhost, measured the exact response time, and captured the new line written to /data/logs/proxy-host-1_error.log:

Here are the four verbatim error log lines recorded in /data/logs/proxy-host-1_error.log across the four test cases:
# Cause 1: backend container stopped (docker stop gfl-npm-whoami) -> 502 after 4.03 s
[error] 304#304: *81 whoami could not be resolved (2: Server failure), client: 172.18.0.1, server: whoami.localhost, request: "GET / HTTP/1.1", host: "whoami.localhost"
# Cause 2: wrong forward port (8080; whoami listens on 80) -> 502 in 0.02 s
[error] 381#381: *95 connect() failed (111: Connection refused) while connecting to upstream, client: 172.18.0.1, server: whoami.localhost, request: "GET / HTTP/1.1", upstream: "http://172.18.0.2:8080/", host: "whoami.localhost"
# Cause 3: backend on a Docker network NPM is not attached to -> 502 after 4.02 s
[error] 451#451: *111 gfl-npm-whoami2 could not be resolved (2: Server failure), client: 172.18.0.1, server: whoami.localhost, request: "GET / HTTP/1.1", host: "whoami.localhost"
# Cause 4: 127.0.0.1 as the forward host (published on host as 127.0.0.1:8081) -> 502 in 0.02 s
[error] 535#535: *129 connect() failed (111: Connection refused) while connecting to upstream, client: 172.18.0.1, server: whoami.localhost, request: "GET / HTTP/1.1", upstream: "http://127.0.0.1:8081/", host: "whoami.localhost"
Mapping those four error signatures onto the Docker network topology makes it immediately clear why two of them fail in 4.02–4.03 s while the other two fail in 0.02 s:

As the topology diagram illustrates, the four 502 Bad Gateway causes split cleanly into two failure domains:
- DNS Resolution Failures (
could not be resolved (2: Server failure), Causes #1 & #3): When OpenResty evaluates$serveron an incoming request, it queries Docker's embedded DNS resolver at127.0.0.11:53. When the backend container is stopped (Cause #1,docker stop gfl-npm-whoami), Docker removes its A record fromgfl-npm-net; when the backend runs in a separate Compose project on its own default bridge (Cause #3,gfl-npm-whoami2ongfl-npm-other),127.0.0.11refuses to resolve names across isolated networks. In both cases, OpenResty waits approximately4.02–4.03 sbefore logging(2: Server failure)and returning502. - TCP Connection Refusals (
connect() failed (111: Connection refused), Causes #2 & #4): When DNS succeeds (or an IP literal is used), OpenResty sends a TCPSYNpacket directly to the resolvedupstreamsocket. In Cause #2 (whoami:8080),whoamiresolves to172.18.0.2, but the container only listens on port80, so its kernel replies with an immediate TCPRSTin0.02 s. In Cause #4 (127.0.0.1:8081),127.0.0.1refers togfl-npm-app's own network namespace (not your host PC) so OpenResty probes port8081inside itself and gets an immediate TCPRSTin0.02 s. For plain Nginx containers outside NPM that hit the same upstream refusal, see Nginx 502 Bad Gateway in Docker: Fix Upstream Connection Refused.
Plotting the measured response latencies across all six tested upstream states side-by-side highlights this 200x timing difference between a TCP RST refusal (20 ms) and a Docker DNS SERVFAIL timeout (4,020–4,030 ms):

That latency gap is a practical shortcut even before you open the logs: if clicking a proxied link returns 502 Bad Gateway instantaneously (~20 ms), you are looking at a 111: Connection refused port or loopback mismatch (Causes #2 or #4); if the browser tab spins for four seconds (~4,020 ms) before showing 502 Bad Gateway, OpenResty is timing out on Docker DNS lookup (2: Server failure, Causes #1 or #3).
Why the Green "Online" Status Dot Stays Lit During a 502 Outage
One of the most confusing parts of debugging Nginx Proxy Manager is that the Proxy Hosts table continues to display a green Online status dot while every client request returns 502 Bad Gateway. To verify why, I queried GET /api/nginx/proxy-hosts while Proxy Host #1 was pointed at broken port 8080 and simultaneously ran curl against http://whoami.localhost/:

The API JSON payload explains the paradox: "meta": {"nginx_online": true, "nginx_err": null}. In Nginx Proxy Manager's backend code, nginx_online is a boolean flag recorded when NPM writes /data/nginx/proxy_host/1.conf and runs /usr/sbin/nginx -t followed by /usr/sbin/nginx -s reload. Because set $server "whoami"; and set $port 8080; are valid Nginx syntax, nginx -t exits with 0 and NPM marks the host as nginx_online: true. NPM never performs an active TCP or HTTP health probe against http://whoami:8080.
Notice also the bottom command in that terminal capture: in Cause #3 (where gfl-npm-whoami2 was on gfl-npm-other), running docker network connect gfl-npm-other gfl-npm-app attached the running NPM container to the backend's network and made the very next request return HTTP/1.1 200 OK in 0.030 s without even clicking Save in the NPM WebUI. Meanwhile, comparing the NPM WebUI row (ID 4416) against the client browser viewport (ID 4417) during the port 8080 test shows how deceptive the green badge looks in practice:

http://whoami:8080 at the exact moment client requests receive OpenResty's 502 Bad Gateway page.In the top viewport above, the Proxy Hosts table lists whoami.localhost with destination http://whoami:8080 and a green Online pill; in the bottom viewport captured at the exact same moment, the browser receives the default 154-byte OpenResty 502 Bad Gateway HTML page. My scripted tests received that exact same 502 response body in all four failure scenarios, which is why reading /data/logs/proxy-host-1_error.log is mandatory.
Connecting Separate Compose Projects & Fixing Port 81 Conflicts
While docker network connect gfl-npm-other gfl-npm-app is useful for a quick live test, an imperative attachment can be lost when containers are recreated. When your backend services live in their own docker-compose.yml directories, the official NPM best-practice guide recommends declaring the shared NPM network (gfl-npm-net) as external: true in each backend Compose project. Similarly, if another container on your machine already occupies host port 81, you can remap only the host side of NPM's admin port to 127.0.0.1:8181:81:
# 1. In a separate backend project's docker-compose.yml: attach to existing gfl-npm-net
services:
whoami2:
image: 'traefik/whoami:latest'
container_name: gfl-npm-whoami2
networks:
- gfl-npm-net
networks:
gfl-npm-net:
external: true
# 2. In admin8181.override.yml: remap host port 81 -> 8181 while keeping 127.0.0.1 binding
services:
app:
ports: !override
- '127.0.0.1:80:80'
- '127.0.0.1:8181:81'
- '127.0.0.1:443:443'

To verify how Docker Compose behaves when port 81 does not open on the host, I reproduced both safe local failure cases from the folder containing compose.yml:
- Case A, The
81mapping is missing fromports:: I launched NPM with an override file (no81.override.yml) that published only ports80and443. Runningdocker port gfl-npm-applisted only80/tcp -> 127.0.0.1:80and443/tcp -> 127.0.0.1:443, and a host request failed withcurl: (7) Failed to connect to 127.0.0.1 port 81 after 2040 ms: Could not connect to server. However, runningcurlinside the container againsthttp://127.0.0.1:81/still returnedHTTP 200, proving that NPM itself was healthy and only the host port mapping was missing. Putting'127.0.0.1:81:81'back immediately restored host access. - Case B, Another container already holds
127.0.0.1:81: I stoppedgfl-npm-appand started a dummy container on port81(docker run -d --name gfl-npm-busy81 -p 127.0.0.1:81:80 traefik/whoami:latest). Runningdocker compose up -d appaborted with exit code1and printedError response from daemon: ... Bind for 127.0.0.1:81 failed: port is already allocated, while requests tohttp://127.0.0.1:81/returnedgfl-npm-busy81's page (Hostname: 7b9b3235f86c). Applyingadmin8181.override.yml(127.0.0.1:8181:81) brought NPM up cleanly withHTTP 200onhttp://127.0.0.1:8181/. For deeper host socket conflict resolution across Windows and Linux, see Docker Port Is Already Allocated: How to Find and Kill the Process.

If port 81 answers in your browser but renders another application's page instead of Nginx Proxy Manager, check docker ps (specifically the PORTS column) to see which container owns 127.0.0.1:81 or 0.0.0.0:81. While the NPM documentation also mentions an NPM_ADMIN_PORT environment variable to change the listening port inside the container, remapping the left-hand host side of the Compose port string ('127.0.0.1:8181:81') is cleaner because OpenResty and /usr/bin/check-health continue to use standard port 81 inside the container.
Combining our socket checks and /data/logs/proxy-host-<ID>_error.log signatures yields a deterministic troubleshooting decision tree you can walk through in under 60 seconds whenever port 81 or a proxy host fails:

Walking the decision tree from top to bottom eliminates guesswork:
- If the admin UI on port
81fails to load, rundocker ps -a --filter "name=gfl-npm-app"anddocker port gfl-npm-appfirst. AnExited (1)container points to a missing/etc/letsencryptmount; a running container without81/tcpindocker portmeans81:81was omitted fromports:; and a daemonport is already allocatederror means you should either stop the conflicting container or remap the host port to127.0.0.1:8181:81. - If a proxy host returns
502 Bad Gateway, ignore the green Online dot in the UI and rundocker exec gfl-npm-app tail -n 20 /data/logs/proxy-host-<ID>_error.log. If the log line sayscould not be resolved (2: Server failure)after a~4 swait, start the stopped backend container or attach both containers to the same Docker network (gfl-npm-net). If the log line saysconnect() failed (111: Connection refused)in0.02 s, inspect theupstream: "http://<IP>:<PORT>/"field:127.0.0.1means you accidentally pointed NPM at itself, whereas172.18.0.x:<PORT>means the Forward Port does not match the backend container's internal listening port.
For quick side-by-side reference during incident triage, the consolidated troubleshooting matrix card below summarizes all six reproduced failure modes, their exact timings, UI states, log strings, and verified fixes:

Limits, Scope & Pre-Production VPS Hardening Checklist
Before deploying this stack beyond a local PC, keep the exact boundaries of what I tested in mind:
- SSL certificates were not tested (no public domain): In my local loopback lab, the SSL tab of the proxy host modal (
ID 4419) remained atSSL Certificate: NonewithForce SSL,HTTP/2 Support, andHSTS Enabledturned off. Requesting a real Let's Encrypt certificate requires either a public domain pointed at ports80/443or a DNS-01 API token. - Single-host Docker Desktop baseline: All measurements come from single runs on Windows 11 with Docker Desktop (Engine
27.5.1). Notably,host.docker.internal:8081worked as a fix for Cause #4 because Docker Desktop injects that hostname automatically; on Linux Docker Engine, you must either addextra_hosts: ["host.docker.internal:host-gateway"]or, better yet, use a shared Docker bridge network (gfl-npm-net) and the Compose service name.
When moving Nginx Proxy Manager onto a Linux VPS, apply the three hardening rules summarized in the scorecard below, especially binding port 81 to 127.0.0.1 so Docker does not bypass your host firewall (see Docker Bypassing UFW Firewall on Ubuntu: Check Your Port Bindings):

Last reviewed: 2025-02-14. Tested on Nginx Proxy Manager 2.11.3 (OpenResty 1.25.3.2) with Docker Desktop (Docker Engine 27.5.1) on Windows 11, all ports bound to 127.0.0.1. The admin UI was driven through a headless Playwright browser session and verified against the NPM REST API. All four 502 Bad Gateway causes, both port 81 failure states, the INITIAL_ADMIN_PASSWORD plaintext log exposure, and the opt-in /usr/bin/check-health probe were reproduced and verified. SSL certificate issuance was not tested (no public domain).
Nginx Proxy Manager Port 81 Setup & Upstream 502 Q&A
Why does Nginx Proxy Manager show a green Online badge while returning 502 Bad Gateway?
The green Online status pill in Nginx Proxy Manager v2.11.3 only indicates that OpenResty parsed and loaded the generated proxy-host Nginx config syntax without error. It does not probe whether your upstream backend container is reachable.
What are the four most common causes of 502 Bad Gateway in Nginx Proxy Manager?
Pointing Forward Hostname at 127.0.0.1 instead of the container name, entering the host-mapped port instead of the internal container port, running NPM and the backend on separate Docker bridge networks, or selecting https Scheme when the backend speaks plain HTTP.
Where are the per-host upstream error logs stored inside the Nginx Proxy Manager container?
Run docker exec against your NPM container and read /data/logs/proxy-host-N_error.log. Look for no resolver defined / could not be resolved (stopped container or split Docker network) versus connect() failed 111: Connection refused (wrong port or 127.0.0.1).
Run Prefilled Sizing Math & Download the 1-Page Runbook
Replace fragile GUI proxy setups with declarative Nginx, Caddy 2, or Traefik v3 configs and boot-ordered health watchdogs.