Caddy.Server.External (Caddy v2.3.1)

View Source

External Caddy Server management.

Manages a Caddy instance that is started and controlled externally (e.g., by systemd, launchd, or another process manager).

This GenServer:

  • Monitors Caddy health via the Admin API
  • Executes system commands for lifecycle operations
  • Pushes configuration when Caddy becomes available
  • Emits telemetry events for observability

Configuration 

config :caddy, mode: :external
config :caddy, admin_url: "http://localhost:2019"
config :caddy, health_interval: 30_000
config :caddy, commands: [
  start: "systemctl start caddy",
  stop: "systemctl stop caddy",
  restart: "systemctl restart caddy",
  status: "systemctl is-active caddy"
]

State

The server maintains:

  • caddy_status - Current known status (:running, :stopped, :unknown)
  • config_pushed - Whether initial config has been pushed
  • last_health_check - Timestamp of last successful health check

Summary

Types

state()

Functions

check_status()

Check the current status of the external Caddy instance.

child_spec(init_arg)

Returns a specification to start this module under a supervisor.

execute_command(command)

Execute a lifecycle command.

get_caddyfile()

Get Caddyfile content via Admin API.

health_check()

Trigger an immediate health check.

push_config()

Push configuration to the running Caddy instance.

restart_caddy()

Restart the external Caddy instance using the configured restart command.

start_caddy()

Start the external Caddy instance using the configured start command.

start_link(opts \\ [])

Start the external server GenServer.

stop_caddy()

Stop the external Caddy instance using the configured stop command.

Types

state()

@type state() :: %{
  caddy_status: :running | :stopped | :unknown,
  config_pushed: boolean(),
  last_health_check: DateTime.t() | nil,
  health_interval: pos_integer()
}

Functions

check_status()

@spec check_status() :: :running | :stopped | :unknown

Check the current status of the external Caddy instance.

child_spec(init_arg)

Returns a specification to start this module under a supervisor.

See Supervisor.

execute_command(command)

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

Execute a lifecycle command.

Available commands: :start, :stop, :restart, :status

get_caddyfile()

@spec get_caddyfile() :: binary()

Get Caddyfile content via Admin API.

health_check()

@spec health_check() :: :ok

Trigger an immediate health check.

push_config()

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

Push configuration to the running Caddy instance.

restart_caddy()

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

Restart the external Caddy instance using the configured restart command.

start_caddy()

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

Start the external Caddy instance using the configured start command.

start_link(opts \\ [])

Start the external server GenServer.

stop_caddy()

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

Stop the external Caddy instance using the configured stop command.