Package caddy implements the Caddy web server as a service in your own Go programs.
To use this package, follow a few simple steps:
- Set the AppName and AppVersion variables.
- Call LoadCaddyfile() to get the Caddyfile (it might have been piped in as part of a restart). You should pass in your own Caddyfile loader.
- Call caddy.Start() to start Caddy, caddy.Stop() to stop it, or caddy.Restart() to restart it.
You should use caddy.Wait() to wait for all Caddy servers to quit before your process exits.
- func IsRestart() bool
- func Restart(newCaddyfile Input) error
- func Start(cdyfile Input) (err error)
- func Stop() error
- func TrapSignals()
- func Wait()
- type CaddyfileInput
- type Input
- type SetupFunc
const ( // DefaultHost is the default host. DefaultHost = "" // DefaultPort is the default port. DefaultPort = "2015" // DefaultRoot is the default root folder. DefaultRoot = "." )
const ( // DefaultConfigFile is the name of the configuration file that is loaded // by default if no other file is specified. DefaultConfigFile = "Caddyfile" )
var ( // AppName is the name of the application. AppName string // AppVersion is the version of the application. AppVersion string // Quiet when set to true, will not show any informative output on initialization. Quiet bool // HTTP2 indicates whether HTTP2 is enabled or not. HTTP2 bool // TODO: temporary flag until http2 is standard // PidFile is the path to the pidfile to create. PidFile string // GracefulTimeout is the maximum duration of a graceful shutdown. GracefulTimeout time.Duration )
Configurable application parameters
var ( // Root is the site root Root = DefaultRoot // Host is the site host Host = DefaultHost // Port is the site port Port = DefaultPort )
These defaults are configurable through the command line
func IsRestart() bool
IsRestart returns whether this process is, according to env variables, a fork as part of a graceful restart.
Restart restarts the entire application; gracefully with zero downtime if on a POSIX-compatible system, or forcefully if on Windows but with imperceptibly-short downtime.
The restarted application will use newCaddyfile as its input configuration. If newCaddyfile is nil, the current (existing) Caddyfile configuration will be used.
Note: The process must exist in the same place on the disk in order for this to work. Thus, multiple graceful restarts don't work if executing with `go run`, since the binary is cleaned up when `go run` sees the initial parent process exit.
Start starts Caddy with the given Caddyfile. If cdyfile is nil, the LoadCaddyfile function will be called to get one.
This function blocks until all the servers are listening.
Note (POSIX): If Start is called in the child process of a restart more than once within the duration of the graceful cutoff (i.e. the child process called Start a first time, then called Stop, then Start again within the first 5 seconds or however long GracefulTimeout is) and the Caddyfiles have at least one listener address in common, the second Start may fail with "address already in use" as there's no guarantee that the parent process has relinquished the address before the grace period ends.
func Stop() error
Stop stops all servers. It blocks until they are all stopped. It does NOT execute shutdown callbacks that may have been configured by middleware (they must be executed separately).
func TrapSignals ¶
TrapSignals create signal handlers for all applicable signals for this system. If your Go program uses signals, this is a rather invasive function; best to implement them yourself in that case. Signals are not required for the caddy package to function properly, but this is a convenient way to allow the user to control this package of your program.
type CaddyfileInput ¶
CaddyfileInput represents a Caddyfile as input and is simply a convenient way to implement the Input interface.
func DefaultInput ¶
func DefaultInput() CaddyfileInput
DefaultInput returns the default Caddyfile input to use when it is otherwise empty or missing. It uses the default host and port (depends on host, e.g. localhost is 2015, otherwise 443) and root.
IsFile returns true if the original input was a real file on the file system.
Input represents a Caddyfile; its contents and file path (which should include the file name at the end of the path). If path does not apply (e.g. piped input) you may use any understandable value. The path is mainly used for logging, error messages, and debugging.
func CaddyfileFromPipe ¶
CaddyfileFromPipe loads the Caddyfile input from f if f is not interactive input. f is assumed to be a pipe or stream, such as os.Stdin. If f is not a pipe, no error is returned but the Input value will be nil. An error is only returned if there was an error reading the pipe, even if the length of what was read is 0.
func LoadCaddyfile ¶
LoadCaddyfile loads a Caddyfile, prioritizing a Caddyfile piped from stdin as part of a restart (only happens on first call to LoadCaddyfile). If it is not a restart, this function tries calling the user's loader function, and if that returns nil, then this function resorts to the default configuration. Thus, if there are no other errors, this function always returns at least the default Caddyfile.
Source Files ¶
Package letsencrypt integrates Let's Encrypt functionality into Caddy with first-class support for creating and renewing certificates automatically.
|Package letsencrypt integrates Let's Encrypt functionality into Caddy with first-class support for creating and renewing certificates automatically.|
Package parse provides facilities for parsing configuration files.
|Package parse provides facilities for parsing configuration files.|