mirror of
https://github.com/caddyserver/caddy.git
synced 2025-08-11 09:16:26 -04:00
First iteration of polished docs
Matt Holt
parent
38d2e3dda5
commit
7efba6c6a0
@ -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 <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": {
|
||||
"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
|
||||
=========
|
||||
|
||||
Loading…
x
Reference in New Issue
Block a user