webinstall.dev/xcaddy Star on GitHub

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

Files

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

~/.config/envman/PATH.env
~/.local/bin/xcaddy
~/.local/opt/go/
~/go/bin/

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

https://github.com/caddyserver/caddy/releases

See also:

• https://github.com/caddyserver/caddy/tags
• https://webinstall.dev/api/releases/caddy.json?pretty=true&channel=stable&os=linux&arch=amd64&limit=10
• https://webinstall.dev/api/releases/caddy.tab?channel=stable&os=linux&arch=amd64&limit=100

How to Find DNS Providers

There are two types of DNS Providers:

1.libdns

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

• https://github.com/caddy-dns
• https://caddyserver.com/docs/modules/ (search dns.providers)

2. lego (legacy)

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

• github.com/caddy-dns/lego-deprecated
• https://github.com/go-acme/lego#dns-providers
• https://caddyserver.com/docs/modules/dns.providers.lego_deprecated

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:

• https://caddyserver.com/docs/modules/

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= \
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

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:

• https://github.com/caddyserver/caddy/tags
• https://github.com/caddyserver/caddy/branches
• https://github.com/caddyserver/caddy/commits/master

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

admin.api.load
# ... 104 other modules
tls.stek.standard

  Standard modules: 106

dns.providers.duckdns

  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:

• go tool dist list
• https://github.com/caddyserver/xcaddy#environment-variables