xcaddy

The --embed flag allows you to include local files directly inside the Caddy executable. To use them, you must declare a custom filesystem using the embedded module in your Caddyfile.

Using unaliased directories

If you use --embed ./dir, the contents are merged into the root of the embedded filesystem.

$ xcaddy build --embed ./my-files --embed ./my-other-files

Caddyfile usage:

{
	filesystem my_embeds embedded
}

localhost {
	file_server {
		fs my_embeds
	}
}

Using aliased directories

To serve multiple sites from different embedded directories, use an alias prefix (alias:path).

$ xcaddy build --embed foo:./sites/foo --embed bar:./sites/bar

Caddyfile usage:

{
	filesystem my_embeds embedded
}

foo.localhost {
	root * /foo
	file_server {
		fs my_embeds
	}
}

bar.localhost {
	root * /bar
	file_server {
		fs my_embeds
	}
}

To ensure reproducible and secure builds, Builder provides mechanisms to control the environment and redact sensitive information:

• Env: If provided, this slice of KEY=value strings becomes the entire environment for the underlying Go commands. The process's ambient environment is not inherited. This is recommended for 'hermetic' builds to prevent leaking local credentials (like GOPROXY user info or .netrc) into build logs. You must include essential variables like PATH and HOME (or GOCACHE/GOMODCACHE).
• Secrets: A list of strings that will be replaced with [REDACTED] in any step output processed via OnStep. Matching is exact and line-buffered.
• RedactCredentials: When set to true, the builder attempts to mask common credential patterns (e.g., GitHub/AWS tokens, PEM private keys) in the output. This is a best-effort backstop and does not replace the need for a hermetic environment.

The OnStep callback allows you to monitor and control the build process. It is called for each build phase (e.g., StepCompile, StepTidyModule). The callback runs in its own goroutine concurrently with the step, allowing you to read the step's Output (which includes stdout/stderr from Go commands) in real-time.

Key behaviors:

• Concurrency: The callback runs concurrently with the step. You can consume event.Output directly.
• Sequentiality: Callbacks do not overlap; the next step starts only after the previous callback returns.
• Error Handling: Returning a non-nil error from the callback aborts the build at the end of that step. To cancel a step mid-execution, cancel the context.Context passed to Build.
• Lifecycle: Output reaches EOF when the step ends.

builder.OnStep = func(e *xcaddy.StepEvent) error {
    scanner := bufio.NewScanner(e.Output)
    for scanner.Scan() {
        fmt.Printf("[%s] %s\n", e.Step, scanner.Text())
    }
    return scanner.Err()
}

The following environment variables control xcaddy behavior:

Use the xcaddy build command to compile a custom Caddy binary with specific plugins, versions, or embedded files.

Syntax

$ xcaddy build [<caddy_version>]
    [--output <file>]
    [--with <module[@version][=replacement]>...]
    [--replace <module[@version]=replacement>...]
    [--embed <[alias]:path/to/dir>...]
    [--pgo <file>]

Arguments

• <caddy_version>: The core Caddy version to build. Defaults to the CADDY_VERSION env var or latest. Accepts tags (e.g., v2.0.1), branches (e.g., master), or commit hashes.
• --output <file>: Specifies the output filename.
• --with <module[@version][=replacement]>: Adds plugins. You can specify a version or a local replacement (e.g., --with github.com/user/repo=../local-repo).
• --replace <module[@version]=replacement>: Writes a replace directive to go.mod without adding a blank import. Useful for developing Caddy's dependencies.
• --embed <[alias]:path/to/dir>: Embeds a directory into the binary.
  • Without an alias: Files are placed in the root of the embedded filesystem.
  • With an alias (alias:path): Files are placed in a subdirectory named after the alias.
• --pgo <file>: (Experimental) Specifies a profile for Profile Guided Optimization. If default.pgo exists in the current directory, it is used automatically.