caddy-website/src/docs/markdown/build.md

title
Build from source

Build from source

There are 2 ways to build Caddy, as opposed to installation of pre-built executable:

• Build from Git repo
• Build using xcaddy

Requirements:

• Go 1.20 or newer

You can easily cross-compile, i.e. build Caddy on one operating system or architecture for a different, using the same tooling. You'll find details on this in the respective section.

The latest section contains instructions for users who installed Caddy using the APT command on Debian-derivative system yet need the custom build executable for their operations.

Build from Git repo

Requirements:

• Go installed (see above)

Clone the repository:

git clone "https://github.com/caddyserver/caddy.git"

If you don't have git, you can download the source code as a file archive from GitHub. Each release also has source snapshots.

Build:

cd caddy/cmd/caddy/
go build

Due to a bug in Go, these basic steps do not embed version information. If you want the version (caddy version), you need to compile Caddy as a dependency rather than as the main module. Instructions for this are in Caddy's main.go file. Or, you can use xcaddy which automates this.

Go programs are easy to compile for other platforms. Just set the GOOS, GOARCH, and/or GOARM environment variables that are different. (See the go documentation for details.)

For example, to compile Caddy for Windows when you're not on Windows:

GOOS=windows go build

Or similarly for Linux ARMv6 when you're not on Linux or on ARMv6:

GOOS=linux GOARCH=arm GOARM=6 go build

Build using xcaddy

The xcaddy command is the easiest way to build Caddy with version information and/or plugins.

Requirements:

• Go installed (see above)
• Make sure xcaddy is in your PATH

You do not need to download the Caddy source code (it will do that for you).

Then building Caddy (with version information) is as easy as:

xcaddy build

To build with plugins, use --with:

xcaddy build \
    --with github.com/caddyserver/nginx-adapter
	--with github.com/caddyserver/ntlm-transport@v0.1.1

As you can see, you can customize the versions of plugins with @ syntax. Versions can be a tag name, commit SHA, or branch.

Cross-platform compilation with xcaddy works the same as with the go command. For example, to cross-compile for macOS:

GOOS=darwin xcaddy build

Package support files for custom builds for Debian/Ubuntu/Raspbian

This procedure aims to simplify running custom caddy binaries while keeping support files from the caddy package.

This procedure allows users to take advantage of the default configuration, systemd service files and bash-completion from the official package.

Requirements:

• Install caddy package according to these instructions
• Build your custom caddy binary according to the procedure listed in this document. (see above)
• Your custom caddy binary should be located in the current directory.

Procedure:

sudo dpkg-divert --divert /usr/bin/caddy.default --rename /usr/bin/caddy
sudo mv ./caddy /usr/bin/caddy.custom
sudo update-alternatives --install /usr/bin/caddy caddy /usr/bin/caddy.default 10
sudo update-alternatives --install /usr/bin/caddy caddy /usr/bin/caddy.custom 50
sudo systemctl restart caddy

dpkg-divert will move /usr/bin/caddy binary to /usr/bin/caddy.default and put a diversion in place in case any package want to install a file to this location.

update-alternatives will create a symlink from the desired caddy binary to /usr/bin/caddy

systemctl restart caddy will shut down the default version of the Caddy server and start the custom one.

You can change between the custom and default caddy binaries by executing

update-alternatives --config caddy

and following the on screen information, then restarting the Caddy service.