First iteration of polished docs

v2:-Documentation.md

@@ -1,71 +1,262 @@
-This is a copy of the document we built very quickly for early testers of Caddy 2. It is a lot to take in but should help orient you! (Will be revising and improving these pretty rapidly I imagine.)
+(This documentation is very much a work in progress!)
 
-Here's the CLI at a glance:
+## Contents
 
-	$ caddy start --config "path/to/caddy.json"
+- [Command-line interface]()
+	- [start]()
+	- [run]()
+	- [stop]()
+	- [version]()
+	- [list-modules]()
+	- [environ]()
+- [Admin endpoint]()
+	- [POST /load]()
+	- [GET /config/]()
+	- [POST /config/]()
+	- [PUT /config/]()
+	- [PATCH /config/]()
+	- [DELETE /config/]()
+- [Caddy modules]()
+- [Config structure]()
+	- [admin]()
+	- [storage]()
+		- [caddy.storage.file_system]()
+	- [apps]()
 
-		Starts the Caddy process, optionally bootstrapped with an
-		initial config file. Blocks until server is successfully
-		running (or fails to run), then returns.
-	
-	$ caddy run --config "path/to/caddy.json"
-	
-		Like start, but blocks indefinitely.
 
-	$ caddy stop
+## Command-line interface
-	
-		Stops the running Caddy process. (Note: this will stop
-		any process named the same as the executable file.)
-	
-	$ caddy version
-	
-		Prints the version.
 
