Caddy Web Server

Caddy is an extensible platform written in Go designed to serve sites, services, and apps. It functions as a 'server of servers' that can take on the role of any long-running process via modules.

Key characteristics:

• Configuration: Supports dynamic and exportable configuration via an API. While no config files are strictly required, users typically use the Caddyfile format or native JSON configuration. Config adapters allow different formats to be converted into Caddy's native JSON.
• Deployment: Compiles for all major platforms and has no runtime dependencies.

Caddy follows a standard unix-like command line interface. The general syntax for invoking commands is:

caddy <command> [<args...>]

Where:

• <carets> indicate parameters to be replaced by your input.
• [brackets] indicate optional parameters.
• (brackets) indicate required parameters.
• ... indicates a continuation (one or more parameters).
• --flags may have single-letter shortcuts (e.g., -f).

For a quick start, you can run caddy, caddy help, or man caddy (if the manpage is installed).

caddy <command> [<args...]]

The reverse_proxy directive proxies requests to one or more backends. It supports configurable transport, load balancing, health checking, request manipulation, and buffering options.

Basic Syntax:

reverse_proxy [<matcher>] [<upstreams...>] {
    # configuration subdirectives
}

You can specify upstreams directly in the directive line or using the to subdirective.

reverse_proxy localhost:8080 localhost:8081

The route directive allows you to evaluate a group of directives literally and as a single unit. By default, Caddy reorders directives in the Caddyfile to optimize the HTTP handler chain. However, when you need absolute control over the execution order—specifically to ensure one handler runs before another regardless of Caddy's built-in sorting—you should wrap them in a route block.

Key Rules:

• Directives inside a route block are not reordered; they are executed in the exact order they are written.
• Only HTTP handler directives (directives that add handlers or middleware to the chain) can be used inside a route block.
• Subdirectives within a route block are treated as regular directives.

route [<matcher>] {
	<directives...>
}

Caddy is composed of three primary components:

1. Command: The CLI used to launch the process. While the core CLI is minimal, modules can add their own subcommands (e.g., caddy file-server) which may include their own flags and environment variables.
2. Core Library: Manages configuration via Run() and Stop(). It handles top-level JSON fields like admin (for the admin API) and logging.
3. Modules: The functional components of Caddy. Modules are plugins that extend Caddy's configuration structure.

Key distinction: All modules are plugins, but not all plugins are modules. Modules specifically extend the Caddy JSON configuration structure.

Response matchers allow you to filter or classify HTTP responses based on specific criteria. They are typically used within other directives to make decisions about a response as it is being written to the client.

There are two ways to use them:

1. Named Matchers: You declare a matcher with a name (prefixed with @) and then reference that name in a directive. This is useful for reusability.
2. Inline Matchers: You provide the criteria directly within the directive without a prior declaration.

# Named Matcher
@name status 2xx

directive @name {
    ...
}

# Inline Matcher
... status 2xx

The push directive configures Caddy to pre-emptively send resources to the client using HTTP/2 server push. This is useful for reducing latency by sending critical assets (like CSS or JS) before the client explicitly requests them.

Caddy can automatically push resources that are identified via Link headers in the response. It supports the following Link header formats:

• <resource>; as=script
• <resource>; as=script,<resource>; as=style
• <resource>; nopush (Note: nopush prevents the resource from being pushed)
• <resource>;<resource2>;...

Constraints:

• Only same-host resources (starting with /) can be pushed.
• External resources or resources marked with nopush are ignored.
• By default, Caddy automatically carries over safe headers (Accept-Encoding, Accept-Language, Accept, Cache-Control, and User-Agent) to the push requests.

In a Caddyfile, a matcher token can be placed immediately after a directive to limit its scope. Matcher tokens can take three primary forms:

1. Wildcard (*): Matches all requests. This is the default behavior if no matcher is provided, so it is often omitted.
2. Path (/path): Starts with a forward slash to match a request path. Note that path matching is an exact match by default; use a * suffix for prefix matching.
3. Named Matcher (@name): Refers to a pre-defined set of matching criteria defined elsewhere in the site block.

If a directive's syntax documentation shows [<matcher>], the matcher is optional.

# Wildcard (matches everything)
reverse_proxy localhost:9000

# Path (matches /api/ prefix)
reverse_proxy /api/* localhost:9000

# Named (matches criteria defined in @postfoo)
reverse_proxy @postfoo localhost:9000

To define multiple sites, you must wrap each site's configuration in curly braces { }. When using curly braces, the site address must appear before the opening brace, and all directives must reside inside the braces.

You can also group multiple addresses that share the same configuration by separating them with commas.

# Individual sites
:8080 {
	respond "I am 8080"
}

:8081 {
	respond "I am 8081"
}

# Multiple addresses sharing one config
:8080, :8081 {
	...
}