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.

1. What you are installing

  • 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-modules is 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.

2. Prerequisites

RequirementWhy it matters
Root access or sudoPorts 80 and 443 are privileged
A domain whose A and AAAA records point at this hostAutomatic HTTPS cannot issue for a name that does not resolve to you
Outbound TCP 80 and 443The ACME challenges and certificate renewal need them
A DNS provider API, if you must use the DNS challengeWildcard 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.

3. Install with a package manager

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

4. Install a static binary manually

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.

5. Install with Docker

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.

6. Run Caddy as a service

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.

7. Verify the installation

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.

8. Common installation problems

SymptomCauseFix
bind: address already in useAnother server holds port 80 or 443Stop the other service, or move it to another port
Issuance fails with an HTTP challenge errorPort 80 is blocked, or DNS points elsewhereForward port 80 to Caddy, or use the DNS challenge
Permission denied under /var/lib/caddyThe service account cannot write the data directoryGive the caddy user ownership of that directory
caddy validate passes but the site returns 404The site address does not match the requested Host headerCheck 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.

caddy installationlinux servercaddy serviceverification

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:

  1. 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 upgrade cycle.
  2. Confirm the binary and the compiled-in module set with caddy version and caddy list-modules. The module list tells you whether third-party plugins, such as a DNS provider, are available, which matters before attempting wildcard certificates.
  3. 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.
  4. Start and enable the systemd unit with sudo systemctl enable --now caddy, then confirm the process listens on ports 80 and 443 using sudo ss -ltnp.
  5. 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.
  6. Read the service log with sudo journalctl -u caddy when any step misbehaves, because the ACME client narrates its progress there.

Answer:

A correct installation produces this sequence of results:

  • caddy version prints a version string such as v2.10.2, and caddy list-modules prints the standard module set including http.handlers.reverse_proxy and tls.issuance.acme.
  • caddy validate reports that the configuration is valid and exits with status 0.
  • systemctl status caddy shows the unit active and running, with the process owned by the unprivileged caddy user rather than by root.
  • ss -ltnp shows listeners on 0.0.0.0:80 and 0.0.0.0:443.
  • curl -I http://your-domain.example returns 301 with a Location header pointing at the HTTPS URL.
  • curl -I https://your-domain.example returns 200 with 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.

Found an issue with this content?

Tell us what could be improved.