Adapt Caddyfile text to JSON (validates syntax)

Add an additional (snippet, matcher, etc.)

Add a site configuration

Append content to the Caddyfile

Apply JSON config directly to running Caddy.

Bypasses in-memory config - use for runtime-only changes.

See Caddy.ConfigManager.apply_runtime_config/2.

Backup current configuration to file

Check if in-memory and runtime configs are in sync.

Returns {:ok, :in_sync} if configs match, or {:ok, {:drift_detected, diff}} with information about the differences.

Clear the current configuration, returning to :unconfigured state.

Can only be called from :configured state. Returns an error if called from other states.

Examples

iex> Caddy.clear_config()
:ok
iex> Caddy.get_state()
:unconfigured

Check if a Caddyfile configuration is set.

Returns true when in :configured, :synced, or :degraded state.

Examples

iex> Caddy.configured?()
false

iex> Caddy.set_caddyfile("localhost { respond 200 }")
:ok
iex> Caddy.configured?()
true

Get an additional by name

Get all additionals

Get the assembled Caddyfile configuration

Get current configuration struct

Get global options content

Get JSON config from running Caddy.

Returns the current configuration from the running Caddy process via Admin API.

Get JSON config from running Caddy at specific path.

Examples

{:ok, servers} = Caddy.get_runtime_config("apps/http/servers")

Get a site by address

Get all sites

Get the current application state.

Returns one of:

• :initializing - Library starting up
• :unconfigured - No Caddyfile set, waiting for configuration
• :configured - Caddyfile set, pending sync to Caddy
• :synced - Configuration synced to Caddy, operational
• :degraded - Configuration synced but Caddy not responding

Examples

iex> Caddy.get_state()
:unconfigured

iex> Caddy.set_caddyfile("localhost { respond 200 }")
:ok
iex> Caddy.get_state()
:configured

Check if the system is ready to serve requests.

Returns true only when in :synced state (configuration has been successfully pushed to Caddy).

Examples

iex> Caddy.ready?()
false

iex> Caddy.sync_to_caddy()
:ok
iex> Caddy.ready?()
true

Remove an additional by name

Remove a site by address

@spec restart_server() :: {:ok, pid()} | {:ok, :undefined} | {:error, term()}

Restart Caddy Server

Restore configuration from backup

Rollback to last known good config.

Save current configuration

Set Caddy binary path

Set Caddy binary path and restart server

Set the Caddyfile configuration (parses into 3 parts)

Set configuration struct

Set global options content (without braces)

@spec start(binary()) :: :ignore | {:error, any()} | {:ok, pid()}

Manually Start Caddy Server.

This is useful when you want to start Caddy Server in iex console.

@spec start_link(Keyword.t()) :: :ignore | {:error, any()} | {:ok, pid()}

Start the Caddy supervisor as part of a supervision tree.

@spec stop(term()) :: :ok

Stop Caddy Server

Pull runtime config from Caddy to memory.

DEPRECATED: This function stores JSON in the Caddyfile field, which breaks the text-first design principle. It will be removed in v3.0.0.

The Caddy Admin API returns JSON configuration, but there is no reverse conversion from JSON back to Caddyfile format. Use get_runtime_config/0 to inspect the running configuration instead.

Sync in-memory config to running Caddy.

Adapts the Caddyfile and loads it into the running Caddy instance.

Options

• :backup - If true, backup current runtime config before sync (default: true)
• :force - If true, skip validation (default: false)

Examples

:ok = Caddy.sync_to_caddy()
:ok = Caddy.sync_to_caddy(backup: false)

See Caddy.ConfigManager.sync_to_caddy/1.

Update an existing additional by name, or add if not found

Update an existing site by address, or add if not found

Validate Caddyfile without applying.