How to Set Up a Caddy Reverse Proxy on Ubuntu 24.04

A Caddy reverse proxy on Ubuntu 24.04 can put a public HTTPS domain in front of an application that listens only on localhost. The production pattern is simple: keep your application on a private listener such as 127.0.0.1:8080, let Caddy accept traffic on ports 80 and 443, and point a Caddyfile reverse_proxy directive at the local upstream.

Caddy handles several details that older reverse-proxy tutorials often configure manually. For qualifying public hostnames, automatic HTTPS obtains and renews certificates and redirects HTTP to HTTPS. The reverse_proxy handler also manages the standard X-Forwarded-For, X-Forwarded-Proto, and X-Forwarded-Host headers by default, and WebSocket upgrades work without adding Nginx-style Connection or Upgrade header rules.

This tutorial installs Caddy from its official Debian/Ubuntu repository, creates a localhost-only demo backend, validates DNS and firewall state without risking SSH lockout, configures the reverse proxy, verifies HTTPS and WebSockets behavior, enables structured access logging, tests a second upstream pattern, and includes a safe rollback path. Raff Technologies is the VM platform used by the original tutorial. The original setup was tested on Ubuntu 24.04 LTS on a Raff 1 vCPU / 2 GB RAM VM; Caddy's current installation, reverse-proxy, automatic HTTPS, and systemd guidance were re-verified on September 4, 2026.

Prerequisites:

• A Raff Linux VM running Ubuntu 24.04
• SSH access with a non-root sudo user
• A domain or subdomain whose DNS can point to the VM
• Ports 80 and 443 available for Caddy
• A backend application that can listen on localhost or a private network address

The examples use app.example.com and a demo backend on 127.0.0.1:8080. Replace them with your real hostname and application port.

Step 1 — Check DNS, existing listeners, and SSH access before changing the firewall

Confirm Ubuntu:

cat /etc/os-release

Check whether another web server already owns ports 80 or 443:

sudo ss -lntp | grep -E ':(80|443)\b' || true

Check the domain's IPv4 and IPv6 DNS records:

dig +short A app.example.com
dig +short AAAA app.example.com

If dig is unavailable:

sudo apt update
sudo apt install -y dnsutils

An A record should point to the VM's public IPv4 address. If an AAAA record exists, it must also point to working IPv6 service on this server; stale IPv6 DNS can break validation or client access even when IPv4 is correct.

If Nginx, Apache, or another reverse proxy is already serving production traffic on ports 80/443, do not stop it blindly. Plan the migration or move Caddy to a different server before continuing.

Also keep your current SSH session open while making network changes.

Verify: Ubuntu should report 24.04, the intended hostname should resolve to this VM, and you should know which process currently owns ports 80 and 443 before installing Caddy.

Step 2 — Install Caddy from the official Debian/Ubuntu repository

Install the repository prerequisites:

sudo apt update
sudo apt install -y debian-keyring debian-archive-keyring apt-transport-https curl

Add Caddy's official stable signing key:

curl -1sLf 'https://dl.cloudsmith.io/public/caddy/stable/gpg.key' | \
  sudo gpg --dearmor -o /usr/share/keyrings/caddy-stable-archive-keyring.gpg

Add the official stable repository:

curl -1sLf 'https://dl.cloudsmith.io/public/caddy/stable/debian.deb.txt' | \
  sudo tee /etc/apt/sources.list.d/caddy-stable.list

Make the APT files readable and install Caddy:

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

Caddy's official package automatically installs and starts caddy.service for Caddyfile-based configurations.

Official installation instructions: Caddy — Install.

Verify:

caddy version
systemctl is-active caddy
systemctl is-enabled caddy

The version command should return a Caddy v2 release, and the service should be active and enabled unless another process is preventing it from binding to the required ports.

Step 3 — Create a localhost-only demo backend

Install Python for a temporary test backend:

sudo apt install -y python3

Create a small document root:

sudo install -d -o root -g root -m 755 /srv/caddy-proxy-demo

Create a test page:

cat <<'EOF' | sudo tee /srv/caddy-proxy-demo/index.html > /dev/null
<!doctype html>
<html lang="en">
<head><meta charset="utf-8"><title>Caddy Reverse Proxy Test</title></head>
<body><h1>Caddy reverse proxy is working</h1></body>
</html>
EOF

