xcaddy

README

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

• Go installed

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

Custom builds

Syntax:

$ xcaddy build [<caddy_version>]
    [--output <file>]
    [--with <module[@version][=replacement]>...]

• <caddy_version> 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/ntlm-transport@v0.1.1

$ 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

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

• <args...> 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. 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.

• 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

Documentation

Index

• type Builder
  • func (b Builder) Build(ctx context.Context, outputFile string) error
• type Compile
  • func SupportedPlatforms() ([]Compile, error)
  • func (c Compile) CgoEnabled() string
• type Dependency
• type Platform
• type Replace
  • func NewReplace(old, new string) Replace
• type ReplacementPath
  • func (r ReplacementPath) Param() string
  • func (r ReplacementPath) String() string

Types

type Builder

type Builder struct {
	Compile
	CaddyVersion string        `json:"caddy_version,omitempty"`
	Plugins      []Dependency  `json:"plugins,omitempty"`
	Replacements []Replace     `json:"replacements,omitempty"`
	TimeoutGet   time.Duration `json:"timeout_get,omitempty"`
	TimeoutBuild time.Duration `json:"timeout_build,omitempty"`
	RaceDetector bool          `json:"race_detector,omitempty"`
	SkipCleanup  bool          `json:"skip_cleanup,omitempty"`
	SkipBuild    bool          `json:"skip_build,omitempty"`
	Debug        bool          `json:"debug,omitempty"`
}

Builder can produce a custom Caddy build with the configuration it represents.

func (Builder) Build

func (b Builder) Build(ctx context.Context, outputFile string) error

Build builds Caddy at the configured version with the configured plugins and plops down a binary at outputFile.

type Compile

type Compile struct {
	Platform
	Cgo bool `json:"cgo,omitempty"`
}

Compile contains parameters for compilation.

func SupportedPlatforms

func SupportedPlatforms() ([]Compile, error)

SupportedPlatforms runs `go tool dist list` to make a list of possible build targets.

func (Compile) CgoEnabled

func (c Compile) CgoEnabled() string

CgoEnabled returns "1" if c.Cgo is true, "0" otherwise. This is used for setting the CGO_ENABLED env variable.

type Dependency

type Dependency struct {
	// The name (import path) of the Go package. If at a version > 1,
	// it should contain semantic import version (i.e. "/v2").
	// Used with `go get`.
	PackagePath string `json:"module_path,omitempty"`

	// The version of the Go module, as used with `go get`.
	Version string `json:"version,omitempty"`
}

Dependency pairs a Go module path with a version.

type Platform

type Platform struct {
	OS   string `json:"os,omitempty"`
	Arch string `json:"arch,omitempty"`
	ARM  string `json:"arm,omitempty"`
}

Platform represents a build target.

type Replace

type Replace struct {
	// The import path of the module being replaced.
	Old ReplacementPath `json:"old,omitempty"`

	// The path to the replacement module.
	New ReplacementPath `json:"new,omitempty"`
}

Replace represents a Go module replacement.

func NewReplace

func NewReplace(old, new string) Replace

NewReplace creates a new instance of Replace provided old and new Go module paths

type ReplacementPath

type ReplacementPath string

ReplacementPath represents an old or new path component within a Go module replacement directive.

func (ReplacementPath) Param

func (r ReplacementPath) Param() string

Param reformats a go.mod replace directive to be compatible with the `go mod edit` command.

func (ReplacementPath) String

func (r ReplacementPath) String() string