-	$ caddy list-modules
+### start
-
-		Prints the modules that are installed.
-	
-	$ caddy environ
-
-		Prints the environment as seen by caddy.
-
-After starting Caddy, you can set/update its configuration by POSTing a
-new JSON payload to it, for example:
-
-	$ curl -X POST \
-		-d @caddy.json \
-		-H "Content-Type: application/json" \
-		"http://localhost:2019/load"
-
-To configure Caddy, you need to know how Caddy 2 is structured:
 
 ```
+$ caddy start
+	[--config <path>]
+```
+
+Starts the Caddy process, optionally bootstrapped with an
+initial config file. Blocks until server is successfully
+running (or fails to run), then returns.
+
+### run
+
+```
+$ caddy run
+	[--config <path>]
+```
+
+Same as `start`, but blocks indefinitely.
+
+### stop
+
+```
+$ caddy stop
+```
+
+Stops the running Caddy process. (Note: this will stop any process named the same as the executable file.)
+
+
+### version
+
+```
+$ caddy version
+```
+
+Prints the version.
+
+### list-modules
+
+```
+$ caddy list-modules
+```
+
+Prints the modules that are installed.
+
+### environ
+
+```
+$ caddy environ
+```
+
+Prints the environment as seen by caddy. Can be useful when debugging init systems or process manager units like systemd.
+
+
+
+## Admin endpoint
+
+Caddy is configured through an administration endpoint which is an HTTP listener with a REST API.
+
+Default address: `localhost:2019`
+
+### POST /load
+
+Sets Caddy's configuration to the JSON body. The `Content-Type` header must indicate a JSON payload, e.g. `application/json`.
+
+_Enterprise_: If you are using the `/config` endpoint to modify configuration instead, you MUST NOT use `/load` because it lacks the capabilities for partial configuration updates.
+
+#### Example
+
+```bash
+$ curl -X POST "http://localhost:2019/load" \
+	-H "Content-Type: application/json"
+	-d @caddy.json
+```
+
+### GET /config/[scope]
+
+🏢 _Enterprise_
+
+Exports Caddy's current configuration. Returns a JSON body. Any path appended to this endpoint will traverse the configuration and return only the scope scope.
+
+#### Examples
+
+```bash
+$ curl "http://localhost:2019/config/"
+{"apps":{"http":{"servers":{"myserver":{"listen":[":443"],"routes":[{"match":[{"host":["example.com"]}],"respond":{"responder":"file_server"}}]}}}}}
+```
+
+```bash
+$ curl "http://localhost:2019/config/apps/http/servers/myserver/listen"
+[":443"]
+```
+
+
+### POST /config/[scope]
+
+🏢 _Enterprise_
+
+Changes Caddy's configuration at the named scope to the JSON body of the request. If the named scope is an array, POST appends; if an object, it creates or replaces.
+
+#### Example
+
+```bash
+$ curl -X POST \
+	-H "Content-Type: application/json" \
+	-d '":2080"' \
+	"http://localhost:2019/config/apps/http/servers/myserver/listen"
+```
+
+
+### PUT /config/[scope]
+
+🏢 _Enterprise_
+
+Changes Caddy's configuration at the named scope to the JSON body of the request. If the named scope is an array, PUT inserts; if an object, it strictly creates a new value.
+
+#### Example
+
+```bash
+$ curl -X PUT \
+	-H "Content-Type: application/json" \
+	-d '":2080"' \
+	"http://localhost:2019/config/apps/http/servers/myserver/listen"
+```
+
+
+### PATCH /config/[scope]
+
+🏢 _Enterprise_
+
+Changes Caddy's configuration at the named scope to the JSON body of the request. PATCH strictly replaces an existing value or array element.
+
+#### Example
+
+```bash
+$ curl -X PUT \
+	-H "Content-Type: application/json" \
+	-d '":2080"' \
+	"http://localhost:2019/config/apps/http/servers/myserver/listen"
+```
+
+
+### DELETE /config/[scope]
+
+🏢 _Enterprise_
+
+Changes Caddy's configuration at the named scope to the JSON body of the request. DELETE deletes the value at the named scope.
+
+#### Example
+
+```bash
+$ curl -X DELETE "http://localhost:2019/config/apps/http/servers/myserver"
+```
+
+
+
+## Caddy modules
+
+Caddy modules are distinct from [Go modules](https://github.com/golang/go/wiki/Modules), although technically speaking, Caddy modules can be implemented by Go modules. When we talk about modules here, we mean Caddy modules.
+
+Caddy modules are the evolution of "plugins" in Caddy 1, and although modules are much-improved over plugins, the idea is similar. Various parts of Caddy's functionality can be swapped out or extended by use of modules which are statically compiled in at build-time.
+
+Each Caddy module has a name, scope/namespace, and ID:
+
+- A name looks like `a.b.c.module_id`
+- The namespace would be `a.b.c`.
+- The module ID is `module_id` which must be unique in its namespace.
+
+When the context makes it obvious what the namespace is, we generally refer to the module ID as the name, or use the terms interchangably; and in conversation the namespace can be omitted.
+
+_Host modules_ (or _parent modules_) are modules which load/initialize other modules.
+
+_Guest modules_ (or _child modules_) are modules which get loaded or initialized. All modules are at least guest modules.
+
+
+
+## Config structure
+
+Caddy configuration is a JSON document.
+
+Generally, object keys are optional, as most of the "required" settings have sane defaults. If something is actually explicitly required for a successful config load, the docs will say so.
+
+At the top level, you'll find properties needed for Caddy's basic functionality:
+
+```json
 {
-	"apps": {
+	"admin": {},
-		"tls": {...},
+	"storage": {},
-		"http": {
+	"apps": {}
-			"servers": {
-				"my_server": {
-					...
-				},
-				"your_server": {
-					...
-				},
-				...
-			}
-		}
-	}
 }
 ```
 
-At the top level of the config, there are process-wide options such as storage to use,
+### admin
-etc. Then there are "apps". Apps are like server types in Caddy 1. The HTTP server is
-an app. In it, you define a list of servers which you name. Each server has listeners,
-routes, and other configuration.
 
-There are two apps currently: "tls" and "http". We will discuss the "http" app first.
+Configures the administration endpoint.
+
+```json
+{
+	"listen": "localhost:2019"
+}
+```
+
+- `listen`: the address to which the admin endpoint's listener should bind itself
+
+### storage
+
+Configures Caddy's default storage module.
+
+Default: The local file system (`caddy.storage.file_system`). If `XDG_DATA_HOME` is set, then `$XDG_DATA_HOME/caddy` is the folder. Otherwise, `$HOME/.local/share/caddy` is the folder.
+
+#### caddy.storage.file_system
+
+```json
+{
+	"module": "file_system",
+	"root": "/var/caddy_storage"
+}
+```
+
+- `module`: The ID of the storage module
+- `root`: The base path in which things should be stored
 
 
+### apps
+
+
+# FIN
+
+The rest of this document is a WIP. It takes hours and hours to polish the documentation, so please check back later; I'm actively working on it!
+
+What follows is the original ad-hoc documentation that we sent some early testers. We'll replace it with more polished docs very soon.
 
 HTTP App
 =========