command

README

caddy-exec

Caddy v2 module for running one-off commands.

Installation

xcaddy build \
    --with github.com/abiosoft/caddy-exec

Usage

Commands can be configured to be triggered globally during startup/shutdown or by via a route.

They can also be configured to run in the background or foreground and to be terminated after a timeout.

⚠ startup commands running on foreground will prevent Caddy from starting if they exit with an error.

Caddyfile

exec [<matcher>] [<command> [<args...>]] {
    command     <command> [<args...>]
    args        <args...>
    directory   <directory>
    timeout     <timeout>
    log         <log output module>
    err_log     <log output module>
    foreground
    pass_thru
    startup
    shutdown
}

• matcher - Caddyfile matcher. When set, this command runs when there is an http request at the current route or the specified matcher. You may leverage other matchers to protect the endpoint.
• command - command to run
• args... - command arguments
• directory - directory to run the command from
• timeout - timeout to terminate the command's process. Default is 10s. A timeout of 0 runs indefinitely.
• log - Caddy log output module for standard output log. Defaults to stderr.
• err_log - Caddy log output module for standard error log. Defaults to the value of log (standard output log).
• foreground - if present, runs the command in the foreground. For commands at http endpoints, the command will exit before the http request is responded to.
• pass_thru - if present, enables pass-thru mode, which continues to the next HTTP handler in the route instead of responding directly
• startup - if present, run the command at startup. Ignored in routes.
• shutdown - if present, run the command at shutdown. Ignored in routes.

Example

exec can run at start via the global directive.

{
  exec hugo generate --destination=/home/user/site/public {
      timeout 0 # don't timeout
  }
}

exec can be the last action of a route block.

route /update {
    ... # other directives e.g. for authentication
    exec git pull origin master {
        log file /var/logs/hugo.log
    }
}

API/JSON

As a top level app for startup and shutdown commands.

{
  "apps": {
    "http": { ... },
    // app configuration
    "exec": {
      // list of commands
      "commands": [
        // command configuration
        {
          // command to execute
          "command": "hugo",
          // [optional] command arguments
          "args": [
            "generate",
            "--destination=/home/user/site/public"
          ],
          // when to run the command, can include 'startup' or 'shutdown'
          "at": ["startup"],

          // [optional] directory to run the command from. Default is the current directory.
          "directory": "",
          // [optional] if the command should run on the foreground. Default is false.
          "foreground": false,
          // [optional] if the middleware should respond directly or pass the request on to the next handler in the route. Default is false.
          "pass_thru": false,
          // [optional] timeout to terminate the command's process. Default is 10s.
          "timeout": "10s",
          // [optional] log output module config for standard output. Default is `stderr` module.
          "log": {
            "output": "file",
            "filename": "/var/logs/hugo.log"
          },
          // [optional] log output module config for standard error. Default is the value of `log`.
          "err_log": {
            "output": "stderr"
          }
        }
      ]
    }
  }
}

As an handler within a route.

{
  ...
  "routes": [
    {
      "handle": [
        // exec configuration for an endpoint route
        {
          // required to inform caddy the handler is `exec`
          "handler": "exec",
          // command to execute
          "command": "git",
          // command arguments it's also possible to use 
          // caddy variables like {http.request.uuid}
          "args": ["pull", "origin", "master", "# {http.request.uuid}"],

          // [optional] directory to run the command from. Default is the current directory.
          "directory": "/home/user/site/public",
          // [optional] if the command should run on the foreground. Default is false.
          "foreground": true,
          // [optional] if the middleware should respond directly or pass the request on to the next handler in the route. Default is false.
          "pass_thru": true,
          // [optional] timeout to terminate the command's process. Default is 10s.
          "timeout": "5s",
          // [optional] log output module config for standard output. Default is `stderr` module.
          "log": {
            "output": "file",
            "filename": "/var/logs/hugo.log"
          },
          // [optional] log output module config for standard error. Default is the value of `log`.
          "err_log": {
            "output": "stderr"
          }
        }
      ],
      "match": [
        {
          "path": ["/update"]
        }
      ]
    }
  ]
}

Dynamic Configuration

Caddy supports dynamic zero-downtime configuration reloads and it is possible to modify exec's configurations at runtime.

exec intelligently determines when Caddy is starting and shutting down. i.e. startup and shutdown commands do not get triggered during configuration reload, only during Caddy's actual startup and shutdown.

