If you already run apps with Docker on a VPS, you're probably familiar with addresses like http://SERVER-IP:8080. That's fine for a quick test. But for real use? The address is hard to remember, the browser shows a "Not Secure" warning, and every new app means one more port exposed to the internet.
What we actually want is a clean address like https://blog.example.com, complete with the HTTPS padlock. The classic approach is to install Nginx, write a server block for each app, and then manage SSL certificates with Certbot. It works, but it takes quite a few steps, and you have to repeat them for every new app.
This is where Caddy comes in. Caddy is a web server that handles HTTPS certificates automatically: write the domain name and the proxy target in two or three lines, and Caddy takes care of the rest.
In this article, we'll walk through setting up Caddy as a reverse proxy with Docker Compose, from what a reverse proxy is, preparing DNS and a Docker network, and writing the Caddyfile, to adding apps from other Compose projects and fixing the most common problems. Let's get started!
What is a Reverse Proxy?
A reverse proxy is a server that sits in front of your apps, receives every request from the internet, and forwards each one to the right app behind it.
Picture an office building with a single receptionist in the lobby. Visitors don't need to know which room to go to. They just say the company name, and the receptionist sends them to the right place. A reverse proxy works the same way: the visitor asks for a domain name, and the reverse proxy forwards the request to the matching container.
A reverse proxy gives you several things at once:
- A single entry point: only ports
80and443are open to the internet, no matter how many apps you run. - HTTPS in one place: SSL certificates are handled by the reverse proxy, so the apps behind it don't need to know anything about HTTPS.
- Many domains on one server:
blog.example.com,status.example.com, andapp.example.comcan all live on the same VPS.
What is Caddy?
Caddy is an open source web server written in Go and released under the Apache 2.0 license. The feature it's best known for is Automatic HTTPS: Caddy requests a certificate from a public certificate authority such as Let's Encrypt, installs it, and renews it before it expires, with no Certbot and no cron job.
At the time of writing, the stable version of Caddy is in the 2.11 series. Its configuration lives in a file called the Caddyfile, whose format is far more compact than an Nginx config. To give you an idea, here is a complete reverse proxy configuration with HTTPS for one domain:
blog.example.com {
reverse_proxy wordpress:80
}Just three lines. Pretty neat, right?
Why Choose Caddy as a Reverse Proxy?
Here are a few reasons Caddy is a great fit for self-hosting on a VPS:
- Automatic HTTPS: certificates are requested, installed, and renewed for you. According to the Automatic HTTPS documentation, if Let's Encrypt fails, Caddy even tries another CA (ZeroSSL) on its own.
- Built-in HTTP to HTTPS redirect: visitors who open
http://are redirected tohttps://with no extra configuration. - Compact configuration: one app takes three lines in the
Caddyfile. - Correct proxy headers out of the box: the
reverse_proxydirective automatically sends theX-Forwarded-For,X-Forwarded-Proto, andX-Forwarded-Hostheaders to your app, and supports WebSocket connections with no special settings. - HTTP/3 enabled by default: just open port
443/udp. - Zero-downtime reloads: configuration changes are applied without dropping active connections.
Downsides of Caddy
To be fair, Caddy has some limitations too:
- A smaller community and fewer tutorials than Nginx: for unusual cases, example configurations are harder to find.
- Extra features need a custom build: some features, such as the DNS challenge for wildcard certificates, come as plugins that you have to build into Caddy yourself.
- No automatic container discovery: unlike Traefik, which reads Docker labels, with standard Caddy every new app still has to be added to the
Caddyfile.
Here is a quick comparison with other popular options:
| Caddy | Nginx + Certbot | Traefik | Nginx Proxy Manager | |
|---|---|---|---|---|
| HTTPS certificates | ✅ Automatic, built in | ⚠️ Through Certbot | ✅ Automatic, needs configuring | ✅ Through the web interface |
| How you configure it | A single Caddyfile |
A config file per site | Labels on each container | Web interface |
| Best for | Beginners to intermediate users | Those who need full control | Many containers that change often | Those who avoid the terminal |
If you prefer the classic approach without Docker, the Nginx and Certbot guide is in How to Deploy Next.js to a VPS with PM2 and Nginx.
Preparation
Before we begin, make sure you have:
- A VPS running Ubuntu 24.04 LTS or 26.04 LTS with a public IP address. The commands in this article are written for those two versions.
- Docker Engine and the Docker Compose plugin already installed. If not, follow Learn Docker Compose first.
- A domain name whose DNS you can manage.
- Ports 80 and 443 free on the VPS. If you previously installed Nginx or Apache directly on the server, that service has to be stopped first.
To check whether ports 80 and 443 are in use, run the following command:
sudo ss -tlnp | grep -E ':(80|443)\s'If there is no output at all, both ports are free and ready for Caddy.
In the examples below, we'll use the IP address 203.0.113.10 and the domains whoami.example.com and blog.example.com. Replace them with your own IP and domains.
How to Set Up Caddy as a Reverse Proxy with Docker Compose
Here is the layout we're going to build: Caddy runs as a single container that publishes ports 80 and 443. The other apps don't publish any ports to the internet. They simply join a shared Docker network called proxy, and Caddy reaches them by container name.
Step #1: Point Your Domain to the VPS IP
Open the DNS panel where your domain is managed, then create an A record for each subdomain you plan to use:
| Type | Name | Value |
|---|---|---|
| A | whoami |
203.0.113.10 |
| A | blog |
203.0.113.10 |
This has to be done before you start Caddy, because Let's Encrypt checks that the domain really points to your server.
To confirm that DNS is live, check it with the dig command below. If the command isn't available, install it first with sudo apt install bind9-dnsutils -y.
dig +short whoami.example.comIf the output shows your VPS IP address, DNS is ready. If it's still empty, wait a few minutes and try again.
Note: if you use Cloudflare, set these records to DNS only (grey cloud) for now, so that requests from Let's Encrypt reach Caddy directly.
Step #2: Open Ports 80 and 443
Caddy needs ports 80 and 443 to be reachable from the internet, both for certificate validation and for serving visitors. If you use UFW as described in How to Secure a New Linux VPS, allow those ports with the following commands:
sudo ufw allow 80/tcp
sudo ufw allow 443/tcp
sudo ufw allow 443/udpPort 443/udp is used by HTTP/3. It's optional, but it would be a shame to leave it closed since HTTP/3 is enabled by default in Caddy.
Important: many VPS providers have their own firewall in their dashboard (often called a security group or cloud firewall). Make sure ports 80 and 443 are allowed there as well.
Step #3: Create a Shared Docker Network
By default, every Compose project gets its own isolated network. So that Caddy can reach apps from other projects, we create one shared network with the following command:
docker network create proxyYou only need to create this network once. From now on, any app you want Caddy to serve just joins the proxy network.
Step #4: Write the compose.yaml File for Caddy
Create a project folder for Caddy, including a conf subfolder to hold the Caddyfile:
mkdir -p ~/apps/caddy/conf
cd ~/apps/caddyThen create the Compose file:
nano compose.yamlPaste in the following configuration:
services:
caddy:
image: caddy:2
restart: unless-stopped
ports:
- "80:80"
- "443:443"
- "443:443/udp"
volumes:
- ./conf:/etc/caddy
- caddy_data:/data
- caddy_config:/config
networks:
- proxy
whoami:
image: traefik/whoami
restart: unless-stopped
networks:
- proxy
volumes:
caddy_data:
caddy_config:
networks:
proxy:
external: trueSave the file by pressing Ctrl+X, then Y, and Enter. A few things in this file are worth pointing out:
image: caddy:2: uses the latest official Caddy 2 image. For a production server, you can pin a minor version instead, for examplecaddy:2.11../conf:/etc/caddy: we mount a folder, not theCaddyfileitself. According to the Caddy image documentation, editors likevimchange the file's inode when saving, so changes to a directly mounted file aren't seen by the container until it is recreated.caddy_data:/data: this is where Caddy stores certificates and private keys. This volume must be persistent. If it's lost, Caddy has to request every certificate again and you may run into Let's Encrypt's rate limits.whoami: a tiny app from thetraefik/whoamiimage that prints information about the HTTP request it receives. We use it as a test app. Notice that this service has noportssection, so it can only be reached through Caddy.external: true: tells Compose that theproxynetwork already exists (created in step #3) and doesn't need to be created again.
Step #5: Write the Caddyfile
Now create the Caddy configuration file:
nano conf/CaddyfileAdd the following configuration, replacing the email address and the domain:
{
email [email protected]
}
whoami.example.com {
reverse_proxy whoami:80
}A quick explanation:
- The unnamed block at the top holds the global options. It has to be the first block in the
Caddyfile. Theemailoption is used when creating your account with the CA, and setting it is strongly recommended so you can be contacted if there's a problem with your certificates. whoami.example.com { … }is a site block. Because the address is a public domain name, Caddy automatically enables HTTPS for it.reverse_proxy whoami:80forwards every request to thewhoamicontainer on port 80. The namewhoamihere is the service name fromcompose.yaml, which resolves thanks to theproxynetwork.
Tip: while you're still experimenting, add the line
acme_ca https://acme-staging-v02.api.letsencrypt.org/directoryinside the global options block. Caddy will then use Let's Encrypt's staging server, which has much higher limits. Staging certificates aren't trusted by browsers, so remove that line and reload once everything works.
Step #6: Start Caddy and Test HTTPS
Start Caddy and the test app in the background with the following command:
docker compose up -dAs soon as it starts, Caddy requests a certificate for the domain in the Caddyfile. This usually takes only a few seconds. Follow the progress in the logs:
docker compose logs caddy | grep -i "certificate obtained"If you see a line containing certificate obtained successfully along with your domain name, the certificate is in place. Now test it from any computer with the following command:
curl https://whoami.example.comThe output looks roughly like this:
Hostname: 3f2a9c1b7d4e
IP: 127.0.0.1
IP: 172.18.0.3
RemoteAddr: 172.18.0.2:41234
GET / HTTP/1.1
Host: whoami.example.com
User-Agent: curl/8.5.0
Accept: */*
Accept-Encoding: gzip
X-Forwarded-For: 198.51.100.25
X-Forwarded-Host: whoami.example.com
X-Forwarded-Proto: httpsLook at the last three lines. Those are the headers Caddy adds automatically, so the app behind it still knows the visitor's real IP address and knows the connection is using HTTPS. Also try opening http://whoami.example.com in a browser, and you'll be redirected straight to the https:// version. Done!
Adding Apps from Other Compose Projects
The test app is running. Now the question is: what about real apps that live in other Compose projects? As an example, we'll connect the WordPress setup from Learn Docker Compose to Caddy.
Step #1: Connect the App to the proxy Network
Open the compose.yaml of the WordPress project, change the wordpress service, and add a networks section at the very bottom. The example below only shows what changes. Don't delete the other existing lines (the database variables, depends_on, volumes, and the db service):
services:
wordpress:
image: wordpress:latest
restart: unless-stopped
environment:
WORDPRESS_CONFIG_EXTRA: |
define('WP_HOME', 'https://blog.example.com');
define('WP_SITEURL', 'https://blog.example.com');
networks:
- default
- proxy
networks:
proxy:
external: trueThere are three changes to note:
- The
portssection is removed: WordPress no longer needs to publish port8080, because all access now goes through Caddy. networkslists bothdefaultandproxy: once you writenetworksexplicitly, the service no longer joins thedefaultnetwork automatically. Without thedefaultline, WordPress can't reach thedbdatabase anymore. Thedbservice itself does not need to join theproxynetwork.WORDPRESS_CONFIG_EXTRA: WordPress stores its site address in the database. If WordPress was originally installed throughhttp://SERVER-IP:8080, these two lines force it to use the new domain. This variable is supported by the official WordPress image.
Apply the change from the WordPress project folder with the following command:
docker compose up -dStep #2: Add a Site Block to the Caddyfile
Go back to the ~/apps/caddy folder, open conf/Caddyfile, and add a new block at the bottom:
blog.example.com {
reverse_proxy wordpress:80
}Before applying it, check for mistakes with the following command:
docker compose exec -w /etc/caddy caddy caddy validateIf the last line of the output is Valid configuration, the configuration is safe to apply.
Step #3: Reload Caddy with Zero Downtime
Apply the new configuration with the following reload command:
docker compose exec -w /etc/caddy caddy caddy reloadYes, caddy appears twice: the first is the service name in Compose, the second is the caddy command inside the container. The -w /etc/caddy option runs the command from the folder that holds the Caddyfile, so Caddy finds it right away.
Caddy will request a certificate for blog.example.com, and within a few seconds your WordPress site is available at https://blog.example.com. The other sites being served aren't interrupted at all.
For the next app, the pattern is always the same: create an A record, connect the container to the proxy network, add three lines to the Caddyfile, and reload.
Note: service names must be unique within the
proxynetwork. If two projects both have a service namedapp, Caddy may be routed to the wrong container. Give services specific names (such aswordpressoruptime-kuma), or use the full container name likewordpress-compose-wordpress-1.
Caddyfile Configuration Tips
Tip #1: Protect an App with Basic Auth
Some internal apps don't have a login page of their own. You can add a password layer in Caddy with the basic_auth directive. First, generate a password hash with the following command and type your password when prompted:
docker compose exec caddy caddy hash-passwordCopy the resulting hash (it starts with $2a$) and use it in the site block like this:
whoami.example.com {
basic_auth {
budi $2a$14$REPLACE-WITH-YOUR-HASH
}
reverse_proxy whoami:80
}Caddy doesn't accept plaintext passwords, so the hashing step above is required.
Note: in older tutorials, this directive is written
basicauth(no underscore). It was renamed tobasic_authin Caddy v2.8.0.
Tip #2: Enable Compression
To deliver pages faster, enable compression by adding a single encode line to the site block:
blog.example.com {
encode zstd gzip
reverse_proxy wordpress:80
}Tip #3: Redirect www to the Main Domain
If you want www.example.com to redirect to example.com automatically, add a separate block with the redir directive:
www.example.com {
redir https://example.com{uri} permanent
}Don't forget to create an A record for www too, because Caddy still needs a certificate for that domain.
Tip #4: Tidy Up the Caddyfile with caddy fmt
If the Caddy logs show the warning Caddyfile input is not formatted, it isn't an error. Caddy is just suggesting its standard formatting. Fix it automatically with the following command:
docker compose exec -w /etc/caddy caddy caddy fmt --overwriteTroubleshooting: Common Problems
The Certificate Fails to Issue
This is the most common problem. Look at the error message in the logs with the following command:
docker compose logs --tail 50 caddyCommon causes:
- DNS doesn't point to the VPS yet: check again with
dig +short. - A wrong AAAA (IPv6) record: if the domain has an AAAA record that doesn't point to your VPS, validation can fail even though the A record is correct. Delete or fix that record.
- Port 80 or 443 is closed: check UFW and the firewall in your VPS provider's dashboard.
- The Cloudflare proxy is still on: switch to DNS only first.
Don't keep restarting Caddy while the certificate is failing. According to the Let's Encrypt rate limit documentation, at the time of writing the limits are 5 failed validations per domain per hour and 5 certificates for the same set of domains per 7 days. Fix the cause first, or use the staging server as described in the tip in step #5.
You Get 502 Bad Gateway
This means Caddy is running but can't reach the app behind it. Check these three things:
- The app's container is actually running (
docker compose psin its project folder). - The container has joined the
proxynetwork. Check withdocker network inspect proxy. - The service name and the internal port in
reverse_proxyare correct. Use the port inside the container (for example80), not the port that used to be published on the host (for example8080).
reverse_proxy to localhost Doesn't Work
Inside a container, localhost means the Caddy container itself, not your VPS. So reverse_proxy localhost:3000 won't find an app running directly on the host.
The easiest fix is to run the app as a container on the proxy network. If the app has to stay on the host, add the following lines to the caddy service in compose.yaml, then use reverse_proxy host.docker.internal:3000:
extra_hosts:
- "host.docker.internal:host-gateway"Keep in mind that the app on the host must accept connections from the Docker network (not only from 127.0.0.1), and the firewall has to allow it. For apps that run entirely on the host, a reverse proxy installed directly on the host is usually simpler.
Port 80 or 443 Is Already in Use
If docker compose up -d fails with the message address already in use, another service is using that port, usually Nginx or Apache. Find it with the ss command from the Preparation section, then stop that service, for example with sudo systemctl disable --now nginx.
Conclusion
From this article, we can conclude that Caddy is one of the easiest ways to put a reverse proxy with HTTPS in front of your Docker apps. All it takes is one container, one shared network, and three lines of Caddyfile per app. Certificates, renewals, and the redirect to HTTPS are all handled by Caddy itself.
Things to Remember
- Point DNS to the VPS and open ports 80 and 443 before starting Caddy.
- Keep the
/datafolder in a named volume, because that's where certificates are stored. - Mount the configuration folder, not the
Caddyfiledirectly. - Apps behind Caddy don't need a
portssection. They only need to join theproxynetwork. - Run
caddy validatebeforecaddy reload. - While experimenting, use the Let's Encrypt staging server to avoid rate limits.
Who Is It For?
Caddy is a good fit if you run several self-hosted apps on one VPS and want HTTPS that "just works" with very little maintenance. If you need very specific configuration or you're already comfortable with Nginx, sticking with Nginx isn't a wrong choice either.
Have questions or run into trouble along the way? Feel free to ask. Stay tuned to Teknotut!
Resources and Useful Links
- Official Caddy documentation
- Automatic HTTPS guide for Caddy
- reverse_proxy directive reference
- Official Caddy image on Docker Hub
- Let's Encrypt rate limits
I hope this article helps.



