mirror of https://github.com/caddyserver/caddy.git
cmd: Enhance CLI docs
This commit is contained in:
Matthew Holt
parent
d605ebe75a
commit
687a4b9e81
91
cmd/cobra.go
91
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 {
|
||||
|
|
|
|||
|
|
@ -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
|
||||
}(),
|
||||
})
|
||||
|
|
|
|||
Loading…
Reference in New Issue