Learning Caddy - Admin API & Dynamic Configuration

#Introduction

The Caddyfile is the main gateway, but there's another path: the admin API. Through HTTP on port 2019, you can read, replace, and patch Caddy's configuration while it runs — no restart, no downtime. Episode 23 unlocks the power of dynamic configuration.

#Admin API: The Basics

#Endpoints and Access

The admin API is available at localhost:2019 by default. Its main endpoints:

• GET /config/ — read the current configuration.
• POST /load — load an entirely new configuration.
• PATCH /config/... — change part of the configuration.
• POST /stop — stop Caddy gracefully.
• GET /pki/... — certificate information.
• GET /metrics — Prometheus metrics (episode 22).

Example of reading the configuration:

curl http://localhost:2019/config/

curl http://localhost:2019/config/ returns the full JSON of the running configuration.

#Securing the Admin API

By default the admin API only listens on localhost. If it must be reachable remotely, restrict access:

{
    admin 127.0.0.1:2019
}
 
example.com {
    root * /var/www
    file_server
}

#Loading JSON Configuration

#The Native JSON Format

Caddy understands JSON natively. A minimal configuration:

{
    "apps": {
        "http": {
            "servers": {
                "srv0": {
                    "listen": [":8080"],
                    "routes": [
                        {
                            "handle": [
                                {
                                    "handler": "static_response",
                                    "body": "Hello from JSON"
                                }
                            ]
                        }
                    ]
                }
            }
        }
    }
}

This JSON serves a static response on port 8080. JSON structure is far more verbose than the Caddyfile — which is why the Caddyfile remains the primary choice for humans.

#Loading via the API

Send JSON configuration to Caddy:

curl -X POST -H 'Content-Type: application/json' \
     -d @config.json \
     http://localhost:2019/load

curl -X POST -d @config.json loads the new configuration. Changes apply immediately — this is hot reload.

#Hot Reload and Patching

#Replacing Configuration Without Downtime

Two patterns for changing configuration:

• POST /load: replace the entire configuration at once.
• PATCH /config: change only a specific part.

Example of adding a reverse proxy with a patch:

curl -X PATCH -H 'Content-Type: application/json' \
     -d '{"handler": "reverse_proxy", "upstreams": [{"dial": "localhost:8080"}]}' \
     http://localhost:2019/config/apps/http/servers/srv0/routes/0/handle/0

PATCH targets a specific JSON path and replaces only that part. Active connections aren't interrupted — Caddy handles the transition seamlessly.

#The Caddyfile Adapter

For convenience, send a Caddyfile and let Caddy adapt it:

curl -X POST -H 'Content-Type: text/caddyfile' \
     --data-binary @Caddyfile \
     http://localhost:2019/load

--data-binary @Caddyfile with the text/caddyfile content type tells Caddy to adapt the Caddyfile to JSON first, then load it. Both approaches are valid — choose based on your needs.

#JSON vs Caddyfile

#When to Use Each

• Caddyfile: for human-readable configuration, version control, and fixed setups.
• JSON: for programmatically generated configuration, automation, and infrastructure integration.
• API: for runtime changes without reloading files.

You can see the JSON produced from a Caddyfile:

caddy adapt --config Caddyfile --pretty

caddy adapt --pretty prints readable JSON. This is the best way to learn the JSON structure from Caddyfiles you already know.

#Automation and Multi-Tenancy

#CI/CD Integration

The admin API fits deployment pipelines:

1. CI builds produce a new Caddyfile or JSON.
2. Validate the configuration (episode 30).
3. Send it to the production Caddy admin API.
4. Changes go live without restart.

#Dynamic Backend Registration

A real scenario: a service mesh registers new backends dynamically:

curl -X POST -H 'Content-Type: application/json' \
     -d '{"dial": "service-b:8081"}' \
     http://localhost:2019/config/apps/http/servers/srv0/routes/0/handle/0/upstreams

Per-upstream PATCH/POST endpoints let you add and remove backends without touching the entire configuration. This is the foundation of the dynamic service discovery used in orchestration.

#Infrastructure as Code

Combine the Caddyfile (version control) and the admin API (runtime) for complete Infrastructure as Code: version-controlled configuration in the repository, runtime changes made through the documented API, and the final state readable back via GET /config/.

#Conclusion

Episode 23 opened up the admin API: configuration and metrics endpoints, loading and replacing JSON with POST /load and PATCH, hot reload without downtime, the JSON vs Caddyfile comparison with the adapter, and scenarios for CI/CD, dynamic backends, and multi-tenancy.

Key takeaways:

• The admin API runs at localhost:2019 by default.
• POST /load replaces configuration, PATCH changes part of it.
• Changes apply without downtime.
• caddy adapt --pretty converts a Caddyfile to JSON.
• Never expose the admin API publicly without protection.
• The API enables dynamic backends and Infrastructure as Code.

In the next episode, episode 24, we'll cover PHP-FPM integration — the php_fastcgi directive, connections via Unix socket and TCP, PHP-FPM setup with pools, WordPress, Laravel, and Symfony patterns with try_files, and OPcache and FPM process management optimization.