Home

Awesome

xcaddy - Custom Caddy Builder

This command line tool and associated Go package makes it easy to make custom builds of the Caddy Web Server.

It is used heavily by Caddy plugin developers as well as anyone who wishes to make custom caddy binaries (with or without plugins).

Stay updated, be aware of changes, and please submit feedback! Thanks!

Requirements

Install

You can download binaries that are already compiled for your platform from the Release tab.

You may also build xcaddy from source:

go install github.com/caddyserver/xcaddy/cmd/xcaddy@latest

For Debian, Ubuntu, and Raspbian, an xcaddy package is available from our Cloudsmith repo:

sudo apt install -y debian-keyring debian-archive-keyring apt-transport-https
curl -1sLf 'https://dl.cloudsmith.io/public/caddy/xcaddy/gpg.key' | sudo gpg --dearmor -o /usr/share/keyrings/caddy-xcaddy-archive-keyring.gpg
curl -1sLf 'https://dl.cloudsmith.io/public/caddy/xcaddy/debian.deb.txt' | sudo tee /etc/apt/sources.list.d/caddy-xcaddy.list
sudo apt update
sudo apt install xcaddy

:warning: Pro tip

If you find yourself fighting xcaddy in relation to your custom or proprietary build or development process, it might be easier to just build Caddy manually!

Caddy's main.go file, the main entry point to the application, has instructions in the comments explaining how to build Caddy essentially the same way xcaddy does it. But when you use the go command directly, you have more control over the whole thing and it may save you a lot of trouble.

The manual build procedure is very easy: just copy the main.go into a new folder, initialize a Go module, plug in your plugins (add an import for each one) and then run go build. Of course, you may wish to customize the go.mod file to your liking (specific dependency versions, replacements, etc).

Command usage

The xcaddy command has two primary uses:

  1. Compile custom caddy binaries
  2. A replacement for go run while developing Caddy plugins

The xcaddy command will use the latest version of Caddy by default. You can customize this for all invocations by setting the CADDY_VERSION environment variable.

As usual with go command, the xcaddy command will pass the GOOS, GOARCH, and GOARM environment variables through for cross-compilation.

Note that xcaddy will ignore the vendor/ folder with -mod=readonly.

Custom builds

Syntax:

$ xcaddy build [<caddy_version>]
    [--output <file>]
    [--with <module[@version][=replacement]>...]
    [--replace <module[@version]=replacement>...]
    [--embed <[alias]:path/to/dir>...]

Examples

$ xcaddy build \
    --with github.com/caddyserver/ntlm-transport

$ xcaddy build v2.0.1 \
    --with github.com/caddyserver/ntlm-transport@v0.1.1

$ xcaddy build master \
    --with github.com/caddyserver/ntlm-transport

$ xcaddy build a58f240d3ecbb59285303746406cab50217f8d24 \
    --with github.com/caddyserver/ntlm-transport

$ xcaddy build \
    --with github.com/caddyserver/ntlm-transport=../../my-fork

$ xcaddy build \
    --with github.com/caddyserver/ntlm-transport@v0.1.1=../../my-fork

You can even replace Caddy core using the --with flag:

$ xcaddy build \
    --with github.com/caddyserver/caddy/v2=../../my-caddy-fork
    
$ xcaddy build \
    --with github.com/caddyserver/caddy/v2=github.com/my-user/caddy/v2@some-branch

This allows you to hack on Caddy core (and optionally plug in extra modules at the same time!) with relative ease.

If --embed is used without an alias prefix, the contents of the source directory are written directly into the root directory of the embedded filesystem within the Caddy executable. The contents of multiple unaliased source directories will be merged together:

$ xcaddy build --embed ./my-files --embed ./my-other-files
$ cat Caddyfile
{
	# You must declare a custom filesystem using the `embedded` module.
	# The first argument to `filesystem` is an arbitrary identifier
	# that will also be passed to `fs` directives.
	filesystem my_embeds embedded
}

localhost {
	# This serves the files or directories that were
	# contained inside of ./my-files and ./my-other-files
	file_server {
		fs my_embeds
	}
}

You may also prefix the source directory with a custom alias and colon separator to write the source directory's contents to a separate subdirectory within the embedded filesystem:

$ xcaddy build --embed foo:./sites/foo --embed bar:./sites/bar
$ cat Caddyfile
{
	filesystem my_embeds embedded
}

foo.localhost {
	# This serves the files or directories that were
	# contained inside of ./sites/foo
	root * /foo
	file_server {
		fs my_embeds
	}
}

bar.localhost {
	# This serves the files or directories that were
	# contained inside of ./sites/bar
	root * /bar
	file_server {
		fs my_embeds
	}
}

This allows you to serve 2 sites from 2 different embedded directories, which are referenced by aliases, from a single Caddy executable.

If you need to work on Caddy's dependencies, you can use the --replace flag to replace it with a local copy of that dependency (or your fork on github etc if you need):

$ xcaddy build some-branch-on-caddy \
    --replace golang.org/x/net=../net

For plugin development

If you run xcaddy from within the folder of the Caddy plugin you're working on without the build subcommand, it will build Caddy with your current module and run it, as if you manually plugged it in and invoked go run.

The binary will be built and run from the current directory, then cleaned up.

The current working directory must be inside an initialized Go module.

Syntax:

$ xcaddy <args...>

For example:

$ xcaddy list-modules
$ xcaddy run
$ xcaddy run --config caddy.json

The race detector can be enabled by setting XCADDY_RACE_DETECTOR=1. The DWARF debug info can be enabled by setting XCADDY_DEBUG=1.

Getting xcaddy's version

$ xcaddy version

Library usage

builder := xcaddy.Builder{
	CaddyVersion: "v2.0.0",
	Plugins: []xcaddy.Dependency{
		{
			ModulePath: "github.com/caddyserver/ntlm-transport",
			Version:    "v0.1.1",
		},
	},
}
err := builder.Build(context.Background(), "./caddy")

Versions can be anything compatible with go get.

Environment variables

Because the subcommands and flags are constrained to benefit rapid plugin prototyping, xcaddy does read some environment variables to take cues for its behavior and/or configuration when there is no room for flags.

© 2020 Matthew Holt