Build Caddy with plugins
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
caddybinaries (with or without plugins).
⚠️ Still in development. Supports Caddy 2 only.
Stay updated, be aware of changes, and please submit feedback! Thanks!
You can download binaries that are already compiled for your platform, or build
xcaddyfrom source:
$ go get -u github.com/caddyserver/xcaddy/cmd/xcaddy
The
xcaddycommand has two primary uses:
caddybinaries
go runwhile developing Caddy plugins
The
xcaddycommand will use the latest version of Caddy by default. You can customize this for all invocations by setting the
CADDY_VERSIONenvironment variable.
As usual with
gocommand, the
xcaddycommand will pass the
GOOS,
GOARCH, and
GOARMenvironment variables through for cross-compilation.
Syntax:
$ xcaddy build [] [--output ] [--with ...]
CADDY_VERSIONenv variable or latest.
--outputchanges the output file.
--withcan be used multiple times to add plugins by specifying the Go module name and optionally its version, similar to
go get. Module name is required, but specific version and/or local replacement are optional.
Examples:
$ xcaddy build \ --with github.com/caddyserver/ntlm-transport$ xcaddy build v2.0.1
--with github.com/caddyserver/[email protected]$ xcaddy build
--with github.com/caddyserver/ntlm-transport=../../my-fork$ xcaddy build
--with github.com/caddyserver/[email protected]=../../my-fork
You can even replace Caddy core using the
--withflag:
$ xcaddy build \ --with github.com/caddyserver/caddy/v2=../../my-caddy-fork
This allows you to hack on Caddy core (and optionally plug in extra modules at the same time!) with relative ease.
If you run
xcaddyfrom within the folder of the Caddy plugin you're working on without the
buildsubcommand, 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
caddycommand.
For example:
$ xcaddy list-modules $ xcaddy run $ xcaddy run --config caddy.json
The race detector can be enabled by setting
XCADDY_RACE_DETECTOR=1.
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.
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.
CADDY_VERSIONsets the version of Caddy to build.
XCADDY_RACE_DETECTOR=1enables the Go race detector in the build.
XCADDY_SETCAP=1will run
sudo setcap cap_net_bind_service=+epon the temporary binary before running it when in dev mode.
XCADDY_SKIP_BUILD=1causes xcaddy to not compile the program, it is used in conjunction with build tools such as GoReleaser. Implies
XCADDY_SKIP_CLEANUP=1.
XCADDY_SKIP_CLEANUP=1causes xcaddy to leave build artifacts on disk after exiting.
© 2020 Matthew Holt