How to Install and Use Caddy on Ubuntu 26.04 and 24.04

Share

To install Caddy on Ubuntu 26.04 or 24.04, add Caddy’s official stable APT repository and install the caddy package. Caddy is a web server that can serve files, renew HTTPS certificates and forward requests to a local app.

Serve a test page first, then put it online with HTTPS or try a reverse proxy without buying a domain. If you get stuck, leave a comment with the error or contact us.

Before you begin
  • Use Ubuntu 26.04 LTS or 24.04 LTS with systemd, internet access and a sudo account.
  • Use a fresh host for these examples. Back up an existing Caddyfile and check for active sites before changing it.
  • The local examples need no domain. Public HTTPS needs a hostname you control and a server reachable from the internet.

1. Install Caddy with APT

Step 1. Check ports 80 and 443

A normal fresh package installation immediately enables and starts caddy.service. Before installing, check for existing listeners:

Ubuntu terminal
sudo ss -ltnup | grep -E ':80|:443'

No output is normal. The quick filter can also match ports such as 8080. Read the Local Address:Port column for exact matches on 80 or 443. If a service owns either port, plan the handoff before changing anything.

Ubuntu 24.04 LTS and 26.04 LTS both package Caddy 2.6.2 in universe, with different Ubuntu package revisions. Caddy’s stable Cloudsmith APT repository provides 2.11.x, including 2.11.9. Choose one route.

Step 2. Install the repository tools

For the official Caddy package, install the prerequisites on either release:

Ubuntu terminal
sudo apt update &&
sudo apt install --yes debian-keyring debian-archive-keyring apt-transport-https curl gnupg

The gnupg package provides the gpg command.

Step 3. Add the official stable repository

Run these lines in Bash. Review any existing Caddy source and keyring before replacing them.

Ubuntu terminal
set -o pipefail
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

The chmod commands keep both files readable to APT, including its _apt sandbox user, on systems with restrictive umask settings. Fix download or signature errors before continuing.

Step 4. Install from the chosen source

Run the policy check first. The upstream candidate should come from dl.cloudsmith.io. Expect 2.11.9 or a later stable release.

Ubuntu terminal
apt-cache policy caddy
Ubuntu terminal
sudo apt install caddy
Alternative. Install the Ubuntu package

If you prefer Ubuntu’s package, skip the Cloudsmith setup and use the following commands on a fresh host:

Ubuntu terminal
sudo apt update &&
sudo apt install curl caddy

If APT cannot find Caddy because Universe is disabled, install the repository helper, enable Universe, then retry:

Ubuntu terminal
sudo apt install software-properties-common &&
sudo add-apt-repository universe &&
sudo apt update &&
sudo apt install curl caddy
Step 5. Verify the service

Check the installed binary and service:

Ubuntu terminal
caddy version
systemctl is-active caddy
systemctl is-enabled caddy

Expect active and enabled on a fresh systemd host. If either check fails, look at the journal before moving on.

2. Serve a Static Site Locally

Step 1. Create a test page

Use a fresh directory. Choose another path throughout if this one already holds a site.

Ubuntu terminal
sudo install -d -m 0755 /var/www/caddy-demo &&
printf '%s\n' '<!doctype html><title>Caddy test</title><h1>Hello from Caddy</h1>' | sudo tee /var/www/caddy-demo/index.html &&
sudo chmod 0644 /var/www/caddy-demo/index.html &&
sudo -u caddy test -r /var/www/caddy-demo/index.html && echo 'Caddy can read the page'

Caddy runs as the caddy user. It needs traversal permission on every parent directory and read access to the file. If the last line prints nothing, check the path and permissions.

Step 2. Set the web root

Back up the original Caddyfile. If the backup already exists, keep it and confirm what it contains before editing.

Ubuntu terminal
sudo cp --no-clobber /etc/caddy/Caddyfile /etc/caddy/Caddyfile.before-demo
Ubuntu terminal
sudoedit /etc/caddy/Caddyfile

