EN

Applications

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.

8 min read, updated on 18 November 2026

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:

Terminal
sudo apt update
sudo apt install -y bind9-dnsutils
dig +short A app.your-domain.com
dig +short AAAA app.your-domain.com

The 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:

Terminal
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 caddy

The package creates the caddy system user and starts the service of the same name. Check the installation:

Terminal
caddy version
systemctl status caddy --no-pager

Step 3: Open the Firewall

If you use UFW, allow the web ports:

Terminal
sudo ufw allow 80/tcp
sudo ufw allow 443/tcp
sudo ufw allow 443/udp
sudo ufw status

Check that the application responds locally:

Terminal
curl -I http://127.0.0.1:3000

If 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:

Terminal
sudo cp /etc/caddy/Caddyfile /etc/caddy/Caddyfile.orig
sudo nano /etc/caddy/Caddyfile

Replace its contents with:

caddyfile
{
	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

Terminal
sudo caddy fmt --overwrite /etc/caddy/Caddyfile
sudo -u caddy caddy validate --config /etc/caddy/Caddyfile --adapter caddyfile
sudo systemctl reload caddy

Reloading 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:

Terminal
sudo journalctl -u caddy --no-pager -n 50
curl -I http://app.your-domain.com
curl -I https://app.your-domain.com

The 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:

Terminal
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 caddy

Port 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:

Terminal
sudo mkdir -p /etc/caddy/sites
sudo nano /etc/caddy/sites/app.caddy

Put the site block in /etc/caddy/sites/app.caddy:

caddyfile
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:

caddyfile
{
	email admin@your-domain.com
}

import sites/*.caddy

Validate 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:

Terminal
caddy hash-password

Then add this site, replacing BCRYPT_HASH with the hash you obtained:

caddyfile
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

caddyfile
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

caddyfile
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

caddyfile
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.

caddyfile
{
	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:

Terminal
sudo apt update
sudo apt install --only-upgrade caddy
caddy version
systemctl status caddy --no-pager

Do 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
Terminal
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.gz

This 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:

Terminal
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 caddy

Troubleshooting

listen tcp :80: bind: address already in use

Another service is using port 80 or 443:

Terminal
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:

caddyfile
{
	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:

Terminal
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:

Terminal
curl -I http://127.0.0.1:3000
sudo ss -ltnp | grep 3000

Redirect 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:

Terminal
systemctl status caddy --no-pager
sudo systemctl start caddy

open /var/log/...: permission denied

Caddy runs as the caddy user and cannot write everywhere. Write the logs to /var/log/caddy/.

References