xcaddy

Build Caddy server from source

$ xcaddy build

$ xcaddy build [version]

$ xcaddy build --with [module_name]

$ xcaddy build --output [path/to/file]

$ xcaddy run

$ xcaddy run --config [path/to/file]

xcaddy [command] [options]

Common commands:
xcaddy build [options]
xcaddy version
xcaddy help

build
    The primary command to compile and build a Caddy binary.

--output <path>
    Specifies the full path and name for the resulting Caddy binary. Defaults to 'caddy' in the current directory.

--with <module_path>[@<version>]
    Includes a Caddy module (plugin) in the build. This option can be specified multiple times to include several modules. Optionally, a specific version of the module can be appended.

--platform <GOOS>/<GOARCH>
    Specifies the target operating system and architecture for cross-compilation (e.g., linux/arm64, windows/amd64).

--go <version>
    Specifies the Go version to use for building Caddy. xcaddy will attempt to download and use it if not already present on the system.

--goos <GOOS>
    Specifies the target operating system (e.g., linux, windows). Often used with --goarch as an alternative to --platform.

--goarch <GOARCH>
    Specifies the target architecture (e.g., amd64, arm64). Often used with --goos as an alternative to --platform.

--goarm <GOARM>
    For ARM architectures, specifies the ARM version (e.g., 7 for ARMv7). Only relevant when targeting ARM.

--skip-build
    Skips the actual Caddy build process. Useful for debugging module compatibility or other pre-build steps.

--enable-telemetry
    Enables anonymous telemetry reporting for the built Caddy binary (not for xcaddy itself). This helps the Caddy project understand usage.

version
    Displays the version of the xcaddy tool itself.

help
    Displays help information for xcaddy or a specific command.

xcaddy is a powerful command-line utility designed to simplify the process of building custom Caddy server binaries. Caddy is a modern, open-source web server that automatically uses HTTPS. While Caddy comes with a robust set of features out-of-the-box, its functionality can be extended via various Go modules (plugins). xcaddy allows users to effortlessly include these external modules into their Caddy build, ensuring a tailored server binary that meets specific requirements. It handles Go module fetching, dependency resolution, and compilation, making it the official and recommended tool for creating custom Caddy distributions. This is especially useful for integrating DNS providers, specific authentication mechanisms, or other third-party functionalities directly into the Caddy executable.

• Go Installation: xcaddy requires the Go programming language to be installed and accessible in your system's PATH. While it can download specific Go versions for the Caddy build, the underlying 'go' command is still needed.
• Internet Connection: Building with external modules or specific Go versions requires an active internet connection to download necessary dependencies and Go SDKs.
• Build Time: Compiling Caddy, especially with numerous modules, can be time-consuming depending on your system's hardware resources and network speed.
• Module Compatibility: Ensure that the Caddy modules you specify are compatible with the Caddy version xcaddy uses (typically the latest stable version unless specified otherwise). Incompatible modules can lead to build failures.

xcaddy is the officially recommended and supported tool for building Caddy, especially when including third-party modules. It ensures proper dependency resolution and compatibility within the Caddy ecosystem.

A significant feature of xcaddy is its ability to easily cross-compile Caddy binaries for different operating systems and architectures (e.g., Linux ARM for Raspberry Pi, Windows for servers). This makes it ideal for deployment to various environments like Docker containers, embedded systems, or different server platforms.

xcaddy was introduced by the Caddy project to streamline the process of building custom Caddy binaries, particularly after Caddy v2 adopted a Go module-based plugin system. Prior to xcaddy, users often had to manually manage Go modules and compilation steps, which could be complex and error-prone. xcaddy simplifies this by providing an official, easy-to-use CLI tool that abstracts away the complexities of Go module integration and compilation, ensuring consistent and reliable custom Caddy builds. It quickly became the recommended and de-facto standard for extending Caddy's functionality.

caddy(8), go(1)