Caddy Installation Guide
Caddy ships as a single self-contained binary: one file that contains the web server, the TLS stack, the ACME client, and every module compiled into that particular build. Once it is installed, you point it at a domain name and it obtains a certificate, serves the site over HTTPS, and renews the certificate on its own. By the end of this page you will be able to install Caddy on a Linux, macOS, or Windows host, run it as a managed background service, confirm which build and which modules are active, and verify that the server is genuinely ready to serve HTTPS before you point real traffic at it.
- One binary, no runtime dependencies. Caddy is written in Go and statically links its own TLS and HTTP implementations. There is no OpenSSL to patch and no external certificate renewal agent to keep alive.
- Ports 80 and 443 are used by default. Automatic HTTPS binds the standard HTTP port to answer the ACME HTTP challenge, and the standard HTTPS port to serve traffic.
- Modules are compiled in. Official builds ship the standard module set; third-party plugins must be compiled in.
caddy list-modulesis the fastest way to confirm what a given binary can do. - State lives in two directories. Certificates, private keys, and the ACME account go under a data directory; runtime configuration goes under a config directory.
| Requirement | Why it matters |
|---|---|
Root access or sudo | Ports 80 and 443 are privileged |
| A domain whose A and AAAA records point at this host | Automatic HTTPS cannot issue for a name that does not resolve to you |
| Outbound TCP 80 and 443 | The ACME challenges and certificate renewal need them |
| A DNS provider API, if you must use the DNS challenge | Wildcard certificates cannot be issued over HTTP |
Behind a cloud load balancer or on a private network, a domain that resolves to a public IP other than the machine running Caddy will fail the HTTP challenge. Either forward ports 80 and 443 to Caddy, or switch to the DNS challenge described in the HTTPS chapter.
Official packages are the best choice for a production server because the distribution handles the service unit, the dedicated system user, and the upgrade path.
3.1 Debian and Ubuntu
sudo apt install -y debian-keyring debian-archive-keyring apt-transport-https curl
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 apt update
sudo apt install caddy
The package installs /usr/bin/caddy, a caddy system user, and a caddy.service unit. The default configuration lives at /etc/caddy/Caddyfile.
3.2 RHEL, Fedora, and Rocky Linux
sudo dnf install 'dnf-command(copr)'
sudo dnf copr enable @caddy/caddy
sudo dnf install caddy
3.3 Alpine Linux
sudo apk add caddy
rc-update add caddy default
rc-service caddy start
3.4 macOS and Windows
Homebrew installs into the Homebrew prefix and creates no system user, so on a shared host prefer the manual binary route and manage the service yourself:
brew install caddy
brew services start caddy
On Windows, Chocolatey and Scoop both publish Caddy:
choco install caddy
scoop install caddy
When no package exists for your platform, download the release archive that matches your operating system and CPU architecture from the GitHub releases page.
CADDY_VERSION=2.10.2
curl -fsSLO "https://github.com/caddyserver/caddy/releases/download/v${CADDY_VERSION}/caddy_${CADDY_VERSION}_linux_amd64.tar.gz"
tar -xzf "caddy_${CADDY_VERSION}_linux_amd64.tar.gz" caddy
sudo install -m 0755 caddy /usr/local/bin/caddy
caddy version
Create an unprivileged service account so that a compromised handler never runs as root, and give it ownership of the state directories:
sudo useradd --system --no-create-home --shell /usr/sbin/nologin caddy
sudo mkdir -p /var/lib/caddy /var/log/caddy /etc/caddy
sudo chown -R caddy:caddy /var/lib/caddy /var/log/caddy
Upgrading a static binary means replacing it with the newer release and restarting the service; the caddy upgrade command performs that replacement for you.
The official image is published as caddy on Docker Hub and tracks the same release stream as the binary packages.
docker run --rm caddy:2 caddy version
Certificates and configuration must live on a persistent volume, otherwise every container restart triggers a new ACME account and a new issuance. The full container workflow, including Compose networks and proxying to other services, is covered in the Docker deployment chapter.
The Debian and RHEL packages ship a systemd unit:
sudo systemctl enable --now caddy
sudo systemctl status caddy
For a manually installed binary, write your own unit:
[Unit]
Description=Caddy
After=network.target
[Service]
Type=notify
User=caddy
Group=caddy
ExecStart=/usr/local/bin/caddy run --environ --config /etc/caddy/Caddyfile
ExecReload=/usr/local/bin/caddy reload --config /etc/caddy/Caddyfile --force
Restart=on-failure
RestartSec=5s
[Install]
WantedBy=multi-user.target
Type=notify matters: Caddy notifies systemd once it has finished starting, so systemd will not report the unit as active before the listeners actually accept connections.
Run these checks in order. Each one rules out a different class of failure.
# Which version is installed, and which modules does it contain?
caddy version
caddy list-modules
# Is the configuration file valid? This does not start the server.
caddy validate --config /etc/caddy/Caddyfile
# See the JSON that the Caddyfile adapter produces.
caddy adapt --config /etc/caddy/Caddyfile --pretty
# Is the process actually listening?
sudo ss -ltnp | grep caddy
Then confirm the service is healthy and the server answers:
sudo systemctl status caddy
sudo journalctl -u caddy --since "10 minutes ago" --no-pager
curl -I http://localhost
curl -I https://your-domain.example
An HTTP request that returns a redirect to the HTTPS URL proves Automatic HTTPS is active. A successful HTTPS request proves the certificate was issued and the site block is routing.
| Symptom | Cause | Fix |
|---|---|---|
bind: address already in use | Another server holds port 80 or 443 | Stop the other service, or move it to another port |
| Issuance fails with an HTTP challenge error | Port 80 is blocked, or DNS points elsewhere | Forward port 80 to Caddy, or use the DNS challenge |
Permission denied under /var/lib/caddy | The service account cannot write the data directory | Give the caddy user ownership of that directory |
caddy validate passes but the site returns 404 | The site address does not match the requested Host header | Check the site address and the Host header |
Continue with the basic configuration chapter to learn the shape of a Caddyfile, then the HTTPS chapter to see what Automatic HTTPS does on your behalf.
Approach:
A production Caddy install is only finished when three independent facts are true: the binary is on the machine, a supervisor keeps it running across reboots, and the server has been observed answering a real HTTPS request with a valid certificate. Each of the three can fail on its own, so verification is staged instead of being treated as a single “it installed” moment.
Steps:
- Install the official package for the distribution, which is Debian or Ubuntu here, using the Cloudsmith APT repository so upgrades arrive with the normal
apt upgradecycle. - Confirm the binary and the compiled-in module set with
caddy versionandcaddy list-modules. The module list tells you whether third-party plugins, such as a DNS provider, are available, which matters before attempting wildcard certificates. - Validate the shipped configuration with
caddy validate --config /etc/caddy/Caddyfile. This parses and provisions the config without opening any listener, so it is safe to run at any time. - Start and enable the systemd unit with
sudo systemctl enable --now caddy, then confirm the process listens on ports 80 and 443 usingsudo ss -ltnp. - Exercise both protocols. An HTTP request that redirects to HTTPS proves the redirect server is live; an HTTPS request returning 200 with a valid certificate proves ACME issuance worked.
- Read the service log with
sudo journalctl -u caddywhen any step misbehaves, because the ACME client narrates its progress there.
Answer:
A correct installation produces this sequence of results:
caddy versionprints a version string such asv2.10.2, andcaddy list-modulesprints the standard module set includinghttp.handlers.reverse_proxyandtls.issuance.acme.caddy validatereports that the configuration is valid and exits with status 0.systemctl status caddyshows the unit active and running, with the process owned by the unprivilegedcaddyuser rather than by root.ss -ltnpshows listeners on 0.0.0.0:80 and 0.0.0.0:443.curl -I http://your-domain.examplereturns301with aLocationheader pointing at the HTTPS URL.curl -I https://your-domain.examplereturns200with a certificate issued by a public CA that covers the domain.
Once all six hold, the server is ready for real traffic and the next step is writing the Caddyfile that defines what it serves.
