Reverse proxy and TLS, done properly

Every service you install wants a port. Jellyfin takes 8096, Immich takes 2283, Home Assistant takes 8123, and Uptime Kuma takes 3001. Each of them serves plain HTTP and each of them has its own idea about certificates, if it has one at all. Ten services in, you have ten port numbers memorized, at least one collision you worked around by editing a compose file at 1am, and no TLS anywhere because doing it per app is ten times the work.

One reverse proxy collapses all of that. Two ports are open, 80 and 443. Every service gets a hostname. Certificates are obtained, renewed and stapled in one place by one process that has exactly one job. Nothing else on the machine needs to know that TLS exists.

Which proxy, honestly#

Use Caddy. It idles at about 25 MB, the config for a working HTTPS reverse proxy is two lines, and certificate renewal is genuinely unattended rather than a cron job you find broken in eight months. Its ops load is 1 out of 5 in this index and that rating is earned.

Two situations change the answer.

Use Traefik if your services come and go. Traefik builds its routing table from Docker labels, so a container that starts with traefik.enable=true and a router label is routable a second later, with a certificate. Nothing file-based matches that. You pay for it: the internet is full of v2 snippets and Traefik does not tell you when you paste one. On v3 rule values go in backticks and combine with &&, Headers became Header, and IPWhiteList became IPAllowList. A stale label does not error. It just fails to match and you get a 404 from whichever router did match. That is why Traefik sits at ops 3 and Caddy at ops 1.

Use Nginx Proxy Manager if you want a form, not a file. Type a domain, an upstream host and port, tick the Let's Encrypt box. Nothing else in this category is that low friction, and it is the honest answer for a household where someone other than you might need to add a proxy host. The uncomfortable part: it is effectively one maintainer, the v3 rewrite has been open since June 2021, and the UI is the source of truth. Anything you hand-edit under /data/nginx gets regenerated on the next save.

Both alternatives are defensible. Reaching for nginx and certbot by hand in 2026 is not, unless you already have an nginx config estate and people who read nginx.

See Caddy vs Traefik for the head to head, and Reverse proxy generator to produce config for your actual hostnames.

HTTP-01 or DNS-01: the decision nobody explains properly#

ACME certificate authorities need proof you control a name. There are two challenge types you will realistically use, and picking wrong is the most common reason a homelab ends up with self-signed certificates and permanently trained-away browser warnings.

The rule that matters: if the hostname does not resolve to your public IP from the internet, HTTP-01 cannot work, and DNS-01 is the only route to a publicly trusted certificate. This is not a limitation you can engineer around. The CA has to reach something. With DNS-01 the thing it reaches is your DNS provider, not your server, which is why nas.home.example.com can point at 192.168.1.20 and still get a real certificate from Let's Encrypt.

That also covers the second common case: an ISP that blocks inbound 80, or a CGNAT connection where you have no inbound at all. Same answer.

Caddy has one trap here. The official binary and the official caddy Docker image ship zero DNS provider modules. The moment you want DNS-01 you have to build with xcaddy build --with github.com/caddy-dns/cloudflare or use the :builder image in a two-stage Dockerfile, and you own that build pipeline on every upgrade. It is fifteen lines of Dockerfile and it is the price of internal certificates.

While you are experimenting, point at the staging CA. Let's Encrypt allows 50 certificates per registered domain per week and 5 duplicates of the exact same name set, and a redeploy loop with no persistent storage burns through that in an afternoon. Which brings us to the other rule: mount a volume at /data before you point real DNS at Caddy, or every container recreate requests every certificate again.

The headers, and exactly what breaks without each one#

A reverse proxy terminates the client's connection and opens a new one. The backend now sees a request from 172.18.0.1 over plain HTTP to localhost. Four headers restore the truth, and each one has a distinct failure mode.

Caddy's reverse_proxy sets X-Forwarded-For, X-Forwarded-Proto and X-Forwarded-Host automatically and passes the original Host through unchanged. Traefik does the same. nginx does none of it unless you write the proxy_set_header lines yourself. This is most of the reason to prefer a proxy that was designed after 2015.

The second half of the problem is on the app side: most applications ignore X-Forwarded-* unless you tell them to trust the proxy. Nextcloud wants trusted_proxies in config.php, Django apps want SECURE_PROXY_SSL_HEADER, and getting it wrong in the other direction is a spoofing hole, because anyone who can reach the app directly can forge the header. Bind your apps to the Docker network only, never to 0.0.0.0.

The two bugs that look like application bugs#

