Linux & Hosting

Reverse proxy with automatic HTTPS: Caddy for self-hosters

Updated 4 November 2026

Once you're running more than one service (see self-hosting for beginners), the :8096, :8080, :3000 port soup gets old fast, and none of it has HTTPS. A reverse proxy fixes both: one process listens on ports 80/443, terminates TLS, and forwards jellyfin.example.com to one container and photos.example.com to another. Every service gets a clean hostname and a padlock.

We recommend Caddy for self-hosters. Nginx and Traefik are excellent (more below), but Caddy's defining feature, automatic HTTPS with certificates it obtains and renews itself, zero configuration, removes the single biggest source of pain in this whole area.

Prerequisites

  • A domain, with DNS you control (Cloudflare's free tier is fine).
  • A server with ports 80 and 443 reachable from the internet: a VPS has this by default; at home you need router port-forwards and a non-CGNAT connection. (If that's not you, Tailscale + Caddy's internal CA works entirely privately: different article.)
  • Your services running, ideally in Docker Compose, not publishing ports to the host: the proxy will reach them over the Docker network.

1. DNS

Point each hostname at your server's IP. A wildcard saves future trips:

A     *.example.com    203.0.113.10
A     example.com      203.0.113.10

Using Cloudflare? Set these to DNS only (grey cloud) for now. Proxied mode works with Caddy but changes how certificates are validated: get the simple version working first.

2. Firewall

sudo ufw allow 80,443/tcp

(Everything else stays closed, per the hardening guide. Your services' ports are never exposed: only Caddy's.)

3. Caddy in Docker Compose

services:
  caddy:
    image: caddy:2
    restart: unless-stopped
    ports:
      - "80:80"
      - "443:443"
      - "443:443/udp"          # HTTP/3
    volumes:
      - ./Caddyfile:/etc/caddy/Caddyfile
      - caddy_data:/data        # certificates live here: persist it!
      - caddy_config:/config
    networks:
      - proxy

networks:
  proxy:
    external: true

volumes:
  caddy_data:
  caddy_config:

Create the shared network once (docker network create proxy) and attach each service's compose file to it with the same networks: [proxy] block. Now Caddy can reach containers by their service name.

4. The Caddyfile

This is the whole configuration for three services with HTTPS:

jellyfin.example.com {
    reverse_proxy jellyfin:8096
}

photos.example.com {
    reverse_proxy immich-server:2283
}

cloud.example.com {
    reverse_proxy nextcloud:80
}

That's not a snippet: that's the file. On docker compose up -d, Caddy requests a Let's Encrypt certificate for each hostname, serves it, redirects HTTP → HTTPS, and renews automatically for as long as it runs. Change the file, run docker compose exec caddy caddy reload --config /etc/caddy/Caddyfile, done.

Useful additions you'll want eventually:

# basic auth in front of something that has none
admin.example.com {
    basic_auth {
        rob $2a$14$...bcrypt-hash-from-`caddy hash-password`...
    }
    reverse_proxy some-dashboard:8080
}

# only allow your LAN / VPN to reach a service
internal.example.com {
    @denied not remote_ip 192.168.1.0/24 100.64.0.0/10
    respond @denied 403
    reverse_proxy private-thing:9000
}

# serve a static site straight from a folder
example.com {
    root * /srv/www
    file_server
}

Caddyfile reverse proxy examples

These Caddyfile reverse proxy examples are minimal patterns adapted from the official Caddy documentation, so you will need to adjust the domain, ports and paths, because the docs themselves say they "are not drop-in solutions".

Proxy only /api and serve files for the rest

The /api/* matcher sends only those requests to the backend, and everything else is served from the site root. This works because reverse_proxy is higher in Caddy's directive order than file_server. Source: Common Caddyfile Patterns.

example.com {
    root /var/www
    reverse_proxy /api/* localhost:5000
    file_server
}

Several apps on one domain under path prefixes

handle_path strips the prefix before proxying. The docs warn that most apps do not work in a subfolder unless configured for it: set the app's base path or public URL if it has one, and use handle instead of handle_path if the app expects the prefix. Otherwise, give each app its own subdomain as shown earlier on this page. Source: Common Caddyfile Patterns.

example.com {
    handle_path /app1/* {
        reverse_proxy localhost:5001
    }
    handle_path /app2/* {
        reverse_proxy localhost:5002
    }
    handle {
        respond "Not found" 404
    }
}

A maintenance page while the backend is down

When reverse_proxy cannot connect it produces a 502 (or a 503 if no upstream is available), which handle_errors catches. The page is served with the error status, so clients and search engines know the outage is temporary. Source: Common Caddyfile Patterns.

example.com {
    reverse_proxy localhost:5000
    handle_errors 502 503 {
        root * /srv/maintenance
        rewrite * /index.html
        file_server
    }
}

Load balancing, sticky sessions and health checks

Listing several upstreams load-balances between them, and the cookie policy keeps a visitor on the same backend. health_uri turns on active health checks in the background, and lb_try_duration holds a request and retries until a healthy backend is found. This block combines two separate examples from the docs. Source: reverse_proxy directive.

example.com {
    reverse_proxy /api/* node1:80 node2:80 node3:80 {
        lb_policy cookie api_sticky
        health_uri /healthz
        lb_try_duration 5s
    }
}

Timeouts for a slow backend

dial_timeout caps how long Caddy waits to connect to the backend (the default is 3s), and response_header_timeout caps how long it waits for the backend's response headers (no timeout by default). Source: reverse_proxy directive.

example.com {
    reverse_proxy localhost:8080 {
        transport http {
            dial_timeout 2s
            response_header_timeout 30s
        }
    }
}

Proxy to an HTTPS upstream

Since Caddy v2.11.0, the Host header is set to match the upstream automatically. The docs also show tls_insecure_skip_verify, marked NOT RECOMMENDED because it disables all the security checks HTTPS offers, so where possible proxy over plain HTTP on a private network instead. Source: reverse_proxy directive.

example.com {
    reverse_proxy https://example.com
}

Match on more than a path (named matcher)

Define a named matcher, then refer to it with @name. Both parts go inside a site block. Source: Request matchers.

@postfoo {
    method POST
    path /foo/*
}
reverse_proxy @postfoo localhost:9000

After editing, reload with the command from earlier on this page: docker compose exec caddy caddy reload --config /etc/caddy/Caddyfile.

5. Check it worked

curl -I https://jellyfin.example.com
# HTTP/2 200 ... server: Caddy

docker compose logs caddy | grep -i certificate

Cert failing? 95% of the time it's one of: DNS not propagated yet, port 80 blocked (Let's Encrypt's HTTP challenge needs it), or Cloudflare proxy turned on. Rate-limit warnings mean you've retried too often: wait an hour.

Caddy vs Nginx vs Traefik

  • Caddy: simplest by a distance; automatic HTTPS; config you can read a year later. Our pick unless you have a reason not to.
  • Nginx (+ Certbot): the industry standard, endlessly documented, but certificates are a separate moving part you must set up and keep renewing. Nginx Proxy Manager wraps it in a web UI, which many self-hosters like.
  • Traefik: configures itself from Docker labels; wonderful once mastered, steeper to learn, and its config lives scattered across every compose file. Best when services come and go constantly.

Whichever you pick, the architecture is the same: one door, TLS terminated in one place, services on a private network behind it. It's the moment a pile of containers starts feeling like infrastructure.