Caddy.Admin.Api (Caddy v2.3.1)

View Source

High-level interface to the Caddy Admin API.

Provides a convenient Elixir API for interacting with Caddy's admin endpoints, including configuration management, server control, and health monitoring.

Features

  • Configuration loading and reloading
  • Caddyfile adaptation (convert to JSON)
  • Health checks and server information
  • Telemetry integration for monitoring
  • Mock support for testing via RequestBehaviour

Examples 

# Get current configuration
{:ok, config} = Caddy.Admin.Api.get_config()

# Load new configuration
Caddy.Admin.Api.load(new_config)

# Adapt Caddyfile to JSON
{:ok, json_config} = Caddy.Admin.Api.adapt(caddyfile_content)

# Check server health
{:ok, status} = Caddy.Admin.Api.health_check()

Summary

Functions

adapt(conf)

Adapts a configuration to JSON without running it

api()

Admin API

POST /load Sets or replaces the active configuration
POST /stop Stops the active configuration and exits the process
GET /config/[path] Exports the config at the named path
POST /config/[path] Sets or replaces object; appends to array
PUT /config/[path] Creates new object; inserts into array
PATCH /config/[path] Replaces an existing object or array element
DELETE /config/[path] Deletes the value at the named path
Using @id in JSON Easily traverse into the config structure
Concurrent config changes Avoid collisions when making unsynchronized changes to config
POST /adapt Adapts a configuration to JSON without running it
GET /pki/ca/<id> Returns information about a particular PKI app CA
GET /pki/ca/<id>/certificates Returns the certificate chain of a particular PKI app CA
GET /reverse_proxy/upstreams Returns the current status of the configured proxy upstreams
delete_config()
delete_config(path)

Delete the config at the named path

get(path)

Get info from caddy server

get_config()
get_config(path)

Exports the config at the named path

get_metrics(endpoint \\ "/metrics")

Fetch Prometheus metrics from Caddy's metrics endpoint.

health_check()

Check server health status

load(conf)

Sets or replaces the active configuration

patch_config(data)
patch_config(path, data)

Patch the config at the named path

post_config(data)
post_config(path, data)

Post the config at the named path

put_config(data)
put_config(path, data)

Put the config at the named path

server_info()

Get detailed server info including version and uptime

stop()

Stops the active configuration and exits the process

Functions

adapt(conf)

@spec adapt(binary()) :: map()

Adapts a configuration to JSON without running it

api()

Admin API 

POST /load Sets or replaces the active configuration
POST /stop Stops the active configuration and exits the process
GET /config/[path] Exports the config at the named path
POST /config/[path] Sets or replaces object; appends to array
PUT /config/[path] Creates new object; inserts into array
PATCH /config/[path] Replaces an existing object or array element
DELETE /config/[path] Deletes the value at the named path
Using @id in JSON Easily traverse into the config structure
Concurrent config changes Avoid collisions when making unsynchronized changes to config
POST /adapt Adapts a configuration to JSON without running it
GET /pki/ca/<id> Returns information about a particular PKI app CA
GET /pki/ca/<id>/certificates Returns the certificate chain of a particular PKI app CA
GET /reverse_proxy/upstreams Returns the current status of the configured proxy upstreams

delete_config()

delete_config(path)

Delete the config at the named path

get(path)

Get info from caddy server

get_config()

get_config(path)

Exports the config at the named path

get_metrics(endpoint \\ "/metrics")

@spec get_metrics(binary()) :: {:ok, binary()} | {:error, term()}

Fetch Prometheus metrics from Caddy's metrics endpoint.

The metrics endpoint must be enabled in Caddy configuration:

{
  servers {
    metrics
  }
}

Returns the raw Prometheus exposition format text.

health_check()

@spec health_check() :: {:ok, map()} | {:error, binary()}

Check server health status

load(conf)

@spec load(map() | binary()) :: Caddy.Admin.Request.t()

Sets or replaces the active configuration

patch_config(data)

patch_config(path, data)

Patch the config at the named path

post_config(data)

post_config(path, data)

Post the config at the named path

put_config(data)

put_config(path, data)

Put the config at the named path

server_info()

@spec server_info() :: {:ok, map()} | {:error, binary()}

Get detailed server info including version and uptime

stop()

Stops the active configuration and exits the process