Websockets. The page loads, then nothing updates. No error in the app log, no error in the proxy log, because the request was proxied successfully as an ordinary HTTP request that the backend then refused to upgrade. Uptime Kuma, Home Assistant, Immich's upload progress and anything with a live view all depend on this. Caddy and Traefik upgrade automatically. In Nginx Proxy Manager it is a per-host checkbox that is off by default, which is why this is such a persistent support thread.

413 on upload. nginx sets client_max_body_size to 1 MB by default and returns 413 above it. A 40 MB photo import into Immich or a scanned PDF into Paperless-ngx dies at the proxy, and the application never sees the request, so its logs are clean and you go looking for a bug that is not there. Caddy and Traefik have no default body limit; if you want one in Caddy it is request_body { max_size 100MB }, which also returns 413.

Working Caddyfile#

This covers an internet-facing service, an internal-only service with a wildcard from DNS-01, and a raised body limit.

{
	email admin@example.com
}

jellyfin.example.com {
	reverse_proxy 10.0.0.20:8096
}

photos.example.com {
	request_body {
		max_size 5GB
	}
	reverse_proxy 10.0.0.20:2283
}

*.home.example.com {
	tls {
		dns cloudflare {env.CF_API_TOKEN}
		resolvers 1.1.1.1
	}

	@ha host ha.home.example.com
	handle @ha {
		reverse_proxy 10.0.0.30:8123
	}

	@vault host vault.home.example.com
	handle @vault {
		reverse_proxy 10.0.0.30:8080
	}

	handle {
		abort
	}
}

Two things worth knowing. Directives run in a fixed built-in order, not the order you wrote them, which is why the internal block uses handle blocks: those are mutually exclusive and evaluated top to bottom. And caddy adapt --config Caddyfile prints the JSON that actually runs, which is the fastest way to find out that your matcher does not match what you think.

Working Traefik v3 labels#

services:
  traefik:
    image: traefik:v3.7
    restart: unless-stopped
    command:
      - --providers.docker=true
      - --providers.docker.exposedByDefault=false
      - --entryPoints.web.address=:80
      - --entryPoints.web.http.redirections.entryPoint.to=websecure
      - --entryPoints.web.http.redirections.entryPoint.scheme=https
      - --entryPoints.websecure.address=:443
      - --certificatesResolvers.le.acme.email=admin@example.com
      - --certificatesResolvers.le.acme.storage=/acme.json
      - --certificatesResolvers.le.acme.dnsChallenge.provider=cloudflare
    environment:
      CF_DNS_API_TOKEN_FILE: /run/secrets/cf_token
    ports:
      - "80:80"
      - "443:443"
    volumes:
      - /var/run/docker.sock:/var/run/docker.sock:ro
      - ./acme.json:/acme.json

  jellyfin:
    image: jellyfin/jellyfin:latest
    restart: unless-stopped
    labels:
      traefik.enable: "true"
      traefik.http.routers.jellyfin.rule: "Host(`jellyfin.example.com`)"
      traefik.http.routers.jellyfin.entrypoints: "websecure"
      traefik.http.routers.jellyfin.tls.certresolver: "le"
      traefik.http.services.jellyfin.loadbalancer.server.port: "8096"

Run touch acme.json && chmod 600 acme.json before the first start. If the host path does not exist, Docker creates a directory with that name, Traefik cannot persist certificates, and it re-requests them on every restart until Let's Encrypt stops answering. The 600 mode is enforced, and a group-readable file is ignored with a warning most people never read.

Also note that --providers.docker gives Traefik read access to the Docker socket, which means it can enumerate every container, its environment variables and its mounts. Mount it read-only at minimum and consider a socket proxy.

HSTS: set it late, set it low#

Strict-Transport-Security tells browsers to refuse plain HTTP to your domain for max-age seconds. It is a good header and it is close to irreversible, because the instruction lives in the browser's cache, not on your server. A year-long max-age on a domain you later need to serve over HTTP means a year of broken clients that you cannot fix from your end.

Start at max-age=300. Run it for a week. Raise it once you are sure nothing in the house depends on plain HTTP. Do not add includeSubDomains until every subdomain has a certificate, and do not submit to the preload list at all unless you are certain, because removal takes months and ships on browser release trains.

What to do next#

Buy a domain if you do not have one, then read DNS for self-hosters for the naming scheme and split-horizon resolution that make internal names work. If you want these services reachable away from home, Remote access without port forwarding covers the four routes and why exposing an app's own login page is the wrong one. If you are putting authentication in front of services rather than relying on each app's login, Authelia and authentik both integrate with the proxy through forward auth, and Single sign-on for self-hosters is honest about how far that gets you.

Generate a starting config for your own hostnames with Reverse proxy generator, and check for overlapping defaults before you assign ports with Port conflict checker.