xcaddy makes it easy to make custom builds of the Caddy Web Server

To update or switch versions, run webi xcaddy@stable (or @v0.3, @beta, etc).


These are the files / directories that are created and/or modified with this install:


Cheat Sheet

xcaddy makes it easy to build caddy with DNS providers, and to test builds of feature branches and PRs.

Build with xcaddy:

CGO_ENABLED=0 xcaddy build 'v2.7.5' \
    --with github.com/caddy-dns/duckdns \
    --with github.com/caddy-dns/lego-deprecated \
    --output ./caddy-v2.7.5-extras

See that it worked:

./caddy-v2.7.5-extras list-modules
# v2.7.5 h1:HoysvZkLcN2xJExEepaFHK92Qgs7xAiCFydN5x5Hs6Q=

Other helpful tips:

  • Caddy Versions
  • DNS Providers
  • Other Modules
  • Cross-Compiling
  • Build a Feature Branch
  • Build a Fork
  • List Built-In Modules
  • Common ENVs

How to List Available Caddy Versions


See also:

How to Find DNS Providers

There are two types of DNS Providers:


These providers each have their own module, most of which can be searched here:

2. lego (legacy)

This module bundles many providers together, all of which are listed here:

How to Find Other Modules

There are a variety of other modules, including things like ngrok, s3, layer4, and others.

Most module authors register them in the caddy modules docs:

However, a module can be loaded from any Git URL (not just GitHub).

Note: Modules are named internally by their namespace (e.g. dns.providers.x), but referenced externally by their Git URL .

How to Cross-Compile

Use CGO_ENABLED, GOOS, GOARCH, and GOARM (for 32-bit ARM):

GOOS=linux GOARCH=arm64 GOARM= \
    xcaddy build 'v2.7.5' \
    --with github.com/caddy-dns/duckdns \
    --with github.com/caddy-dns/lego-deprecated \
    --output ./caddy-v2.7.5-extras

You can inline (as seen above) or export the ENVs:

export GOOS=linux
export GOARCH=arm64
export GOARM=
export CGO_ENABLED=0

xcaddy build 'v2.7.5' \
    --with github.com/caddy-dns/duckdns \
    --with github.com/caddy-dns/lego-deprecated \
    --output ./caddy-v2.7.5-extras

Using CGO_ENABLED=0 can only build pure Go programs, which means that cross-compiling is guaranteed to succeed (assuming the modules don't contain C), however, file sizes may be slightly larger for bundling Go modules for DNS resolution, etc, which your OS would otherwise provide.

Common OSes and Arches are:

  • linux, darwin, windows, freebsd
  • amd64, arm64, mips, ppc64le

See also:

  • OSes: go tool dist list | cut -d/ -f1 | sort -u
  • Arches: go tool dist list | cut -d/ -f2 | sort -u

How to Build From a Feature Branch

The build is actually a commit-ish (a.k.a. a "git ref"), which can apply to any branch of the official repository:

xcaddy build "file-placeholder"

See also:

How to List Built-In Modules

When it's time to rebuild caddy and you've forgotten which modules you used to build it, fear not!

list-modules to the rescue!

caddy list-modules
# ... 104 other modules

  Standard modules: 106


  Non-standard modules: 1

Common Options

Here are some of the common environment variables that change xcaddy's behavior:

Option Description
CGO_ENABLED Set to 0 to build pure Go (no C or OS libraries)
GOOS For cross-compiling: linux, darwin, windows, etc
GOARCH For cross-compiling: amd64, arm64, arm, etc
GOARM For cross-compiling arm (32-bit): 7 or 6 (8 is arm64)
CADDY_VERSION Equivalent to xcaddy build "$CADDY_VERSION" ...
XCADDY_SETCAP=1 Linux: runs sudo setcap cap_net_bind_service=+ep
XCADDY_SUDO=0 Don't use sudo for XCADDY_SETCAP (i.e. on Alpine)
XCADDY_RACE_DETECTOR For finding race conditions in feature builds
XCADDY_DEBUG=1 Disables -ldflags '-w -s', for debug builds
XCADDY_SKIP_CLEANUP Leaves build files (for debugging failure)
XCADDY_SKIP_BUILD For use with building & releasing custom builds w/ GoReleaser

See also:


Report an Issue Submit Installer Star on GitHub