Need help with xcaddy?
Click the “chat” button below for chat support from the developer who created it, or find similar developers for support.

About the developer

caddyserver
155 Stars 27 Forks Apache License 2.0 45 Commits 2 Opened issues

Description

Build Caddy with plugins

Services available

!
?

Need anything else?

Contributors list

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

⚠️ Still in development. Supports Caddy 2 only.

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

Requirements

Install

You can download binaries that are already compiled for your platform, or build

xcaddy
from source:
$ go get -u github.com/caddyserver/xcaddy/cmd/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 []
    [--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
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 
  •  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
.

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

We use cookies. If you continue to browse the site, you agree to the use of cookies. For more information on our use of cookies please see our Privacy Policy.