diff --git a/v2:-Documentation.md b/v2:-Documentation.md index 556e0d7..da749a4 100644 --- a/v2:-Documentation.md +++ b/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 - - Stops the running Caddy process. (Note: this will stop - any process named the same as the executable file.) - - $ caddy version - - Prints the version. +## Command-line interface - $ caddy list-modules - - 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: +### start ``` +$ caddy start + [--config ] +``` + +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 ] +``` + +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": { - "tls": {...}, - "http": { - "servers": { - "my_server": { - ... - }, - "your_server": { - ... - }, - ... - } - } - } + "admin": {}, + "storage": {}, + "apps": {} } ``` -At the top level of the config, there are process-wide options such as storage to use, -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. +### admin -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 =========