Fast and extensible multi-platform HTTP/1-2-3 web server with automatic HTTPS
Mirrored from https://github.com/Slazee/caddy.git
Synced Nov 13, 14:15 UTC
cmd: Enhance CLI docs
Matthew Holt committed
Aug 30, 2022 at 19:15 UTC
687a4b9e81c7b0b08c760ec33808c721d6775e0e
2 files changed
+91
-11
cmd/cobra.go
+87
-4
@@ -6,15 +6,98 @@ import (
6
7
var rootCmd = &cobra.Command{
8
Use: "caddy",
9
+ Long: `Caddy is an extensible server platform written in Go.
10
+
11
+At its core, Caddy merely manages configuration. Modules are plugged
12
+in statically at compile-time to provide useful functionality. Caddy's
13
+standard distribution includes common modules to serve HTTP, TLS,
14
+and PKI applications, including the automation of certificates.
15
+
16
+To run Caddy, use:
17
+
18
+ - 'caddy run' to run Caddy in the foreground (recommended).
19
+ - 'caddy start' to start Caddy in the background; only do this
20
+ if you will be keeping the terminal window open until you run
21
+ 'caddy stop' to close the server.
22
+
23
+When Caddy is started, it opens a locally-bound administrative socket
24
+to which configuration can be POSTed via a restful HTTP API (see
25
+https://caddyserver.com/docs/api).
26
+
27
+Caddy's native configuration format is JSON. However, config adapters
28
+can be used to convert other config formats to JSON when Caddy receives
29
+its configuration. The Caddyfile is a built-in config adapter that is
30
+popular for hand-written configurations due to its straightforward
31
+syntax (see https://caddyserver.com/docs/caddyfile). Many third-party
32
+adapters are available (see https://caddyserver.com/docs/config-adapters).
33
+Use 'caddy adapt' to see how a config translates to JSON.
34
+
35
+For convenience, the CLI can act as an HTTP client to give Caddy its
36
+initial configuration for you. If a file named Caddyfile is in the
37
+current working directory, it will do this automatically. Otherwise,
38
+you can use the --config flag to specify the path to a config file.
39
+
40
+Some special-purpose subcommands build and load a configuration file
41
+for you directly from command line input; for example:
42
+
43
+ - caddy file-server
44
+ - caddy reverse-proxy
45
+ - caddy respond
46
+
47
+These commands disable the administration endpoint because their
48
+configuration is specified solely on the command line.
49
+
50
+In general, the most common way to run Caddy is simply:
51
+
52
+ $ caddy run
53
+
54
+Or, with a configuration file:
55
+
56
+ $ caddy run --config caddy.json
57
+
58
+If running interactively in a terminal, running Caddy in the
59
+background may be more convenient:
60
+
61
+ $ caddy start
62
+ ...
63
+ $ caddy stop
64
+
65
+This allows you to run other commands while Caddy stays running.
66
+Be sure to stop Caddy before you close the terminal!
67
+
68
+Depending on the system, Caddy may need permission to bind to low
69
+ports. One way to do this on Linux is to use setcap:
70
+
71
+ $ sudo setcap cap_net_bind_service=+ep $(which caddy)
72
+
73
+Remember to run that command again after replacing the binary.
74
+
75
+See the Caddy website for tutorials, configuration structure,
76
+syntax, and module documentation: https://caddyserver.com/docs/
77
+
78
+Custom Caddy builds are available on the Caddy download page at:
79
+https://caddyserver.com/download
80
+
81
+The xcaddy command can be used to build Caddy from source with or
82
+without additional plugins: https://github.com/caddyserver/xcaddy
83
+
84
+Where possible, Caddy should be installed using officially-supported
85
+package installers: https://caddyserver.com/docs/install
86
+
87
+Instructions for running Caddy in production are also available:
88
+https://caddyserver.com/docs/running
89
+`,
90
+ Example: ` $ caddy run
91
+ $ caddy run --config caddy.json
92
+ $ caddy reload --config caddy.json
93
+ $ caddy stop`,
94
}
95
11
-const docsHeader = "{{if not .HasParent}} Caddy is an extensible server platform.\n\n{{end}}"
96
const fullDocsFooter = `Full documentation is available at:
13
-https://caddyserver.com/docs/command-line
14
-`
97
+https://caddyserver.com/docs/command-line`
98
99
func init() {
17
- rootCmd.SetHelpTemplate(docsHeader + rootCmd.HelpTemplate() + "\n" + fullDocsFooter)
100
+ rootCmd.SetHelpTemplate(rootCmd.HelpTemplate() + "\n" + fullDocsFooter)
101
}
102
103
func caddyCmdToCoral(caddyCmd Command) *cobra.Command {
cmd/commands.go
+4
-7
@@ -358,25 +358,22 @@ EXPERIMENTAL: May be changed or removed.
358
}
359
if err := doc.GenManTree(rootCmd, &doc.GenManHeader{
360
Title: "Caddy",
361
- Section: "8",
361
+ Section: "8", // https://en.wikipedia.org/wiki/Man_page#Manual_sections
362
}, dir); err != nil {
363
return caddy.ExitCodeFailedQuit, err
364
}
365
return caddy.ExitCodeSuccess, nil
366
},
367
- Usage: "--directory <directory path>",
368
- Short: "Generates the manual pages of Caddy commands",
367
+ Usage: "--directory <path>",
368
+ Short: "Generates the manual pages for Caddy commands",
369
Long: `
370
-Generates the manual pages of Caddy commands into the designated directory tagged into the specified section.
370
+Generates the manual pages for Caddy commands into the designated directory tagged into section 8 (System Administration).
371
372
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.
373
-
374
-The manual pages are sorted into the section specified by the argument of --section.
373
`,
374
Flags: func() *flag.FlagSet {
375
fs := flag.NewFlagSet("manpage", flag.ExitOnError)
376
fs.String("directory", "", "The output directory where the manpages are generated")
379
- fs.String("section", "", "The section number of the generated manual pages")
377
return fs
378
}(),
379
})