On a fresh install, replace the packaged sample with this block. The :80 address serves HTTP. The bind line keeps the demo on this machine.

Caddyfile
:80 {
    bind 127.0.0.1
    root * /var/www/caddy-demo
    file_server
}
Step 3. Validate and reload

Format the file and apply it only if validation passes:

Ubuntu terminal
sudo caddy fmt --overwrite /etc/caddy/Caddyfile &&
sudo caddy validate --config /etc/caddy/Caddyfile &&
sudo systemctl reload caddy

A valid file can still fail to load when its port is busy. Check the journal if reload fails.

Step 4. Request the page

From the Ubuntu host, run:

Ubuntu terminal
curl -fsS http://127.0.0.1/

Expect HTML containing Hello from Caddy.

3. Put the Site Online with HTTPS

Step 1. Point DNS at your server

Create an A record for your public IPv4 address. Add an AAAA record only if the server is reachable at that IPv6 address. Replace site.example.com throughout with your hostname.

Ubuntu terminal
resolvectl query site.example.com

The answer should include your server’s public address. Correct any stale AAAA record before continuing. If resolvectl is unavailable, install dnsutils and use dig +short for both A and AAAA records.

Step 2. Allow web traffic

If UFW is active, allow these ports. TCP 80 serves HTTP redirects and can be used for certificate validation. TCP 443 serves HTTPS. UDP 443 enables HTTP/3 over QUIC.

Ubuntu terminal
sudo ufw status verbose
sudo ufw allow 80/tcp
sudo ufw allow 443/tcp
sudo ufw allow 443/udp

Allow the same traffic through any cloud firewall or router. If UFW is inactive, adding rules leaves it inactive. Check that your SSH port is allowed before enabling a firewall remotely. TCP HTTPS still works without UDP 443.

Step 3. Switch to your domain

Open /etc/caddy/Caddyfile with sudoedit and replace the static block below, using your own hostname. Without the loopback bind, the site can accept external connections.

Caddyfile
site.example.com {
    root * /var/www/caddy-demo
    file_server
}
Ubuntu terminal
sudo caddy fmt --overwrite /etc/caddy/Caddyfile &&
sudo caddy validate --config /etc/caddy/Caddyfile &&
sudo systemctl reload caddy

Caddy automatically requests and renews a trusted certificate for a qualifying public name. Initial issuance can take a moment.

Step 4. Check HTTP and HTTPS

From another device or network, verify both responses:

Ubuntu terminal
curl -I http://site.example.com/
curl -I https://site.example.com/

The HTTP request should return 308 Permanent Redirect with an HTTPS Location header. The HTTPS request should return 200 and pass certificate verification. curl may print HTTP/1.1 or HTTP/2. Testing HTTP/3 itself requires a QUIC-capable client.

4. Reverse Proxy a Local App

A reverse proxy takes a request from the browser and passes it to an application. Use a separate loopback-only site on port 8081 so your static site can stay up while you test.

Step 1. Start a local backend

Check that 8080 and 8081 are free. In a second terminal on the Ubuntu host, start Python’s built-in test server. Install the Ubuntu python3 package first if it is missing. This example needs no pip packages.

Ubuntu terminal
python3 -m http.server 8080 --bind 127.0.0.1 --directory /var/www/caddy-demo

Leave this terminal open. Python serves the demo folder on the local machine only.

Step 2. Add a proxy site block

Append this block to /etc/caddy/Caddyfile using sudoedit. Keep your static site block.

Caddyfile
:8081 {
    bind 127.0.0.1
    reverse_proxy 127.0.0.1:8080
}
Ubuntu terminal
sudo caddy fmt --overwrite /etc/caddy/Caddyfile &&
sudo caddy validate --config /etc/caddy/Caddyfile &&
sudo systemctl reload caddy

Caddy accepts requests on local port 8081 and forwards them to Python on 8080. Neither demo port needs a public firewall rule.

