Caddy as a Reverse Proxy with Automatic HTTPS
Install Caddy on Debian or Ubuntu from its official repository, publish an application with automatic HTTPS, protect an admin interface, then update and back up.
On this page
Your values
Enter them once and the commands in this guide update.
This guide explains how to place Caddy in front of an application hosted on your server. Caddy receives visitors on ports 80 and 443, obtains and renews the TLS certificate on its own, then forwards requests to the application, which stays reachable only locally.
By the end of the guide, your application answers on https://app.your-domain.com, HTTP traffic is redirected to HTTPS, and you know how to protect an admin interface, update Caddy and back up its data.
Order a Server
This guide applies to servers that you administer yourself:
Prerequisites
- A server running Debian 12 or 13, or Ubuntu 22.04 or 24.04
- SSH access with a user that has
sudo - A domain name whose DNS zone you manage
- An application that listens locally, for example on
127.0.0.1:3000 - No other software using ports 80 and 443, such as Nginx or Apache
Ports Used
| Port | Direction | Purpose | To open |
|---|---|---|---|
| 80/tcp | Inbound | HTTP-01 validation and redirect to HTTPS | Yes |
| 443/tcp | Inbound | HTTPS (HTTP/1.1 and HTTP/2) and TLS-ALPN-01 validation | Yes |
| 443/udp | Inbound | HTTP/3 | Recommended |
| 2019/tcp | Local | Caddy admin API, on localhost |
No |
| 3000/tcp | Local | Example application | No |
Step 1: Point the Domain to the Server
Create an A record for app.your-domain.com pointing to YOUR_SERVER_IP. If your domain is managed at HostMyServers, follow the guide Create an A record.
Then check the result from the server:
sudo apt update
sudo apt install -y bind9-dnsutils
dig +short A app.your-domain.com
dig +short AAAA app.your-domain.comThe first command must return your server's address. If the second returns an IPv6 address, it must also match this server: the certificate authority may use it to validate the domain. Otherwise, delete that AAAA record.
Step 2: Install Caddy from the Official Repository
Add the stable repository published by the Caddy project, then install the package:
sudo apt install -y debian-keyring debian-archive-keyring apt-transport-https curl gnupg
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 chmod o+r /usr/share/keyrings/caddy-stable-archive-keyring.gpg
sudo chmod o+r /etc/apt/sources.list.d/caddy-stable.list
sudo apt update
sudo apt install -y caddyThe package creates the caddy system user and starts the service of the same name. Check the installation:
caddy version
systemctl status caddy --no-pagerStep 3: Open the Firewall
If you use UFW, allow the web ports:
sudo ufw allow 80/tcp
sudo ufw allow 443/tcp
sudo ufw allow 443/udp
sudo ufw statusCheck that the application responds locally:
curl -I http://127.0.0.1:3000If it runs in Docker, publish its port on the loopback interface only, with 127.0.0.1:3000:3000. A port published as 3000:3000 stays reachable from the Internet, because Docker inserts its own firewall rules and UFW does not filter them.
Step 4: Write the Caddyfile
Keep the supplied file, then open it:
sudo cp /etc/caddy/Caddyfile /etc/caddy/Caddyfile.orig
sudo nano /etc/caddy/CaddyfileReplace its contents with:
{
email admin@your-domain.com
}
app.your-domain.com {
encode zstd gzip
reverse_proxy 127.0.0.1:3000
}| Element | Purpose |
|---|---|
email |
Address linked to the ACME account, useful if there is a certificate problem |
app.your-domain.com |
Public name: its presence enables automatic HTTPS |
encode zstd gzip |
Response compression |
reverse_proxy |
Forwards requests to the application |
Caddy handles the HTTP to HTTPS redirect and WebSocket passthrough on its own. It also sets the X-Forwarded-For, X-Forwarded-Proto and X-Forwarded-Host headers, and passes the original Host to an HTTP application.
Step 5: Validate and Apply the Configuration
sudo caddy fmt --overwrite /etc/caddy/Caddyfile
sudo -u caddy caddy validate --config /etc/caddy/Caddyfile --adapter caddyfile
sudo systemctl reload caddyReloading does not drop existing connections. If the new configuration is rejected, Caddy keeps running with the previous one.
Check the Result
Look at the logs, then test both protocols:
sudo journalctl -u caddy --no-pager -n 50
curl -I http://app.your-domain.com
curl -I https://app.your-domain.comThe HTTP request must return a 308 redirect to HTTPS, and the HTTPS request must return your application's response. The logs must contain certificate obtained successfully.
Then check the certificate issuer and dates, as well as the listening ports:
echo | openssl s_client -connect app.your-domain.com:443 -servername app.your-domain.com 2>/dev/null | openssl x509 -noout -issuer -dates
sudo ss -tulpn | grep caddyPort 2019 must appear only on 127.0.0.1. From your computer, the address http://YOUR_SERVER_IP:3000 must not respond.
Publish Several Sites
To keep one file per site, create a dedicated folder:
sudo mkdir -p /etc/caddy/sites
sudo nano /etc/caddy/sites/app.caddyPut the site block in /etc/caddy/sites/app.caddy:
app.your-domain.com {
encode zstd gzip
reverse_proxy 127.0.0.1:3000
}The /etc/caddy/Caddyfile file now contains only the global options and the import:
{
email admin@your-domain.com
}
import sites/*.caddyValidate and reload again as in step 5.
Protect an Admin Interface
An admin interface must not be open to everyone. The following example combines two protections: only your IP address is accepted, then a password is required.
First generate the password hash. The command asks for the password twice and prints the result:
caddy hash-passwordThen add this site, replacing BCRYPT_HASH with the hash you obtained:
admin.your-domain.com {
@allowed client_ip YOUR_IP
handle @allowed {
basic_auth {
admin BCRYPT_HASH
}
reverse_proxy 127.0.0.1:9000
}
handle {
abort
}
}Connections from any other address are dropped without a response. If your IP address changes often, reserve this interface for a private network instead, using WireGuard or Tailscale.
Common Settings
Load Balance Across Several Instances
app.your-domain.com {
reverse_proxy 127.0.0.1:3001 127.0.0.1:3002 {
lb_policy round_robin
health_uri /health
health_interval 10s
}
}The /health URL must exist in your application and respond with a 2xx code. An instance that fails this check is taken out of rotation until it recovers.
Reach an Application over HTTPS
app.your-domain.com {
reverse_proxy https://127.0.0.1:8443 {
header_up Host {host}
transport http {
tls_server_name backend.your-domain.com
}
}
}Caddy verifies the application's certificate. tls_server_name must match a name present in that certificate. Since Caddy 2.11, the Host sent to an HTTPS target is the target's own by default: header_up Host {host} keeps the public name for applications that need it.
Write Access Logs to a File
app.your-domain.com {
log {
output file /var/log/caddy/app.log
}
reverse_proxy 127.0.0.1:3000
}The package creates /var/log/caddy for the caddy user. Keep your logs in this folder to avoid permission errors.
Place Caddy Behind Another Proxy
If another proxy receives visitors before Caddy, declare its address in the global options. Without this, Caddy ignores the client address that this proxy passes to it.
{
email admin@your-domain.com
servers {
trusted_proxies static 203.0.113.10/32
}
}Update Caddy
Since Caddy is installed from a package, update it with APT:
sudo apt update
sudo apt install --only-upgrade caddy
caddy version
systemctl status caddy --no-pagerDo not use caddy upgrade on this installation: this experimental command directly replaces the binary managed by the package.
Back Up and Restore
Two locations should be kept:
| Path | Contents |
|---|---|
/etc/caddy/ |
Caddyfile and imported files |
/var/lib/caddy/.local/share/caddy/ |
Certificates, private keys and ACME accounts |
sudo tar -czf /root/caddy-$(date +%F).tar.gz /etc/caddy /var/lib/caddy/.local/share/caddy
sudo chmod 600 /root/caddy-$(date +%F).tar.gzThis archive contains private keys: copy it off the server to an encrypted location. The data folder is not a cache. Keeping it avoids requesting all certificates again and running into the certificate authority's limits.
To restore the archive on a server where Caddy is installed, replacing YYYY-MM-DD with its date:
sudo systemctl stop caddy
sudo tar -xzf /root/caddy-YYYY-MM-DD.tar.gz -C /
sudo chown -R caddy:caddy /var/lib/caddy
sudo systemctl start caddyTroubleshooting
listen tcp :80: bind: address already in use
Another service is using port 80 or 443:
sudo ss -ltnp | grep -E ':(80|443) 'Stop and disable that service if it is no longer needed, for example with sudo systemctl disable --now nginx.
urn:ietf:params:acme:error:dns or NXDOMAIN
The name does not exist in DNS yet, or propagation is not complete. Check with dig +short A app.your-domain.com. Caddy retries on its own: there is no need to restart it repeatedly.
urn:ietf:params:acme:error:unauthorized or urn:ietf:params:acme:error:connection
The certificate authority could not reach this server. Check the A and AAAA records, then the firewall rules for ports 80 and 443. If everything is correct on the server and the port remains unreachable from outside, contact support from your client area.
urn:ietf:params:acme:error:caa
A CAA record on the domain forbids the authority being used. Add the relevant authority to it, letsencrypt.org for Let's Encrypt, or remove this restriction.
urn:ietf:params:acme:error:rateLimited
Too many requests were sent for this domain. Wait until the end of the period given in the message. For your tests, use the Let's Encrypt staging environment, whose certificates are not trusted by browsers, and remove this line afterwards:
{
acme_ca https://acme-staging-v02.api.letsencrypt.org/directory
}tlsv1 alert internal error in the browser or with curl
Caddy does not have a certificate for this name yet. Look for the cause in the logs:
sudo journalctl -u caddy --no-pager -n 100 | grep -iE 'error|acme|challenge'502 error and connect: connection refused
Caddy cannot reach the application. Check that it is running and that it listens on the address given in reverse_proxy:
curl -I http://127.0.0.1:3000
sudo ss -ltnp | grep 3000Redirect Loop
The application forces HTTPS without recognizing the X-Forwarded-Proto header. Enable the "trust proxy" option or its equivalent in the application. If the domain also goes through Cloudflare's proxy, set the SSL/TLS mode to Full (strict): the Flexible mode causes this kind of loop.
localhost:2019 and connection refused on reload
The service is stopped or the admin API has been disabled. Check its status, fix the reported error, then start it:
systemctl status caddy --no-pager
sudo systemctl start caddyopen /var/log/...: permission denied
Caddy runs as the caddy user and cannot write everywhere. Write the logs to /var/log/caddy/.