Start the demo server in the foreground from a second SSH session or terminal:

python3 -m http.server 8080 \
  --bind 127.0.0.1 \
  --directory /srv/caddy-proxy-demo

Python's built-in HTTP server is only a disposable test upstream. Do not use it as the production application server.

Verify: From the VM, run curl -fsS http://127.0.0.1:8080 | grep 'Caddy reverse proxy is working'. The command should return the heading.

Step 4 — Confirm the backend is not exposed publicly

Check the listener:

sudo ss -lntp | grep ':8080'

The local address should be:

127.0.0.1:8080

not:

0.0.0.0:8080

Do not add a UFW or cloud firewall rule for port 8080 when Caddy and the application run on the same VM. The entire point of this topology is that the public client reaches Caddy, while Caddy reaches the application through loopback.

A real Node.js, FastAPI, Django, Go, or other application should follow the same principle unless it intentionally lives on another private host.

Verify: Port 8080 should listen only on 127.0.0.1, and there should be no public firewall rule exposing TCP 8080.

Step 5 — Back up the Caddyfile and configure the reverse proxy

Back up the packaged configuration:

sudo cp /etc/caddy/Caddyfile /etc/caddy/Caddyfile.bak

Replace the active configuration with the reverse-proxy site:

sudo tee /etc/caddy/Caddyfile > /dev/null <<'EOF'
app.example.com {
    reverse_proxy 127.0.0.1:8080
}
EOF

That is enough for the basic proxy. Caddy's current reverse_proxy documentation says incoming headers are passed through by default, while Caddy sets or augments X-Forwarded-For and sets X-Forwarded-Proto and X-Forwarded-Host itself.

Do not add boilerplate such as:

header_up X-Forwarded-For ...
header_up X-Forwarded-Proto ...
header_up Host ...

unless your application has a specific, documented requirement that differs from Caddy's defaults.

Verify: sudo cat /etc/caddy/Caddyfile should show your real hostname and the intended localhost upstream.

Step 6 — Format and validate the Caddyfile before reloading

Format the configuration:

sudo caddy fmt --overwrite /etc/caddy/Caddyfile

Validate it:

sudo caddy validate --config /etc/caddy/Caddyfile

caddy validate does more than parse syntax; Caddy documents that it loads and provisions modules as if starting the configuration, without actually starting it. That makes it a useful check before changing the running service.

Do not reload a configuration that fails validation.

Verify: caddy validate should complete successfully without a configuration or provisioning error.

Step 7 — Allow HTTP and HTTPS without enabling UFW blindly

Check UFW first:

sudo ufw status verbose

If UFW is already active and your SSH access is already safely allowed, add web traffic:

sudo ufw allow 80/tcp
sudo ufw allow 443/tcp

If UFW is inactive, do not run ufw enable merely because this tutorial uses Caddy. Enabling a firewall on a remote server without first validating your SSH rule can lock you out. Configure SSH deliberately first using Set Up UFW Firewall on Ubuntu 24.04, then enable it if host-level firewalling is part of your plan.

If a Raff-side security group or another cloud firewall protects the VM, allow public TCP 80 and 443 there as well.

For normal public automatic HTTPS, Caddy's documentation expects ports 80 and 443 to be externally reachable. Port 80 is also used for automatic HTTP-to-HTTPS redirects and can be used for ACME HTTP challenge validation; port 443 serves HTTPS and can be used for TLS-ALPN validation.

Verify: If UFW is active, sudo ufw status numbered should preserve your working SSH access and allow TCP 80/443. The external firewall should also permit the intended public web traffic.

Step 8 — Reload Caddy and verify automatic HTTPS

Apply the validated configuration with a graceful reload:

sudo systemctl reload caddy

Caddy recommends reloading rather than stopping the service for Caddyfile configuration changes.

Check recent logs:

sudo journalctl -u caddy -n 100 --no-pager

Test HTTPS:

curl -I https://app.example.com

Test the HTTP redirect:

curl -I http://app.example.com

For a qualifying public hostname with correct DNS and external reachability, Caddy automatically manages a publicly trusted certificate and normally redirects HTTP to HTTPS.

Verify: HTTPS should reach the demo backend successfully, HTTP should redirect to HTTPS, and the Caddy journal should not show repeating certificate, DNS, bind, or upstream errors.

Step 9 — Verify the full client → Caddy → backend path

