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

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

Requirements

• Go installed

Install

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

You may also build

xcaddy

$ go install github.com/caddyserver/xcaddy/cmd/[email protected]

For Debian, Ubuntu, and Raspbian, an

xcaddy

sudo apt install -y debian-keyring debian-archive-keyring apt-transport-https
curl -1sLf 'https://dl.cloudsmith.io/public/caddy/xcaddy/gpg.key' | sudo tee /etc/apt/trusted.gpg.d/caddy-xcaddy.asc
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

Command usage

The

xcaddy

1. Compile custom

   caddy

   binaries
2. A replacement for

   go run

   while developing Caddy plugins

The

xcaddy

CADDY_VERSION

As usual with

go

xcaddy

GOOS

GOARCH

GOARM

Custom builds

Syntax:

$ xcaddy build []
    [--output ]
    [--with ...]

• is the core Caddy version to build; defaults to

  CADDY_VERSION

  env variable or latest.

• --output

  changes the output file.

• --with

  can 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

--with

$ 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.

For plugin development

If you run

xcaddy

build

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 

• are passed through to the

  caddy

  command.

For example:

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

The race detector can be enabled by setting

XCADDY_RACE_DETECTOR=1

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.

• CADDY_VERSION

  sets the version of Caddy to build.

• XCADDY_RACE_DETECTOR=1

  enables the Go race detector in the build.

• XCADDY_DEBUG=1

  enables the DWARF debug information in the build.

• XCADDY_SETCAP=1

  will run

  sudo setcap cap_net_bind_service=+ep

  on the temporary binary before running it when in dev mode.

• XCADDY_SKIP_BUILD=1

  causes 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=1

  causes xcaddy to leave build artifacts on disk after exiting.

© 2020 Matthew Holt