TL;DR: Nginx Proxy Manager ships with one goal: get a reverse proxy with Let's Encrypt certs running in under ten minutes. It delivers on that.
📖 Reading time: ~20 min
What's in this article
- Why the Default NPM Config Leaves Performance on the Table
- Getting NPM Running the Right Way in Docker
- Worker and Buffer Tuning Inside the Generated nginx.conf
- Proxy Host Advanced Settings That Actually Matter
- SSL Performance: Let's Encrypt, Wildcard Certs, and HSTS Pitfalls
- Monitoring NPM and Catching Problems Before Users Do
- When NPM Is the Wrong Tool
Why the Default NPM Config Leaves Performance on the Table
Nginx Proxy Manager ships with one goal: get a reverse proxy with Let's Encrypt certs running in under ten minutes. It delivers on that. What it doesn't deliver is a config that holds up under anything resembling real traffic. The defaults reflect shared-hosting assumptions — conservative buffer sizes, short keepalive windows, worker counts that don't account for your actual CPU topology. On a machine you own, those aren't safe defaults, they're just wrong defaults.
The symptoms are recognizable once you know what to look for. Upstream timeouts on long-running API responses — say, a local Ollama inference call or an OpenAI streaming response that takes 45 seconds — because proxy_read_timeout ships at 60s and NPM's UI doesn't expose it per-host without a custom config block. 502s during n8n webhook bursts because the upstream queue fills faster than the default buffer can drain. And SSL handshake latency that eats 80–150ms on every short request because session resumption isn't configured and the TLS ticket key rotation is left at defaults. That last one is invisible in synthetic benchmarks but shows up immediately when you're proxying lots of small API calls.
The underlying issue is that NPM wraps nginx in a management layer — which is genuinely useful — but it also abstracts away the knobs that matter. The generated nginx.conf in a stock Docker deployment looks roughly like this:
worker_processes auto;
# "auto" resolves to 1 on a 1-vCPU container — fine for a VPS,
# wrong for a 16-core workstation running in Docker with --cpus not set
worker_connections 1024;
# 1024 total across all workers; saturates fast under webhook fan-out
http {
# no proxy_cache_path defined — caching is entirely disabled
# keepalive_timeout 75s — upstream keepalives not configured at all
# client_max_body_size 1m — will silently drop file uploads
# gzip off — yes, off by default
}
What this article works through: the specific /data/nginx/custom override files that NPM actually reads, per-proxy-host advanced config blocks that survive container restarts, how to set proxy_read_timeout and proxy_send_timeout high enough for LLM API responses without opening yourself up to connection exhaustion, and how to wire up upstream keepalives so n8n webhook throughput stops degrading under burst load. Everything here runs on a Docker Compose stack — NPM 2.x on top of nginx 1.25 — so the file paths and config injection points are concrete and reproducible.
Getting NPM Running the Right Way in Docker
The volume mount decision trips up more NPM deployments than any config mistake. When you bind-mount /path/on/host/data directly on an ext4 filesystem and NPM starts hammering Let's Encrypt renewals plus proxy host writes simultaneously, you can hit inode exhaustion or contention-driven write stalls — especially on VPS images provisioned with small inode counts. Named volumes let Docker manage that I/O through its own storage driver layer, which sidesteps the problem entirely. The fix is one line in your compose file, and it costs nothing.
Here's a compose file that avoids the common traps:
services:
npm:
image: jc21/nginx-proxy-manager:2.11.3 # pinned — not latest
container_name: npm
restart: unless-stopped
ports:
- "80:80"
- "443:443"
- "81:81"
environment:
DB_SQLITE_FILE: "/data/database.sqlite"
DISABLE_IPV6: "true" # drop this only if your LAN actually routes v6
X_FRAME_OPTIONS: "sameorigin" # default is DENY, which breaks iframe embeds
volumes:
- npm_data:/data
- npm_letsencrypt:/etc/letsencrypt
healthcheck:
test: ["CMD", "curl", "-sf", "http://localhost:81/api"]
interval: 30s
timeout: 10s
retries: 5
start_period: 20s
volumes:
npm_data:
npm_letsencrypt:
Pin the image. Between 2.10.x and 2.11.x, upstream NPM changed how it stores custom Nginx config snippets in SQLite, and containers that got auto-pulled to a new minor broke existing advanced proxy host configs silently — the proxy kept running from the old rendered config on disk, but any edit triggered a regeneration that dropped custom directives. You won't catch that until you touch a host entry. 2.11.3 is the last version I've validated on my stack; check the guide covers how local-model setups interact with reverse proxy constraints like auth headers and streaming timeouts, which is worth reading before you wire an Ollama endpoint or OpenAI-compatible server through NPM for the first time.
When NPM Is the Wrong Tool
The 30-proxy-host threshold is roughly where NPM's SQLite backend starts working against you rather than for you. Below that, the GUI is a genuine time-saver. Above it, you're fighting drift: a host edited in the UI doesn't show up in Git, rollbacks mean restoring a SQLite file, and your "config" is effectively a database dump. If you're already running infrastructure-as-code for everything else — Terraform, Ansible, Docker Compose in a repo — NPM becomes the odd one out that you can't peer-review or diff. Caddy with a committed Caddyfile or Traefik driven by Docker labels both solve this cleanly. A git diff on a Caddyfile shows exactly what changed and when; NPM's export JSON does not.
# Caddy equivalent of a typical NPM reverse proxy entry — version-controllable, reviewable
app.example.com {
reverse_proxy localhost:3000 {
header_up Host {host}
header_up X-Real-IP {remote_host}
}
tls [email protected] # ACME handled inline, no separate certbot process
}
The Streams tab in NPM exposes TCP/UDP proxying, and it works for basic cases — forwarding a Minecraft port or a WireGuard UDP endpoint is straightforward. What you don't get is any tuning surface: no proxy_timeout, no proxy_buffer_size, no proxy_connect_timeout, no way to set so_keepalive on the upstream socket. For a game server where a 200ms TCP timeout difference is felt by players, or a Postgres tunnel where you want fine-grained keepalive behavior, you need a raw nginx container with a hand-written stream {} block. That's not a workaround — it's the right architecture for the use case.
# stream block nginx config for a latency-sensitive TCP tunnel
# mount this as /etc/nginx/nginx.conf in a plain nginx:alpine container
stream {
upstream db_backend {
server 10.0.0.5:5432;
}
server {
listen 5432;
proxy_pass db_backend;
proxy_timeout 10s; # fail fast — don't let stale connections pile up
proxy_connect_timeout 2s;
proxy_buffer_size 16k; # default 16k is fine for PG, tune down for game protocols
}
}
The process count is the other honest liability. NPM runs nginx, a Node.js GUI server, SQLite, and a Certbot/openssl-backed certificate renewal loop. On a 4GB homelab VM that's background noise. On a device with 512MB or 768MB RAM — an older Raspberry Pi, an edge node, a cheap VPS — that overhead is measurable in available headroom for your actual workloads. Caddy is a single statically-linked binary that handles TLS automatically; bare nginx is even leaner. For edge nodes or constrained devices, install Caddy via its official package and skip the container stack entirely:
# Caddy on a Debian/Ubuntu edge node — no Docker, no secondary processes
sudo apt install -y debian-keyring debian-archive-keyring apt-transport-https
curl -1sLf 'https://dl.cloudsmith.io/public/caddy/stable/gpg.key' | sudo gpg --dearmor -o /usr/share/keyrings/caddy-stable-archive-keyring.gpg
curl -1sLf 'https://dl.cloudsmith.io/public/caddy/stable/debian.deb.txt' | sudo tee /etc/apt/sources.list.d/caddy-stable.list
sudo apt update && sudo apt install caddy
# Binary is ~45MB, zero runtime dependencies, TLS built in
The honest summary: NPM earns its keep for solo operators managing a moderate number of HTTPS reverse proxies who want a visual cert dashboard and don't need repeatability guarantees. Push past that boundary in any direction — scale, IaC discipline, non-HTTP protocols, constrained hardware — and the abstraction layer NPM adds becomes friction rather than utility. Knowing which side of that line your setup sits on saves you from bolting on workarounds that never quite fit.
Disclaimer: This article is for informational purposes only. The views and opinions expressed are those of the author(s) and do not necessarily reflect the official policy or position of Sonic Rocket or its affiliates. Always consult with a certified professional before making any financial or technical decisions based on this content.
Originally published on techdigestor.com. Follow for more developer-focused tooling reviews and productivity guides.
SOCIAL SHARE CARD GENERATOR