Master Caddy 2: From Installation to Advanced Configuration

Caddy Overview

Caddy is a Go‑written web server comparable to Nginx, offering stronger built‑in features. Since the release of v2, it has become a viable alternative for small‑to‑medium sites.

Automatic HTTPS certificate issuance (ACME HTTP/DNS challenges)

Automatic certificate renewal and OCSP stapling

Enhanced security, including TLS tuning and memory safety

Friendly, powerful configuration file support

API for dynamic configuration adjustments

HTTP/3 (QUIC) support

Dynamic back‑ends such as Consul or Kubernetes ingress

Multiple load‑balancing strategies and health checks

Highly modular Go codebase, easy to extend (CoreDNS built on Caddy 1)

The main drawback is that Caddy’s raw performance is slightly lower than Nginx, but the convenience often outweighs this difference.

Compiling Caddy 2

Note: Pre‑compiled binaries for Caddy 1 were not allowed for commercial use; Caddy 2 is released under the Apache 2.0 license.

By default, Caddy 2 provides pre‑compiled binaries. To add third‑party plugins you need to compile with xcaddy:

Golang Environment Installation

Assuming an Ubuntu 20.04 host with root access:

wget https://golang.org/dl/go1.15.6.linux-amd64.tar.gz

Extract and set environment variables:

# Extract
 tar -zxvf go1.15.6.linux-amd64.tar.gz

# Move to a permanent location
 mkdir -p /opt/devtools
 mv go /opt/devtools/go

# Create GOPATH directories
 mkdir -p ${HOME}/gopath/{src,bin,pkg}

# Export variables (add to ~/.bashrc or ~/.zshrc)
 export GOROOT='/opt/devtools/go'
 export GOPATH="${HOME}/gopath"
 export GOPROXY='https://goproxy.cn'  # remove if you have unrestricted internet
 export PATH="${GOROOT}/bin:${GOPATH}/bin:${PATH}"

# Apply changes
 source ~/.zshrc

Verify the installation:

go version
go version go1.15.6 linux/amd64

Install xcaddy

Install the build helper:

go get -u github.com/caddyserver/xcaddy/cmd/xcaddy

After installation the xcaddy command should be available.

Compile Caddy 2

First install required tools: apt install -y curl git jq Fetch the latest release tag and build with desired plugins:

export version=$(curl -s "https://api.github.com/repos/caddyserver/caddy/releases/latest" | jq -r .tag_name)
xcaddy build ${version} \
    --output ./caddy_${version} \
    --with github.com/abiosoft/caddy-exec \
    --with github.com/caddy-dns/cloudflare \
    --with github.com/caddy-dns/dnspod \
    --with github.com/caddy-dns/duckdns \
    --with github.com/caddy-dns/gandi \
    --with github.com/caddy-dns/route53 \
    --with github.com/greenpau/caddy-auth-jwt \
    --with github.com/greenpau/caddy-auth-portal \
    --with github.com/greenpau/caddy-trace \
    --with github.com/hairyhenderson/caddy-teapot-module \
    --with github.com/kirsch33/realip \
    --with github.com/porech/caddy-maxmind-geolocation \
    --with github.com/caddyserver/format-encoder \
    --with github.com/mholt/caddy-webdav

When the build finishes, the binary is ready. Verify included modules:

./caddy_${version} list-modules

Installing Caddy 2

Host Installation (systemd)

Install the official package and replace the binary with the custom build:

# Install official package
 sudo apt install -y debian-keyring debian-archive-keyring apt-transport-https
 curl -1sLf 'https://dl.cloudsmith.io/public/caddy/stable/cfg/gpg/gpg.155B6D79CA56EA34.key' | sudo apt-key add -
 curl -1sLf 'https://dl.cloudsmith.io/public/caddy/stable/cfg/setup/config.deb.txt?distro=debian&version=any-version' | sudo tee -a /etc/apt/sources.list.d/caddy-stable.list
 sudo apt update
 sudo apt install caddy

# Replace binary
 systemctl stop caddy
 sudo rm -f /usr/bin/caddy
 sudo mv ./caddy_${version} /usr/bin/caddy

Docker Installation

Build a custom Docker image using a Dockerfile that runs xcaddy. The pre‑built image mritd/caddy is also available on Docker Hub.

Configuring Caddy 2

Caddy 2’s native configuration is JSON, but the more readable Caddyfile format is recommended. Below are essential snippets.

Configuration Snippets

# (TLS) {
    protocols tls1.2 tls1.3
    ciphers TLS_ECDHE_ECDSA_WITH_AES_128_GCM_SHA256 TLS_ECDHE_RSA_WITH_AES_128_GCM_SHA256 TLS_ECDHE_ECDSA_WITH_AES_256_GCM_SHA384 TLS_ECDHE_RSA_WITH_AES_256_GCM_SHA384 TLS_ECDHE_ECDSA_WITH_CHACHA20_POLY1305_SHA256 TLS_ECDHE_RSA_WITH_CHACHA20_POLY1305_SHA256
}

import TLS

Modular Imports

# Import all *.caddy files from /etc/caddy
import /etc/caddy/*.caddy

Site Block Example

# address { site configuration }
example.com {
    # routes, reverse_proxy, etc.
}

Environment Variables

# Use GANDI_API_TOKEN from the environment for DNS challenge
 dns gandi { env.GANDI_API_TOKEN }

Parameterized Snippet Example

(LOG) {
    log {
        format json "[${ts}] ${request>remote_addr} ${request>proto} ${request>method} <- ${status} -> ${request>host}${request>uri} ${request>headers>User-Agent[0]}"
        time_format "iso8601"
        output file "${args.0}" {
            roll_size 100mb
            roll_keep 3
            roll_keep_for 7d
        }
    }
}

import LOG "/data/logs/example.com.log"

Automatic Certificate Issuance

tls {
    dns gandi { env.GANDI_API_TOKEN }
}

After configuring, start Caddy with systemctl start caddy and reload changes with systemctl reload caddy. Reload failures do not interrupt the running service.

Summary

Caddy’s rich plugin ecosystem and Go‑based architecture make it easy to extend compared with Nginx’s Lua or C modules. With built‑in file serving, load balancing, and support for HTTP/3, Caddy 2 is a compelling choice for modern web sites when the modest performance trade‑off is acceptable.