Caddy.Config (Caddy v2.3.1)

View Source

Structured configuration for Caddy reverse proxy server.

Configuration is stored in 3 distinct parts that are assembled into a Caddyfile:

  1. Global options (global) - Content for the global options block { ... }
  2. Additionals (additionals) - List of snippets, imports, matchers, etc.
  3. Sites (sites) - List of site configurations with address and content

Example 

config = %Caddy.Config{
  global: """
  debug
  admin unix//tmp/caddy.sock
  """,
  additionals: [
    %{name: "common", content: "(common) {\n  header X-Frame-Options DENY\n}"},
    %{name: "security", content: "(security) {\n  header X-Content-Type-Options nosniff\n}"}
  ],
  sites: [
    %{address: "example.com", config: "reverse_proxy localhost:3000"},
    %{address: "api.example.com", config: "reverse_proxy localhost:4000"}
  ]
}

This assembles into:

{
  debug
  admin unix//tmp/caddy.sock
}

(common) {
  header X-Frame-Options DENY
}

(security) {
  header X-Content-Type-Options nosniff
}

example.com {
  reverse_proxy localhost:3000
}

api.example.com {
  reverse_proxy localhost:4000
}

Validation

Configuration is validated by calling the Caddy binary's adapt command, which converts Caddyfile to JSON and catches syntax errors.

Summary

Types

additional()

Additional configuration item (snippet, import, matcher, etc.).

site()

Site configuration map with address and config content.

t()

Functions

adapt(caddyfile_text, caddy_bin \\ nil)

Convert Caddyfile text to JSON using Caddy binary.

admin_url()

Get the admin API URL for external mode.

backup_json_file()

Get backup file path

base_path()

Get configurable base path for caddy files

command(name)

Get a specific command for external mode.

commands()

Get system commands for external mode operations.

default_caddyfile()

Create a default Caddyfile with admin socket configuration.

default_config()

Create a default config struct with admin socket configuration.

env_file()

Get environment file path

etc_path()

Get etc path for configuration files

external_mode?()

Check if running in external mode.

health_interval()

Get the health check interval in milliseconds for external mode.

init_file()

Get init configuration file path

mode()

Get the operating mode for Caddy management.

pid_file()

Get PID file path

priv_path()

Get configurable priv path

run_path()

Get run path for runtime files

saved_json_file()

Get saved JSON configuration file path

share_path()

Get share path (base path)

socket_file()

Get socket file path

tmp_path()

Get tmp path for temporary files

to_caddyfile(config)

Assemble the 3-part configuration into a complete Caddyfile text.

user_home()

See System.user_home/0.

validate_bin(caddy_bin)

Validate Caddy binary path

validate_config(config)

Validate complete configuration

xdg_config_home()

Get XDG config home path

xdg_data_home()

Get XDG data home path

Types

additional()

@type additional() :: %{name: binary(), content: binary()}

Additional configuration item (snippet, import, matcher, etc.).

  • name - A descriptive name for this additional (e.g., "common-headers", "security")
  • content - The actual Caddyfile content

site()

@type site() :: %{address: binary(), config: binary()}

Site configuration map with address and config content.

  • address - The site address (e.g., "example.com", "localhost:8080")
  • config - The site configuration content (without wrapping braces)

t()

@type t() :: %Caddy.Config{
  additionals: [additional()],
  bin: binary() | nil,
  env: [{binary(), binary()}],
  global: binary(),
  sites: [site()]
}

Functions

adapt(caddyfile_text, caddy_bin \\ nil)

@spec adapt(binary(), binary() | nil) :: {:ok, map()} | {:error, term()}

Convert Caddyfile text to JSON using Caddy binary.

This validates the Caddyfile syntax and returns the JSON configuration that Caddy will use internally.

admin_url()

@spec admin_url() :: binary()

Get the admin API URL for external mode.

Supports both TCP and Unix socket connections:

  • "http://localhost:2019" - TCP connection
  • "unix:///path/to/caddy.sock" - Unix domain socket

Falls back to the configured socket_file in embedded mode.

Example 

config :caddy, admin_url: "http://localhost:2019"

backup_json_file()

@spec backup_json_file() :: Path.t()

Get backup file path

base_path()

Get configurable base path for caddy files

command(name)

@spec command(atom()) :: binary() | nil

Get a specific command for external mode.

Returns nil if the command is not configured.

commands()

@spec commands() :: keyword(binary())

Get system commands for external mode operations.

Commands are executed via System.cmd when managing an externally-controlled Caddy.

Example 

config :caddy, commands: [
  start: "systemctl start caddy",
  stop: "systemctl stop caddy",
  restart: "systemctl restart caddy",
  status: "systemctl is-active caddy"
]

default_caddyfile()

@spec default_caddyfile() :: binary()

Create a default Caddyfile with admin socket configuration.

default_config()

@spec default_config() :: t()

Create a default config struct with admin socket configuration.

env_file()

Get environment file path

etc_path()

Get etc path for configuration files

external_mode?()

@spec external_mode?() :: boolean()

Check if running in external mode.

health_interval()

@spec health_interval() :: pos_integer()

Get the health check interval in milliseconds for external mode.

Defaults to 30 seconds.

Example 

config :caddy, health_interval: 60_000

init_file()

Get init configuration file path

mode()

@spec mode() :: :embedded | :external

Get the operating mode for Caddy management.

  • :external (default) - Caddy is managed externally (e.g., systemd), communicate via Admin API
  • :embedded - Caddy binary is managed by this application

External mode is the default because it's safer - it doesn't spawn processes and works with empty configuration (waiting state).

Example 

config :caddy, mode: :embedded

pid_file()

Get PID file path

priv_path()

Get configurable priv path

run_path()

Get run path for runtime files

saved_json_file()

Get saved JSON configuration file path

share_path()

Get share path (base path)

socket_file()

Get socket file path

tmp_path()

Get tmp path for temporary files

to_caddyfile(config)

@spec to_caddyfile(t()) :: binary()

Assemble the 3-part configuration into a complete Caddyfile text.

Combines global options, additional directives, and site configurations into a single Caddyfile string.

Output Format 

{
  <global content>
}

<additional content>

<site1_address> {
  <site1_content>
}

<site2_address> {
  <site2_content>
}

Examples 

iex> config = %Caddy.Config{
...>   global: "debug",
...>   additional: "",
...>   sites: [%{address: "example.com", config: "reverse_proxy localhost:3000"}]
...> }
iex> Caddy.Config.to_caddyfile(config)
"{\n  debug\n}\n\nexample.com {\n  reverse_proxy localhost:3000\n}"

user_home()

See System.user_home/0.

validate_bin(caddy_bin)

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

Validate Caddy binary path

validate_config(config)

@spec validate_config(t()) :: :ok | {:error, binary()}

Validate complete configuration

xdg_config_home()

Get XDG config home path

xdg_data_home()

Get XDG data home path