Step 3. Check the backend and proxy

From another terminal on the Ubuntu host, request the backend directly and through Caddy:

Ubuntu terminal
curl -i http://127.0.0.1:8080/
curl -i http://127.0.0.1:8081/

Both should return 200 and the same page.

Step 4. Diagnose a 502

Press Ctrl+C in the Python terminal to stop the test backend. In your other terminal, repeat the requests and read the journal:

Ubuntu terminal
curl -i http://127.0.0.1:8081/
curl -i http://127.0.0.1:8080/
sudo journalctl -u caddy -n 30 --no-pager

Caddy should return 502, the direct request should fail to connect, and the journal should show a connection refusal for 127.0.0.1:8080. Restart Python to confirm recovery. When done, stop Python, remove the 8081 block, then validate and reload.

For an app running in Bun, Deno, ASP.NET Core or Go, use the port the app actually listens on. For Podman, publish the container’s app port on host loopback and point the host’s Caddy service at that published port. To make the app public, use your actual hostname in a site block with reverse_proxy in place of the static file directives for that hostname.

5. Troubleshoot Caddy

The service fails to start or reload

Check the listening ports and Caddy’s service logs:

Ubuntu terminal
sudo ss -ltnup | grep -E ':80|:443'
sudo journalctl -u caddy -n 50 --no-pager

If another process owns the port, identify what it serves before moving it. For a configuration error, fix the reported line or restore the known-good Caddyfile, then validate and reload.

The page or certificate fails

For a missing or forbidden file, check the web root and verify that the caddy user can traverse the parent directories and read the file. For HTTPS, check DNS and verify that TCP ports 80 and 443 reach the server from outside its network. Read the journal for the certificate error before retrying.

6. Update or Remove Caddy

Update through APT

Review the candidate before upgrading. A package update can restart the service, so schedule it for a time when a brief interruption is acceptable.

Ubuntu terminal
sudo apt update && apt-cache policy caddy

After confirming the version and source, run the upgrade and check the service:

Ubuntu terminal
sudo apt install --only-upgrade caddy &&
caddy version &&
systemctl is-active caddy
Remove or purge the package

Both operations take Caddy’s sites offline. If you are reinstalling, back up /etc/caddy and /var/lib/caddy privately and use the regular remove command:

Ubuntu terminal
sudo apt remove caddy

With the default systemd service, managed TLS certificates and private keys live under /var/lib/caddy/.local/share/caddy. The verified Cloudsmith 2.11.9 package deletes /etc/caddy, /var/log/caddy and /var/lib/caddy on sudo apt purge caddy. Running sudo rm -rf /var/lib/caddy separately would also erase that certificate storage. Keep the storage for a reinstall to avoid unnecessary reissuance and reduce the chance of hitting Let’s Encrypt rate limits. Ubuntu archive packages can have different cleanup scripts.

Remove the Cloudsmith source when retiring it

If you added this source and no longer need it, remove its dedicated source list and key:

Ubuntu terminal
sudo rm -f /etc/apt/sources.list.d/caddy-stable.list /usr/share/keyrings/caddy-stable-archive-keyring.gpg
sudo apt update

Your test page under /var/www is separate. Remove firewall rules only if no other service needs them.

Frequently Asked Questions

Can I use Caddy without a domain?

Yes. Use an HTTP site address such as :80 and bind to 127.0.0.1 for a local test. Use a public hostname you control for the public HTTPS setup in this guide.

Does UDP port 443 have to be open for HTTPS?

UDP port 443 enables HTTP/3. HTTPS over HTTP/1.1 or HTTP/2 uses TCP port 443.

Why does Caddy return 502 Bad Gateway?

Caddy could not get a usable response from the backend. Request the backend directly from the Caddy host, then check the Caddy journal for details such as a connection refusal or timeout.

Official reference: Install Caddy

Related Ubuntu guides · Test web requests with curl · Install Go · Run containers with Podman