Caddy Fundamentals

Caddy is a web server and reverse proxy with automatic HTTPS. You give it a site address and request-handling rules. It listens for traffic, secures qualifying sites, and either returns a response or forwards the request to another service.

Use this mental model: Caddy is a programmable front door. The site address chooses the door. Matchers classify each request. Directives decide what happens next. Automatic HTTPS secures the public path to that door when the domain and network are ready.

Why Caddy exists

A web-facing application needs more than application code. Something must accept connections, negotiate TLS, serve static assets, route requests, and keep configuration changes safe. Caddy combines those edge responsibilities in one extensible server.

Caddy is especially useful when you want:

• automatic certificate provisioning, renewal, and HTTP-to-HTTPS redirects;
• a readable Caddyfile for hand-managed configuration;
• native JSON and an HTTP administration API for automation;
• static file serving;
• reverse proxying to one or more application servers;
• configuration reloads without planned downtime.

Caddy is not your application runtime or database. It usually sits in front of those systems. It handles the connection and routing layer while your application handles business behavior.

The request path

A common deployment looks like this:

client → DNS → Caddy → application service
                  ↘ static files

DNS must send the domain to the machine running Caddy. For public Automatic HTTPS, ports 80 and 443 must reach Caddy. Caddy also needs writable, persistent data storage for certificates and keys.

When a request arrives, Caddy selects the configured site and runs the applicable HTTP handlers. A handler might return a fixed response, serve a file, redirect the client, or proxy the request upstream.

Two configuration layers

Caddy's native configuration format is JSON. The running process exposes an administration API that accepts and exports configuration. The default API address is localhost:2019.

The Caddyfile is a human-friendly configuration format. A config adapter converts it to native JSON before Caddy loads it. This gives you two useful working styles:

• Use a Caddyfile when people maintain a concise configuration in a file.
• Use native JSON and the API when software needs precise, programmable changes.

The Caddyfile is easier to read, but it does not expose every possible JSON configuration shape. Learn both layers so you know what Caddy actually runs.

Reading a Caddyfile

A Caddyfile contains one or more site blocks. Each site block begins with a site address. Directives inside the block configure behavior for that site.

example.com {
    encode zstd gzip
    reverse_proxy localhost:8080
}

example.com is the site address. encode and reverse_proxy are directives. Because the address contains a qualifying public domain, Caddy activates Automatic HTTPS unless configuration explicitly prevents it.

You can configure several sites in one file:

example.com {
    root * /srv/example
    file_server
}

api.example.com {
    reverse_proxy localhost:8080
}

The first site serves files from disk. The second sends requests to an application on the local machine.

Matchers and handler order

A directive applies to every request in its site block unless you attach a matcher. Matchers let you select requests by properties such as path, method, host, header, or expression.

example.com {
    reverse_proxy /api/* localhost:8080
    file_server
}

The path matcher limits reverse_proxy to requests under /api/. Other requests can reach file_server.

Caddyfile adapter order matters. HTTP handler directives are normally sorted according to Caddy's default directive order, not their visual order in the file. A route block preserves literal handler order when you need exact sequencing.

Automatic HTTPS

Automatic HTTPS does two main jobs for qualifying names:

1. It obtains and renews certificates.
2. It adds HTTP-to-HTTPS redirects.

For a public domain, set correct DNS records and make ports 80 and 443 reachable. Keep Caddy's data directory persistent. If that storage disappears, Caddy loses locally stored certificate state and keys.

Local names such as localhost use Caddy's local certificate authority. A client trusts those certificates only after it trusts the local root certificate. Containers and other machines do not inherit that trust automatically.

Automatic HTTPS reduces certificate work, but it does not fix DNS, firewall, storage, or application security mistakes. You still own those boundaries.

Static files and reverse proxying

For a static site, root sets the filesystem root and file_server serves files beneath it:

example.com {
    root * /srv/example
    file_server
}

For an application, reverse_proxy forwards requests to an upstream:

api.example.com {
    reverse_proxy localhost:8080
}

The upstream is the service that receives proxied requests. Caddy can proxy to multiple upstreams and offers load balancing and health-check options. Those features require deliberate failure and retry design beyond this fundamentals course.

Safe configuration changes

Use caddy validate to load and provision a candidate configuration without starting it. This catches more than syntax conversion errors.

Use caddy reload to replace the configuration of a running process. A successful reload changes configuration without planned downtime. If the new configuration fails, Caddy rolls back to the previous configuration.

Do not stop and restart a production process just to apply a Caddyfile change. When Caddy runs as a service, use the service's reload path. A service manager also starts Caddy after a reboot and captures process logs.

Where Caddy fits well

Caddy is a strong fit for small and medium web deployments, internal services, development HTTPS, and automated edge configuration. Its defaults remove much certificate plumbing from routine deployments.

Consider the surrounding system before choosing it. You may need a different or additional layer when an organization depends on a vendor-specific appliance, a managed cloud gateway, a specialized traffic policy engine, or existing operational expertise around another proxy.

The right question is not whether Caddy can receive HTTP traffic. It can. Ask whether its configuration model, extension set, observability, and operating model fit your environment.