Skip to main content

Web servers and networking · Intermediate · 11 min

How to Serve a Site with Automatic HTTPS Using Caddy 2

By Padding · Updated 15 Nov 2026
Ubuntu 26.04.1 LTS · Caddy 2.11

You will install Caddy 2.11, serve a folder with a three-line Caddyfile, see it use HTTPS and redirect HTTP without extra setup, and learn what changes when the site has a real domain.

On this page

Caddy is a web server that gets and renews HTTPS certificates by itself. For a public domain name you write the name in its configuration file, and Caddy asks a certificate authority for a certificate, installs it, redirects HTTP to HTTPS and renews it before it expires. Nothing else is needed.

In this tutorial you will install Caddy 2.11 from its official apt repository, write a Caddyfile that serves a folder, see HTTPS and the redirect work, add a reverse proxy, and learn how the same file works on a real domain. You test with the name localhost first, because Caddy then issues a certificate from its own local certificate authority. That lets you see the whole behaviour without owning a domain.

Step 1 · Install Caddy

Install the packages the repository setup needs, add Caddy's signing key and repository, then install caddy.

Bash
sudo apt-get update
sudo apt-get install -y debian-keyring debian-archive-keyring apt-transport-https curl gnupg ca-certificates
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 /etc/apt/sources.list.d/caddy-stable.list
sudo apt-get update
sudo apt-get install -y caddy

The two chmod lines make sure apt can read the key and the list. The Caddy project's instructions use them for the same reason.

Check it worked

Bash
caddy version
getent passwd caddy

The first prints v2.11.9 or a later 2.11 release, followed by a hash. The second shows the caddy system user that the service runs as.

The package also installs a caddy systemd service, reads /etc/caddy/Caddyfile, and starts at boot. Confirm that it runs:

Bash
systemctl status caddy

You want Active: active (running). Use sudo systemctl reload caddy whenever you change the Caddyfile.

Step 2 · Serve a folder

Make a folder with a page in it:

Bash
sudo mkdir -p /var/www/demo
echo '<h1>Hello from Caddy</h1>' | sudo tee /var/www/demo/index.html

Replace the sample Caddyfile with a minimal one. A Caddyfile is a list of site addresses, each followed by a block of directives.

Bash
sudo tee /etc/caddy/Caddyfile > /dev/null <<'CADDY'
localhost {
	root * /var/www/demo
	file_server
}
CADDY
  • localhost is the site address. For a public site, this is your domain name.
  • root * /var/www/demo sets the folder to serve for every path (*).
  • file_server turns on static file serving.

Check the file before you use it:

Bash
caddy validate --config /etc/caddy/Caddyfile --adapter caddyfile

The output ends with Valid configuration. Caddyfiles use tabs for indentation, and caddy fmt --overwrite /etc/caddy/Caddyfile fixes the spacing for you.

Step 3 · Start Caddy and look at the result

The package started Caddy with its sample configuration. Tell the running service to read your new Caddyfile:

Bash
sudo systemctl reload caddy

Caddy spends the first moments creating a local certificate authority and a certificate for localhost. Then request the page over HTTPS. The -k flag tells curl to accept the certificate even though your computer does not trust Caddy's local authority:

Bash
curl -sk https://localhost/
curl -skI https://localhost/ | head -n 1

You get <h1>Hello from Caddy</h1> and HTTP/2 200. Now ask over plain HTTP:

Bash
curl -sI http://localhost/ | head -n 4

The response is HTTP/1.1 308 Permanent Redirect with Location: https://localhost/. Caddy redirects every HTTP request to HTTPS by itself, and you wrote no rule for it.

Check it worked

You saw three things from three lines of configuration: a page served over HTTPS, HTTP/2 negotiated, and a redirect from HTTP. On your laptop, sudo caddy trust adds Caddy's local authority to the system trust store, so a browser shows a padlock for https://localhost without a warning. The local authority is for testing. It cannot give you a certificate that other people's browsers will trust.

Troubleshooting

  • could not start: address already in use: another web server holds port 80 or 443. Stop Nginx or Apache (sudo systemctl stop nginx), or find the process with sudo ss -ltnp 'sport = :443'.
  • Caddyfile input is not formatted appears as a warning: harmless, but run caddy fmt --overwrite to clean it.
  • Read the log: journalctl -u caddy --no-pager | tail -n 50.

Step 4 · Change the config and reload without downtime

Edit the Caddyfile to add a reverse proxy for a path. This sends everything under /api/ to an app on local port 3000 and still serves files for the rest:

Bash
sudo tee /etc/caddy/Caddyfile > /dev/null <<'CADDY'
localhost {
	root * /var/www/demo

	handle /api/* {
		reverse_proxy 127.0.0.1:3000
	}

	handle {
		file_server
	}
}
CADDY
sudo caddy validate --config /etc/caddy/Caddyfile --adapter caddyfile

handle blocks are tried in order and the first match wins, so /api/* goes to the app and everything else to the file server. To send the whole site to an app, use a single reverse_proxy 127.0.0.1:3000 line. Caddy sets the X-Forwarded-For, X-Forwarded-Proto and X-Forwarded-Host headers for you, so no header lines are needed.

Apply the change. A reload replaces the running configuration without dropping connections.

Bash
sudo systemctl reload caddy
Bash
curl -sk https://localhost/
curl -sk -o /dev/null -w '%{http_code}\n' https://localhost/api/ping

The page still loads. The /api/ping request returns 502, because nothing listens on port 3000 yet, which shows the request was passed to the proxy.

Step 5 · Use a real domain

With a public domain, nothing in the Caddyfile changes except the address.

  1. Create an A record (and an AAAA record if the server has IPv6) for example.com that points at your server's public IP address. Check it with dig +short example.com.
  2. Open ports 80 and 443 in the server firewall (sudo ufw allow 80/tcp and sudo ufw allow 443/tcp) and in your provider's firewall. Caddy needs port 80 for the HTTP challenge and port 443 to serve.
  3. Create the folder and a page for the site:
Bash
sudo mkdir -p /var/www/example.com
echo '<h1>Hello from example.com</h1>' | sudo tee /var/www/example.com/index.html
  1. Replace localhost with the domain in /etc/caddy/Caddyfile:
Text
example.com {
	root * /var/www/example.com
	file_server
}
  1. Reload:
Bash
sudo systemctl reload caddy

On the first request, Caddy obtains a certificate from a public certificate authority (Let's Encrypt or ZeroSSL), then stores it, with its other state, in /var/lib/caddy/.local/share/caddy (the home folder of the caddy service user) and renews it as needed. Check the log:

Bash
journalctl -u caddy --no-pager | grep -i certificate

Add www.example.com to the same site line to cover both names: example.com, www.example.com {. Contact details for expiry notices are optional; set them in a global options block at the top of the Caddyfile, with email you@example.com inside { }.

If the certificate fails, the log names the reason. The usual causes are a DNS record that has not spread yet, port 80 blocked, or another program holding ports 80 and 443. Fix the cause and reload. Caddy retries by itself with increasing delays.

Next steps

  • The same job with Nginx and Certbot: /tutorials/free-https-with-lets-encrypt-and-nginx.
  • Read the DNS records you set for the domain in /tutorials/dns-records-explained-a-cname-mx-txt.
  • Caddy's Caddyfile reference and automatic HTTPS pages: caddyserver.com/docs.

Need this done for you?

Padding does this work for growing companies, from the first diagnosis to a system that keeps working.

Platform Engineering

Get new tutorials

New tutorials, about twice a month.