Check the backend directly from the VM:

curl -fsS http://127.0.0.1:8080 | \
  grep 'Caddy reverse proxy is working'

Then check the same content through public HTTPS:

curl -fsS https://app.example.com | \
  grep 'Caddy reverse proxy is working'

Inspect the listeners:

sudo ss -lntp | grep -E ':(80|443|8080)\b'

The expected topology is:

Internet
   |
   | TCP 80 / 443
   v
Caddy
   |
   | 127.0.0.1:8080
   v
Application

Verify: Caddy should own the public web ports, the application should remain on localhost, and the content returned through HTTPS should match the local upstream response.

Step 10 — Use Caddy's built-in WebSocket proxying instead of manual upgrade headers

Caddy's reverse proxy supports WebSockets directly. When the client sends an HTTP upgrade request, Caddy performs the upgrade and turns the connection into a bidirectional tunnel.

For a WebSocket-capable application on port 3000, the normal configuration is still just:

ws.example.com {
    reverse_proxy 127.0.0.1:3000
}

You do not need Nginx-style boilerplate such as manually setting Connection: upgrade and Upgrade: websocket for the standard case.

One operational detail matters: Caddy documents that active WebSocket connections are closed by default when the configuration is reloaded. Applications normally reconnect, but long-lived connection workloads can consider stream_close_delay or stream_timeout after measuring their actual behavior.

Verify: For your real WebSocket application, connect through the HTTPS/WSS hostname and confirm messages flow in both directions without adding manual upgrade headers.

Step 11 — Handle reverse-proxy headers and upstream trust deliberately

When Caddy is directly internet-facing, its default forwarded-header behavior is usually the correct baseline. Caddy ignores client-supplied values for its managed X-Forwarded-* headers by default to reduce spoofing risk, then sets the forwarding information it knows itself.

If another reverse proxy or CDN sits in front of Caddy, client IP handling changes. In that architecture, configure Caddy's trusted_proxies only for the actual proxy/CDN address ranges rather than trusting arbitrary incoming forwarded headers.

Do not copy a broad trusted_proxies private_ranges or 0.0.0.0/0 rule without understanding which machine is the immediate peer.

Your application also needs to be configured to trust proxy headers only from the Caddy hop when its framework requires explicit proxy trust.

Verify: Document whether Caddy is the first public proxy. If another proxy exists in front, verify that only the known proxy address ranges are trusted for client-IP parsing.

Step 12 — Proxy to HTTPS upstreams without disabling certificate verification

If Caddy and the backend are on the same VM, loopback HTTP is often the simplest transport:

app.example.com {
    reverse_proxy 127.0.0.1:8080
}

If the upstream itself requires HTTPS and has a valid certificate, specify the HTTPS URL:

app.example.com {
    reverse_proxy https://backend.example.internal
}

Current Caddy versions automatically handle the upstream Host value needed for normal HTTPS upstream certificate verification.

Do not solve a private-certificate error by adding:

tls_insecure_skip_verify

Caddy's documentation explicitly states that this disables TLS handshake verification and is vulnerable to man-in-the-middle attacks. For an internal CA or self-signed upstream, establish trust with an appropriate tls_trust_pool and configure the correct TLS server name when necessary.

Verify: If you use an HTTPS upstream, Caddy should connect without tls_insecure_skip_verify, and the backend certificate should validate against a trusted CA or explicitly configured trust pool.

Step 13 — Add access logging and a second reverse-proxy site

Caddy's site-level log directive enables HTTP access logging. Update the Caddyfile:

app.example.com {
    log
    reverse_proxy 127.0.0.1:8080
}

api.example.com {
    log
    reverse_proxy 127.0.0.1:9000
}

Only add the second site when api.example.com actually points to this VM and a backend is listening on the configured address.

Format, validate, and reload:

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

With the packaged systemd service, Caddy's output is available through the systemd journal:

sudo journalctl -u caddy -n 100 --no-pager

Do not confuse access logs with application logs. Caddy can tell you that a request reached the proxy and what response it produced, while your upstream application still needs its own logs for application errors and business logic.

Verify: The Caddyfile should validate after adding log, requests to the configured site should appear in Caddy's logs, and every hostname should map only to an upstream that actually exists.

Step 14 — Run the final verification and roll back safely if needed

Run the complete check:

