Build from source

There are multiple options for building Caddy, if you need a customized build (e.g. with plugins):

Git: Build from Git repo
xcaddy: Build using xcaddy
Docker: Build a custom Docker image

Requirements:

Go 1.20 or newer

The Package Support Files 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.

Git

Requirements:

Go installed (see above)

Clone the repository:

<pre><code class="cmd bash">git clone "https://github.com/caddyserver/caddy.git"</code></pre>

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:

<pre><code class="cmd">cd caddy/cmd/caddy/ go build</code></pre> <aside class="tip">

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.

</aside>

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:

<pre><code class="cmd bash">GOOS=windows go build</code></pre>

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

<pre><code class="cmd bash">GOOS=linux GOARCH=arm GOARM=6 go build</code></pre>

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:

<pre><code class="cmd bash">xcaddy build</code></pre>

To build with plugins, use --with:

<pre><code class="cmd bash">xcaddy build \ --with github.com/caddyserver/nginx-adapter --with github.com/caddyserver/[email protected]</code></pre>

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:

<pre><code class="cmd bash">GOOS=darwin xcaddy build</code></pre>

Docker

You can use the :builder image as a short-cut to building a new Caddy binary with custom modules:

Dockerfile

FROM caddy:<version>-builder AS builder

RUN --mount=type=cache,target=/go/pkg/mod \
    --mount=type=cache,target=/root/.cache/go-build \
    xcaddy build \
    --with github.com/caddyserver/nginx-adapter \
    --with github.com/hairyhenderson/[email protected]

FROM caddy:<version>

COPY --from=builder /usr/bin/caddy /usr/bin/caddy

Make sure to replace <version> with the latest version of Caddy to start.

Note the second FROM instruction — this produces a much smaller image by simply overlaying the newly-built binary on top of the regular caddy image.

The builder uses xcaddy to build Caddy with the provided modules, similar to the process outlined above. The --mount=type=cache,target=/go/pkg/mod and --mount=type=cache,target=/root/.cache/go-build options are used to cache the Go module dependencies and build artifacts, respectively, which speeds up subsequent builds. The flag is a feature of Docker, not of xcaddy.

To use Docker Compose, see our recommended compose.yml and usage instructions.

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 the caddy package according to these instructions
Build your custom caddy binary (see above sections), or download a custom build
Your custom caddy binary should be located in the current directory

Procedure:

<pre><code class="cmd">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 </code></pre>

Explanation:

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 the below, and following the on screen information. Then, restart the Caddy service.

<pre><code class="cmd bash">update-alternatives --config caddy</code></pre>

To upgrade Caddy after this point, you may run caddy upgrade. This attempts to download a build with the same plugins as your current build, with the latest version of Caddy, then replace the current binary with the new one.