diff options
| -rw-r--r-- | cmd/cobra.go | 91 | ||||
| -rw-r--r-- | cmd/commands.go | 11 |
2 files changed, 91 insertions, 11 deletions
diff --git a/cmd/cobra.go b/cmd/cobra.go index ad95ec0d3..437fda97a 100644 --- a/cmd/cobra.go +++ b/cmd/cobra.go @@ -6,15 +6,98 @@ import ( var rootCmd = &cobra.Command{ Use: "caddy", + Long: `Caddy is an extensible server platform written in Go. + +At its core, Caddy merely manages configuration. Modules are plugged +in statically at compile-time to provide useful functionality. Caddy's +standard distribution includes common modules to serve HTTP, TLS, +and PKI applications, including the automation of certificates. + +To run Caddy, use: + + - 'caddy run' to run Caddy in the foreground (recommended). + - 'caddy start' to start Caddy in the background; only do this + if you will be keeping the terminal window open until you run + 'caddy stop' to close the server. + +When Caddy is started, it opens a locally-bound administrative socket +to which configuration can be POSTed via a restful HTTP API (see +https://caddyserver.com/docs/api). + +Caddy's native configuration format is JSON. However, config adapters +can be used to convert other config formats to JSON when Caddy receives +its configuration. The Caddyfile is a built-in config adapter that is +popular for hand-written configurations due to its straightforward +syntax (see https://caddyserver.com/docs/caddyfile). Many third-party +adapters are available (see https://caddyserver.com/docs/config-adapters). +Use 'caddy adapt' to see how a config translates to JSON. + +For convenience, the CLI can act as an HTTP client to give Caddy its +initial configuration for you. If a file named Caddyfile is in the +current working directory, it will do this automatically. Otherwise, +you can use the --config flag to specify the path to a config file. + +Some special-purpose subcommands build and load a configuration file +for you directly from command line input; for example: + + - caddy file-server + - caddy reverse-proxy + - caddy respond + +These commands disable the administration endpoint because their +configuration is specified solely on the command line. + +In general, the most common way to run Caddy is simply: + + $ caddy run + +Or, with a configuration file: + + $ caddy run --config caddy.json + +If running interactively in a terminal, running Caddy in the +background may be more convenient: + + $ caddy start + ... + $ caddy stop + +This allows you to run other commands while Caddy stays running. +Be sure to stop Caddy before you close the terminal! + +Depending on the system, Caddy may need permission to bind to low +ports. One way to do this on Linux is to use setcap: + + $ sudo setcap cap_net_bind_service=+ep $(which caddy) + +Remember to run that command again after replacing the binary. + +See the Caddy website for tutorials, configuration structure, +syntax, and module documentation: https://caddyserver.com/docs/ + +Custom Caddy builds are available on the Caddy download page at: +https://caddyserver.com/download + +The xcaddy command can be used to build Caddy from source with or +without additional plugins: https://github.com/caddyserver/xcaddy + +Where possible, Caddy should be installed using officially-supported +package installers: https://caddyserver.com/docs/install + +Instructions for running Caddy in production are also available: +https://caddyserver.com/docs/running +`, + Example: ` $ caddy run + $ caddy run --config caddy.json + $ caddy reload --config caddy.json + $ caddy stop`, } -const docsHeader = "{{if not .HasParent}} Caddy is an extensible server platform.\n\n{{end}}" const fullDocsFooter = `Full documentation is available at: -https://caddyserver.com/docs/command-line -` +https://caddyserver.com/docs/command-line` func init() { - rootCmd.SetHelpTemplate(docsHeader + rootCmd.HelpTemplate() + "\n" + fullDocsFooter) + rootCmd.SetHelpTemplate(rootCmd.HelpTemplate() + "\n" + fullDocsFooter) } func caddyCmdToCoral(caddyCmd Command) *cobra.Command { diff --git a/cmd/commands.go b/cmd/commands.go index e71923cfa..4ae3a5b37 100644 --- a/cmd/commands.go +++ b/cmd/commands.go @@ -358,25 +358,22 @@ EXPERIMENTAL: May be changed or removed. } if err := doc.GenManTree(rootCmd, &doc.GenManHeader{ Title: "Caddy", - Section: "8", + Section: "8", // https://en.wikipedia.org/wiki/Man_page#Manual_sections }, dir); err != nil { return caddy.ExitCodeFailedQuit, err } return caddy.ExitCodeSuccess, nil }, - Usage: "--directory <directory path>", - Short: "Generates the manual pages of Caddy commands", + Usage: "--directory <path>", + Short: "Generates the manual pages for Caddy commands", Long: ` -Generates the manual pages of Caddy commands into the designated directory tagged into the specified section. +Generates the manual pages for Caddy commands into the designated directory tagged into section 8 (System Administration). The manual page files are generated into the directory specified by the argument of --directory. If the directory does not exist, it will be created. - -The manual pages are sorted into the section specified by the argument of --section. `, Flags: func() *flag.FlagSet { fs := flag.NewFlagSet("manpage", flag.ExitOnError) fs.String("directory", "", "The output directory where the manpages are generated") - fs.String("section", "", "The section number of the generated manual pages") return fs }(), }) |