License

Apache 2

Documentation

Index

• type App
  • func (a App) CaddyModule() caddy.ModuleInfo
  • func (a *App) Provision(ctx caddy.Context) error
  • func (a App) Start() error
  • func (a *App) Stop() error
  • func (a App) Validate() error
• type Cmd
  • func (c *Cmd) UnmarshalCaddyfile(d *caddyfile.Dispenser) error
• type Middleware
  • func (Middleware) CaddyModule() caddy.ModuleInfo
  • func (m *Middleware) Cleanup() error
  • func (m *Middleware) Provision(ctx caddy.Context) error
  • func (m Middleware) ServeHTTP(w http.ResponseWriter, r *http.Request, next caddyhttp.Handler) error
  • func (m Middleware) Validate() error
• type Runner

Types

type App

type App struct {
	Commands []Cmd `json:"commands,omitempty"`
	// contains filtered or unexported fields
}

App is top level module that runs shell commands.

func (App) CaddyModule

func (a App) CaddyModule() caddy.ModuleInfo

CaddyModule implements caddy.ModuleInfo

func (*App) Provision

func (a *App) Provision(ctx caddy.Context) error

Provision implements caddy.Provisioner

func (App) Start

func (a App) Start() error

Start starts the app.

func (*App) Stop

func (a *App) Stop() error

Stop stops the app.

func (App) Validate

func (a App) Validate() error

Validate implements caddy.Validator

type Cmd

type Cmd struct {
	// The command to run.
	Command string `json:"command,omitempty"`

	// The command args.
	Args []string `json:"args,omitempty"`

	// The directory to run the command from.
	// Defaults to current directory.
	Directory string `json:"directory,omitempty"`

	// If the command should run in the foreground.
	// By default, commands run in the background and doesn't
	// affect Caddy.
	// Setting this makes the command run in the foreground.
	// Note that failure of a startup command running in the
	// foreground may prevent Caddy from starting.
	Foreground bool `json:"foreground,omitempty"`

	// Enables pass-thru mode, which continues to the next HTTP
	// handler in the route instead of responding directly
	PassThru bool `json:"pass_thru,omitempty"`

	// Timeout for the command. The command will be killed
	// after timeout has elapsed if it is still running.
	// Defaults to 10s.
	Timeout string `json:"timeout,omitempty"`

	// When the command should run. This can contain either of
	// "startup" or "shutdown".
	At []string `json:"at,omitempty"`

	// Standard output log.
	StdWriterRaw json.RawMessage `json:"log,omitempty" caddy:"namespace=caddy.logging.writers inline_key=output"`

	// Standard error log.
	ErrWriterRaw json.RawMessage `json:"err_log,omitempty" caddy:"namespace=caddy.logging.writers inline_key=output"`
	// contains filtered or unexported fields
}

Cmd is the module configuration

func (*Cmd) UnmarshalCaddyfile

func (c *Cmd) UnmarshalCaddyfile(d *caddyfile.Dispenser) error

UnmarshalCaddyfile configures the handler directive from Caddyfile. Syntax:

  exec [<matcher>] [<command> [<args...>]] {
    command     <text>
    args        <text>...
    directory   <text>
    timeout     <duration>
    log         <log output module>
    err_log     <log output module>
    foreground
    pass_thru
    startup
    shutdown
}

type Middleware

type Middleware struct {
	Cmd
}

Middleware implements an HTTP handler that runs shell command.

func (Middleware) CaddyModule

func (Middleware) CaddyModule() caddy.ModuleInfo

CaddyModule returns the Caddy module information.

func (*Middleware) Cleanup

func (m *Middleware) Cleanup() error

Cleanup implements caddy.Cleanup TODO: ensure all running processes are terminated.

func (*Middleware) Provision

func (m *Middleware) Provision(ctx caddy.Context) error

Provision implements caddy.Provisioner.

func (Middleware) ServeHTTP

func (m Middleware) ServeHTTP(w http.ResponseWriter, r *http.Request, next caddyhttp.Handler) error

ServeHTTP implements caddyhttp.MiddlewareHandler.

func (Middleware) Validate

func (m Middleware) Validate() error

Validate implements caddy.Validator

type Runner

type Runner interface {
	Run() error
}

Runner runs a command.