sudo caddy validate --config /etc/caddy/Caddyfile
systemctl is-active caddy
systemctl is-enabled caddy
sudo ss -lntp | grep -E ':(80|443|8080)\b'
curl -I http://app.example.com
curl -I https://app.example.com
curl -fsS https://app.example.com | \
  grep 'Caddy reverse proxy is working'
sudo journalctl -u caddy -p warning -n 50 --no-pager

The final state is healthy when Caddy is active and enabled, ports 80/443 terminate at Caddy, the backend remains private, HTTP redirects to HTTPS, the HTTPS response reaches the application, and there are no unresolved repeating errors.

To roll back the Caddyfile, first validate the saved backup:

sudo caddy validate --config /etc/caddy/Caddyfile.bak

Then restore it and reload:

sudo cp /etc/caddy/Caddyfile.bak /etc/caddy/Caddyfile
sudo systemctl reload caddy

Stop the temporary Python backend with Ctrl+C in the terminal where it is running, then remove the demo directory if it is no longer needed:

sudo rm -rf /srv/caddy-proxy-demo

Do not remove ports 80/443 from the firewall if another production web service still needs them, and do not delete /var/lib/caddy casually because it contains Caddy-managed application state including certificate data.

Verify: After rollback, sudo caddy validate --config /etc/caddy/Caddyfile should pass, Caddy should serve the intended previous configuration, and the temporary port 8080 listener should be gone.

Troubleshooting

Caddy returns 502 Bad Gateway

Test the upstream first:

curl -v http://127.0.0.1:8080
sudo ss -lntp | grep ':8080'

If the local request fails, fix the application before changing Caddy. If the application works locally, inspect Caddy's journal:

sudo journalctl -u caddy -n 120 --no-pager

HTTPS certificate issuance fails

Check both address families:

dig +short A app.example.com
dig +short AAAA app.example.com

Then confirm ports 80/443 are reachable and owned by Caddy:

sudo ss -lntp | grep -E ':(80|443)\b'
sudo ufw status numbered

A stale AAAA record, blocked port, another web server, or DNS pointed at the wrong VM can all prevent normal public validation.

Caddy fails after a configuration edit

Validate before doing anything else:

sudo caddy validate --config /etc/caddy/Caddyfile

Then inspect:

sudo journalctl -u caddy -n 100 --no-pager

Do not repeatedly restart the service while the configuration is invalid.

The backend sees the wrong client IP

First decide whether a CDN/load balancer sits in front of Caddy. If Caddy is the first public proxy, do not add broad trusted-proxy rules. If another proxy is present, configure only its actual CIDRs with Caddy's trusted_proxies settings and configure your application framework's proxy trust accordingly.

WebSockets disconnect when Caddy reloads

Caddy supports WebSockets automatically, but current documentation notes that open WebSocket streams are normally closed when a config is unloaded during reload. If this is a problem for your workload, evaluate stream_close_delay or stream_timeout and test reconnect behavior before changing production settings.

An HTTPS upstream works only with tls_insecure_skip_verify

That means certificate trust or server-name verification is not configured correctly. Do not keep the insecure option in production. Install or reference the correct CA through tls_trust_pool, use the hostname that matches the backend certificate, or use trusted private HTTP when that is appropriate for the network and threat model.

Conclusion

You now have Caddy running as a reverse proxy on Ubuntu 24.04 with a localhost-only backend, automatic HTTPS, safe firewall handling, validated Caddyfile reloads, default forwarded-header behavior, native WebSocket support, access logging, upstream TLS guidance, end-to-end checks, and rollback instructions.

The production baseline is intentionally small: reverse_proxy 127.0.0.1:PORT is often all the Caddyfile needs. Add manual headers, transport settings, health checks, or trusted proxies only when your actual topology requires them. Keeping the application off the public interface and validating every configuration before reload removes much of the unnecessary risk found in older reverse-proxy examples.

For a static Caddy site instead of a proxy, see Install Caddy Web Server on Ubuntu 24.04. For an Nginx-based edge, use Install Nginx on Ubuntu 24.04 and Secure Nginx with Let's Encrypt.

Sources

• Caddy — Install
• Caddy — Reverse proxy quick-start
• Caddy — reverse_proxy directive
• Caddy — Automatic HTTPS
• Caddy — Keep Caddy Running
• Caddy guidance verified: 2026-09-04