Caddy: HTTPS reverse proxy in five lines

Caddy is a web server whose main selling point is automatic HTTPS: give it a domain name and it obtains a certificate from Let’s Encrypt or ZeroSSL, redirects HTTP to HTTPS, renews before expiry and picks sane TLS settings, with nothing to configure. The configuration language, the Caddyfile, is designed to be short. This is the whole reverse proxy:

app.example.com {
    reverse_proxy localhost:3000
}

Before you start

• A server with ports 80 and 443 open to the internet (sudo ufw allow 80,443/tcp if you use ufw).
• A DNS A record (and AAAA if applicable) for app.example.com pointing at that server.
• Your application running and listening on a local port, here 3000.

1. Install Caddy

On Debian and Ubuntu, the official repository gives you a package plus a systemd service that runs Caddy as its own user:

sudo apt install -y debian-keyring debian-archive-keyring apt-transport-https curl
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
caddy version

Fedora and RHEL have a caddy package in the standard repositories (sudo dnf install caddy), and the install page covers Arch, Docker and static binaries. After installing, systemctl status caddy should show it running and serving a placeholder page on port 80.

2. Write the Caddyfile

The service reads /etc/caddy/Caddyfile. Replace its contents:

app.example.com {
    reverse_proxy localhost:3000
}

That is the five lines, with whitespace. The first line is the site address. Because it is a real domain name, Caddy knows it must serve it over HTTPS and go and get a certificate. reverse_proxy forwards every request to the app and automatically sets X-Forwarded-For, X-Forwarded-Proto and X-Forwarded-Host; WebSockets work without extra configuration.

3. Reload

caddy validate --config /etc/caddy/Caddyfile
sudo systemctl reload caddy
journalctl -u caddy -f

Within a few seconds the log shows the certificate being obtained and https://app.example.com works, including the redirect from http://. Careful: a reload applies the file to every site Caddy serves; the previous configuration is not kept, so keep a copy of the Caddyfile before editing (sudo cp /etc/caddy/Caddyfile /etc/caddy/Caddyfile.bak) and reload that copy to go back.

If the certificate step fails, the log says why. The usual causes are DNS not yet pointing at the server, port 80 or 443 blocked by a firewall or cloud security group, or another web server already using the ports (sudo ss -ltnp | grep -E ':(80|443)').

More than the minimum

{
    email [email protected]
}

app.example.com {
    encode zstd gzip

    header {
        Strict-Transport-Security "max-age=31536000; includeSubDomains"
        X-Content-Type-Options nosniff
        Referrer-Policy strict-origin-when-cross-origin
        -Server
    }

    handle_path /api/* {
        reverse_proxy localhost:8000
    }

    handle {
        reverse_proxy localhost:3000
    }

    log {
        output file /var/log/caddy/app.log
    }
}

www.example.com {
    redir https://example.com{uri} permanent
}

example.com {
    root * /var/www/example
    file_server
}

• The { } block at the top is global options; email is where Let’s Encrypt sends expiry warnings (which you should never receive, since Caddy renews on its own).
• encode compresses responses. header adds response headers; the -Server line removes the Server: Caddy header.
• handle_path /api/* routes requests under /api/ to a second app and strips the prefix, so the backend sees /users instead of /api/users. Use handle instead of handle_path to keep the prefix.
• Several sites are just several blocks; each gets its own certificate.
• caddy fmt --overwrite /etc/caddy/Caddyfile tidies the indentation.

Local and internal use

For a hostname that is not reachable from the internet, Caddy can issue certificates from its own local certificate authority instead:

intranet.lan {
    tls internal
    reverse_proxy localhost:3000
}

localhost {
    reverse_proxy localhost:3000
}

localhost and names ending in .localhost get internal certificates automatically. caddy trust installs the local root into the system trust store so browsers accept them. To serve plain HTTP on purpose, write the address with a scheme or port: http://intranet.lan or :8080.

Where things are

• Configuration: /etc/caddy/Caddyfile. Caddy also has a JSON config and a REST API on localhost:2019; the Caddyfile is converted to JSON internally.
• Certificates and keys: /var/lib/caddy/.local/share/caddy/. Back this folder up with the server; losing it only means certificates are requested again.
• Logs: journalctl -u caddy, or the file you configured with log.
• Run caddy run --config /etc/caddy/Caddyfile in a terminal to see errors directly when debugging.

Official documentation

• Reverse proxy quick start
• Caddyfile concepts and directives
• Automatic HTTPS