Building from Source

Compile Caddy from source code for development and customization

Building Caddy from source gives you control over the build process and is essential for module development. This guide covers building for both development and production.

Requirements

From README.md:106:

• Go 1.25.0 or newer

Older Go versions are not supported. Always use the version specified in the requirements.

Quick Development Build

For rapid development and testing, from README.md:114:

1. Clone the repository

   git clone "https://github.com/caddyserver/caddy.git"
   cd caddy/cmd/caddy/
   
2. Build the binary

   go build
   

   This creates a caddy binary in the current directory.

These steps will not embed proper version information. For production builds with version info, see the next section.

Running Tests

From README.md:136:

All Tests

go test ./...

Specific Module

go test ./modules/caddyhttp/tracing/

Run tests frequently during development to catch issues early.

Permission to Bind Low Ports

Caddy may need to bind to ports 80 and 443 for HTTPS. From README.md:120:

Linux

sudo setcap cap_net_bind_service=+ep ./caddy

Using go run

If you prefer go run, use the included helper script:

go run -exec ./setcap.sh main.go

Passwordless setcap (Optional)

To avoid entering your password repeatedly, from README.md:128:

Only do this if you understand the security implications!

sudo visudo

Add this line (replace username with your actual username):

username ALL=(ALL:ALL) NOPASSWD: /usr/sbin/setcap

Production Build with Version Info

For builds with proper version information and/or plugins, use xcaddy.

From README.md:145:

xcaddy build

See the xcaddy documentation for detailed information.

Manual Production Build Process

The xcaddy tool automates these steps from README.md:151:

1. Create a new folder

   mkdir caddy
   cd caddy
   
2. Copy main.go

   Copy Caddy’s main.go into the folder.

   From cmd/caddy/main.go:15:

   package main
   
   import (
       _ "time/tzdata"
       caddycmd "github.com/caddyserver/caddy/v2/cmd"
       _ "github.com/caddyserver/caddy/v2/modules/standard"
   )
   
   func main() {
       caddycmd.Main()
   }
   

   Add imports for any custom plugins you want.

3. Initialize Go module

   go mod init caddy
   
4. Pin Caddy version (optional)

   go get github.com/caddyserver/caddy/v2@version
   

   Replace version with:

   • A git tag (e.g., v2.8.0)
   • A commit hash
   • A branch name (e.g., master)
5. Add plugins (optional)

   Add plugin imports to main.go:

   import (
       _ "time/tzdata"
       caddycmd "github.com/caddyserver/caddy/v2/cmd"
       _ "github.com/caddyserver/caddy/v2/modules/standard"
       
       // Your plugins
       _ "github.com/example/caddy-plugin"
   )
   
6. Build

   go build -tags=nobadger,nomysql,nopgx
   

Build Tags

From README.md:159, the standard build uses these tags:

-tags=nobadger,nomysql,nopgx

These tags:

• nobadger: Exclude BadgerDB support
• nomysql: Exclude MySQL support
• nopgx: Exclude PostgreSQL support

These databases are used by certain optional modules. Excluding them reduces binary size.

Custom Version Information

From caddy.go:940, you can set a custom version at build time:

go build -ldflags '-X github.com/caddyserver/caddy/v2.CustomVersion=v2.8.0-custom'

The version is reported in:

• caddy version command
• Admin API responses
• Server headers (if configured)

Build Output Location

By default, go build creates the binary in the current directory:

# Build in current directory
go build

# Specify output location
go build -o /usr/local/bin/caddy

Cross-Compilation

Build for different platforms:

# Linux AMD64
GOOS=linux GOARCH=amd64 go build

# Windows AMD64  
GOOS=windows GOARCH=amd64 go build

# macOS ARM64 (Apple Silicon)
GOOS=darwin GOARCH=arm64 go build

# Linux ARM64
GOOS=linux GOARCH=arm64 go build

Optimizing Binary Size

Reduce binary size with build flags:

go build -ldflags=\"-s -w\" -trimpath

• -s: Strip symbol table
• -w: Strip DWARF debugging info
• -trimpath: Remove file system paths from binary

Combine with UPX compression for even smaller binaries:

upx --best --lzma caddy

Static Linking

From README.md:93, Caddy runs with no external dependencies (not even libc):

CGO_ENABLED=0 go build

This creates a fully static binary that can run on any Linux system.

Module Imports

From modules/standard/imports.go:1, standard modules are imported:

package standard

import (
    // standard Caddy modules
    _ "github.com/caddyserver/caddy/v2/caddyconfig/caddyfile"
    _ "github.com/caddyserver/caddy/v2/modules/caddyevents"
    _ "github.com/caddyserver/caddy/v2/modules/caddyevents/eventsconfig"
    _ "github.com/caddyserver/caddy/v2/modules/caddyfs"
    _ "github.com/caddyserver/caddy/v2/modules/caddyhttp/standard"
    _ "github.com/caddyserver/caddy/v2/modules/caddypki"
    _ "github.com/caddyserver/caddy/v2/modules/caddypki/acmeserver"
    _ "github.com/caddyserver/caddy/v2/modules/caddytls"
    _ "github.com/caddyserver/caddy/v2/modules/caddytls/distributedstek"
    _ "github.com/caddyserver/caddy/v2/modules/caddytls/standardstek"
    _ "github.com/caddyserver/caddy/v2/modules/filestorage"
    _ "github.com/caddyserver/caddy/v2/modules/logging"
    _ "github.com/caddyserver/caddy/v2/modules/metrics"
)

The blank imports (_) trigger init() functions that register modules.

Verification

After building, verify your binary:

# Check version
./caddy version

# List all modules
./caddy list-modules

# Validate a config
./caddy validate --config Caddyfile

# Test run
./caddy run --config Caddyfile

Troubleshooting

Version Shows “unknown”

From README.md:112, this happens with simple go build. Use xcaddy or manual steps for version info.

Module Not Found

Ensure the module is imported in main.go and run:

go mod tidy

Permission Denied on Ports

Run setcap on the binary (Linux) or use sudo.

Large Binary Size

Use optimization flags and consider excluding unused modules.

Next Steps

xcaddy Tool

Use xcaddy for easier builds with plugins

Custom Builds

Create custom builds with plugins

Module Development

Develop your own modules

Testing Guide

Test your custom builds