Caddy.Admin.Resources (Caddy v2.3.1)

Domain-specific helpers for common Caddy configuration paths.

Provides typed access to Caddy's JSON configuration structure, making it easier to work with apps, servers, routes, and TLS settings.

Examples

# Get all HTTP servers
{:ok, servers} = Caddy.Admin.Resources.get_http_servers()

# Add a route to a server
route = %{"match" => [%{"path" => ["/api/*"]}], "handle" => [...]}
{:ok, _} = Caddy.Admin.Resources.add_route("srv0", route)

# Get TLS configuration
{:ok, tls} = Caddy.Admin.Resources.get_tls()

Caddy Config Structure

The typical Caddy JSON config structure:

%{
  "admin" => %{"listen" => "unix//tmp/caddy.sock"},
  "apps" => %{
    "http" => %{
      "servers" => %{
        "srv0" => %{
          "listen" => [":443"],
          "routes" => [...]
        }
      }
    },
    "tls" => %{...}
  }
}

Summary

Functions

add_route(server_name, route)

Add a route to an HTTP server (appends to routes array).

create_http_server(name, config)

Create a new HTTP server.

delete_app(name)

Delete a specific app.

delete_http_server(name)

Delete an HTTP server.

delete_route(server_name, index)

Delete a route at a specific index.

get_admin()

Get admin settings.

get_app(name)

Get a specific app by name.

get_apps()

Get all configured apps.

get_http_server(name)

Get a specific HTTP server by name.

get_http_servers()

Get all HTTP servers.

get_pki_ca(ca_id)

Get information about a PKI CA.

get_pki_certificates(ca_id)

Get the certificate chain of a PKI CA.

get_route(server_name, index)

Get a specific route by index.

get_routes(server_name)

Get all routes for an HTTP server.

get_tls()

Get TLS app configuration.

get_tls_automation()

Get TLS automation configuration.

get_upstreams()

Get current status of reverse proxy upstreams.

insert_route(server_name, index, route)

Insert a route at a specific index.

set_admin(config)

Set admin settings.

set_app(name, config)

Set or replace a specific app configuration.

set_http_server(name, config)

Set or replace an HTTP server configuration.

set_tls(config)

Set TLS app configuration.

set_tls_automation(config)

Set TLS automation configuration.

update_route(server_name, index, route)

Update a route at a specific index.

Functions

add_route(server_name, route)

@spec add_route(String.t(), map()) :: {:ok, map()} | {:error, term()}

Add a route to an HTTP server (appends to routes array).

Examples

route = %{
  "match" => [%{"path" => ["/api/*"]}],
  "handle" => [%{"handler" => "reverse_proxy", "upstreams" => [%{"dial" => "localhost:3000"}]}]
}
{:ok, _} = Caddy.Admin.Resources.add_route("srv0", route)

create_http_server(name, config)

@spec create_http_server(String.t(), map()) :: {:ok, map()} | {:error, term()}

Create a new HTTP server.

delete_app(name)

@spec delete_app(String.t()) :: :ok | {:error, term()}

Delete a specific app.

delete_http_server(name)

@spec delete_http_server(String.t()) :: :ok | {:error, term()}

Delete an HTTP server.

delete_route(server_name, index)

@spec delete_route(String.t(), non_neg_integer()) :: :ok | {:error, term()}

Delete a route at a specific index.

get_admin()

@spec get_admin() :: {:ok, map()} | {:error, term()}

Get admin settings.

get_app(name)

@spec get_app(String.t()) :: {:ok, map()} | {:error, term()}

Get a specific app by name.

Examples

{:ok, http_app} = Caddy.Admin.Resources.get_app("http")
{:ok, tls_app} = Caddy.Admin.Resources.get_app("tls")

get_apps()

@spec get_apps() :: {:ok, map()} | {:error, term()}

Get all configured apps.

Returns the apps section of the Caddy config.

get_http_server(name)

@spec get_http_server(String.t()) :: {:ok, map()} | {:error, term()}

Get a specific HTTP server by name.

Examples

{:ok, server} = Caddy.Admin.Resources.get_http_server("srv0")

get_http_servers()

@spec get_http_servers() :: {:ok, map()} | {:error, term()}

Get all HTTP servers.

Returns the servers map from the HTTP app.

get_pki_ca(ca_id)

@spec get_pki_ca(String.t()) :: {:ok, map()} | {:error, term()}

Get information about a PKI CA.

Examples

{:ok, ca_info} = Caddy.Admin.Resources.get_pki_ca("local")

get_pki_certificates(ca_id)

@spec get_pki_certificates(String.t()) :: {:ok, list()} | {:error, term()}

Get the certificate chain of a PKI CA.

get_route(server_name, index)

@spec get_route(String.t(), non_neg_integer()) :: {:ok, map()} | {:error, term()}

Get a specific route by index.

get_routes(server_name)

@spec get_routes(String.t()) :: {:ok, list()} | {:error, term()}

Get all routes for an HTTP server.

get_tls()

@spec get_tls() :: {:ok, map()} | {:error, term()}

Get TLS app configuration.

get_tls_automation()

@spec get_tls_automation() :: {:ok, map()} | {:error, term()}

Get TLS automation configuration.

get_upstreams()

@spec get_upstreams() :: {:ok, map()} | {:error, term()}

Get current status of reverse proxy upstreams.

This endpoint returns health status of configured upstream servers.

insert_route(server_name, index, route)

@spec insert_route(String.t(), non_neg_integer(), map()) ::
  {:ok, map()} | {:error, term()}

Insert a route at a specific index.

set_admin(config)

@spec set_admin(map()) :: {:ok, map()} | {:error, term()}

Set admin settings.

set_app(name, config)

@spec set_app(String.t(), map()) :: {:ok, map()} | {:error, term()}

Set or replace a specific app configuration.

set_http_server(name, config)

@spec set_http_server(String.t(), map()) :: {:ok, map()} | {:error, term()}

Set or replace an HTTP server configuration.

set_tls(config)

@spec set_tls(map()) :: {:ok, map()} | {:error, term()}

Set TLS app configuration.

set_tls_automation(config)

@spec set_tls_automation(map()) :: {:ok, map()} | {:error, term()}

Set TLS automation configuration.

update_route(server_name, index, route)

@spec update_route(String.t(), non_neg_integer(), map()) ::
  {:ok, map()} | {:error, term()}

Update a route at a specific index.