diff --git a/src/docs/markdown/api-tutorial.md b/src/docs/markdown/api-tutorial.md index a47fac4..ada2368 100644 --- a/src/docs/markdown/api-tutorial.md +++ b/src/docs/markdown/api-tutorial.md @@ -132,10 +132,14 @@ Using the request URI's path, we can traverse into the config structure and upda -d '"Work smarter, not harder."' + + You can verify that it worked with a similar GET request, for example:
curl localhost:2019/config/apps/http/servers/example/routes
@@ -146,10 +150,14 @@ You should see: [{"handle":[{"body":"Work smarter, not harder.","handler":"static_response"}]}] ``` + + **Important note:** This should be obvious, but once you use the API to make a change that is not in your original config file, your config file becomes obsolete. There are a few ways to handle this: @@ -182,10 +190,14 @@ This adds a property to our handler object: `"@id": "msg"`, so it now looks like } ``` + + We can then access it directly:
curl localhost:2019/id/msg
diff --git a/src/docs/markdown/api.md b/src/docs/markdown/api.md index 5d0729d..a768b9b 100644 --- a/src/docs/markdown/api.md +++ b/src/docs/markdown/api.md @@ -251,6 +251,7 @@ This section is for all `/config/` endpoints. It is experimental and subject to + Caddy's config API provides [ACID guarantees](https://en.wikipedia.org/wiki/ACID) for individual requests, but changes that involve more than a single request are subject to collisions or data loss if not properly synchronized. For example, two clients may `GET /config/foo` at the same time, make an edit within that scope (config path), then call `POST|PUT|PATCH|DELETE /config/foo/...` at the same time to apply their changes, resulting in a collision: either one will overwrite the other, or the second might leave the config in an unintended state since it was applied to a different version of the config than it was prepared against. This is because the changes are not aware of each other. diff --git a/src/docs/markdown/architecture.md b/src/docs/markdown/architecture.md index b2cea99..c319c9f 100644 --- a/src/docs/markdown/architecture.md +++ b/src/docs/markdown/architecture.md @@ -18,16 +18,23 @@ Caddy consists of a command, core library, and modules. The **command** provides the [command line interface](/docs/command-line) you are hopefully familiar with. It's how you launch the process from your operating system. The amount of code and logic here is fairly minimal, and has only what is needed to bootstrap the core in the user's desired way. We intentionally avoid using flags and environment variables for configuration except as they pertain to bootstrapping config. + + The **[core library](https://pkg.go.dev/github.com/caddyserver/caddy/v2?tab=doc)**, or "core" of Caddy, primarily manages configuration. It can [`Run()`](https://pkg.go.dev/github.com/caddyserver/caddy/v2?tab=doc#Run) a new configuration or [`Stop()`](https://pkg.go.dev/github.com/caddyserver/caddy/v2?tab=doc#Stop) a running config. It also provides various utilities, types, and values for modules to use. **Modules** do everything else. Many modules come built into Caddy, which are called the _standard modules_. These are determined to be the most useful to the most users. + @@ -64,7 +71,9 @@ When an app module is started, it initiates the app's module lifecycle. @@ -116,8 +125,11 @@ When it is time for a config to be stopped, all modules get unloaded. If a modul A module -- or any Caddy plugin -- gets "plugged in" to Caddy by adding an `import` for the module's package. By importing the package, [the module registers itself](https://pkg.go.dev/github.com/caddyserver/caddy/v2?tab=doc#RegisterModule) with the Caddy core, so when the Caddy process starts, it knows each module by name. It can even associate between module values and names, and vice-versa. + diff --git a/src/docs/markdown/automatic-https.md b/src/docs/markdown/automatic-https.md index 5514941..971220d 100644 --- a/src/docs/markdown/automatic-https.md +++ b/src/docs/markdown/automatic-https.md @@ -8,7 +8,9 @@ title: "Automatic HTTPS" Automatic HTTPS provisions TLS certificates for all your sites and keeps them renewed. It also redirects HTTP to HTTPS for you! Caddy uses safe and modern defaults -- no downtime, extra configuration, or separate tooling is required. - + Here's a 28-second video showing how it works: @@ -40,19 +42,24 @@ Here's a 28-second video showing how it works: - Caddy serves public DNS names over HTTPS using certificates from a public ACME CA such as [Let's Encrypt](https://letsencrypt.org) or [ZeroSSL](https://zerossl.com). - Examples: `example.com`, `sub.example.com`, `*.example.com` -Caddy keeps all managed certificates renewed and redirects HTTP (default port 80) to HTTPS (default port 443) automatically. +Caddy keeps all managed certificates renewed and redirects HTTP (default port `80`) to HTTPS (default port `443`) automatically. **For local HTTPS:** - Caddy may prompt for a password to install its unique root certificate into your trust store. This happens only once per root; and you can remove it at any time. -- Any client accessing the site without trusting Caddy's root will show security errors. +- Any client accessing the site without trusting Caddy's root CA certificate will show security errors. **For public domain names:** - + + - If your domain's A/AAAA records point to your server, -- ports 80 and 443 are open externally, +- ports `80` and `443` are open externally, - Caddy can bind to those ports (_or_ those ports are forwarded to Caddy), - your [data directory](/docs/conventions#data-directory) is writeable and persistent, - and your domain name appears somewhere relevant in the config, @@ -68,16 +75,17 @@ Because HTTPS utilizes a shared, public infrastructure, you as the server admin Caddy implicitly activates automatic HTTPS when it knows a domain name (i.e. hostname) or IP address it is serving. There are various ways to tell Caddy your domain/IP, depending on how you run or configure Caddy: - A [site address](/docs/caddyfile/concepts#addresses) in the [Caddyfile](/docs/caddyfile) -- A [host matcher](/docs/json/apps/http/servers/routes/match/host/) in a [route](/docs/modules/http#servers/routes) +- A [host matcher](/docs/json/apps/http/servers/routes/match/host/) in a [JSON route](/docs/modules/http#servers/routes) - Command line flags like [--domain](/docs/command-line#caddy-file-server) or [--from](/docs/command-line#caddy-reverse-proxy) - The [automate](/docs/json/apps/tls/certificates/automate/) certificate loader Any of the following will prevent automatic HTTPS from being activated, either in whole or in part: -- [Explicitly disabling it](/docs/json/apps/http/servers/automatic_https/) +- Explicitly disabling it [via JSON](/docs/json/apps/http/servers/automatic_https/) or [via Caddyfile](/docs/caddyfile/options#auto-https) - Not providing any hostnames or IP addresses in the config - Listening exclusively on the HTTP port -- Manually loading certificates (unless [this config property](/docs/json/apps/http/servers/automatic_https/ignore_loaded_certificates/) is true) +- Prefixing the [site address](/docs/caddyfile/concepts#addresses) with `http://` in the Caddyfile +- Manually loading certificates (unless [`ignore_loaded_certificates`](/docs/json/apps/http/servers/automatic_https/ignore_loaded_certificates/) is set) **Special cases:** @@ -89,8 +97,8 @@ Any of the following will prevent automatic HTTPS from being activated, either i When automatic HTTPS is activated, the following occurs: - Certificates are obtained and renewed for [all domain names](#hostname-requirements) -- The default port (if any) is changed to the [HTTPS port](/docs/modules/http#https_port) 443 -- HTTP is redirected to HTTPS (this uses [HTTP port](/docs/modules/http#http_port) 80) +- The default port (if any) is changed to the [HTTPS port](/docs/modules/http#https_port) `443` +- HTTP is redirected to HTTPS (this uses [HTTP port](/docs/modules/http#http_port) `80`) Automatic HTTPS never overrides explicit configuration. @@ -126,9 +134,11 @@ The root's private key is uniquely generated using a cryptographically-secure ps Although Caddy can be configured to sign with the root directly (to support non-compliant clients), this is disabled by default, and the root key is only used to sign intermediates. -The first time a root key is used, Caddy will try to install it into the system's local trust store(s). If it does not have permission to do so, it will prompt for a password. This behavior can be disabled in the configuration if it is not desired. +The first time a root key is used, Caddy will try to install it into the system's local trust store(s). If it does not have permission to do so, it will prompt for a password. This behavior can be disabled in the configuration if it is not desired. If this fails due to being run as an unprivileged user, you may run [`caddy trust`](/docs/command-line#caddy-trust) to retry installation as a privileged user. - + After Caddy's root CA is installed, you will see it in your local trust store as "Caddy Local Authority" (unless you've configured a different name). You can uninstall it any time if you wish (the [`caddy untrust`](/docs/command-line#caddy-untrust) command makes this easy). @@ -161,29 +171,29 @@ The first two challenge types are enabled by default. If multiple challenges are ### HTTP challenge -The HTTP challenge performs an authoritative DNS lookup for the candidate hostname's A/AAAA record, then requests a temporary cryptographic resource over port 80 using HTTP. If the CA sees the expected resource, a certificate is issued. +The HTTP challenge performs an authoritative DNS lookup for the candidate hostname's A/AAAA record, then requests a temporary cryptographic resource over port `80` using HTTP. If the CA sees the expected resource, a certificate is issued. -This challenge requires port 80 to be externally accessible. If Caddy cannot listen on port 80, packets from port 80 must be forwarded to Caddy's [HTTP port](/docs/json/apps/http/http_port/). +This challenge requires port `80` to be externally accessible. If Caddy cannot listen on port 80, packets from port `80` must be forwarded to Caddy's [HTTP port](/docs/json/apps/http/http_port/). This challenge is enabled by default and does not require explicit configuration. ### TLS-ALPN challenge -The TLS-ALPN challenge performs an authoritative DNS lookup for the candidate hostname's A/AAAA record, then requests a temporary cryptographic resource over port 443 using a TLS handshake containing special ServerName and ALPN values. If the CA sees the expected resource, a certificate is issued. +The TLS-ALPN challenge performs an authoritative DNS lookup for the candidate hostname's A/AAAA record, then requests a temporary cryptographic resource over port `443` using a TLS handshake containing special ServerName and ALPN values. If the CA sees the expected resource, a certificate is issued. -This challenge requires port 443 to be externally accessible. If Caddy cannot listen on port 443, packets from port 443 must be forwarded to Caddy's [HTTPS port](/docs/json/apps/http/https_port/). +This challenge requires port `443` to be externally accessible. If Caddy cannot listen on port 443, packets from port `443` must be forwarded to Caddy's [HTTPS port](/docs/json/apps/http/https_port/). This challenge is enabled by default and does not require explicit configuration. ### DNS challenge -The DNS challenge performs an authoritative DNS lookup for the candidate hostname's TXT records, and looks for a special TXT record with a certain value. If the CA sees the expected value, a certificate is issued. +The DNS challenge performs an authoritative DNS lookup for the candidate hostname's `TXT` records, and looks for a special `TXT` record with a certain value. If the CA sees the expected value, a certificate is issued. -This challenge does not require any open ports, and the server requesting a certificate does not need to be externally accessible. However, the DNS challenge requires configuration. Caddy needs to know the credentials to access your domain's DNS provider so it can set (and clear) the special TXT records. If the DNS challenge is enabled, other challenges are disabled by default. +This challenge does not require any open ports, and the server requesting a certificate does not need to be externally accessible. However, the DNS challenge requires configuration. Caddy needs to know the credentials to access your domain's DNS provider so it can set (and clear) the special `TXT` records. If the DNS challenge is enabled, other challenges are disabled by default. -Since ACME CAs follow DNS standards when looking up TXT records for challenge verification, you can use CNAME records to delegate answering the challenge to other DNS zones. This can be used to delegate the `_acme-challenge` subdomain to another zone. This is particularly useful if your DNS provider doesn't provide an API, or isn't supported by one of the DNS plugins for Caddy. +Since ACME CAs follow DNS standards when looking up `TXT` records for challenge verification, you can use CNAME records to delegate answering the challenge to other DNS zones. This can be used to delegate the `_acme-challenge` subdomain to another zone. This is particularly useful if your DNS provider doesn't provide an API, or isn't supported by one of the DNS plugins for Caddy. DNS provider support is a community effort. [Learn how to enable the DNS challenge for your provider at our wiki.](https://caddy.community/t/how-to-use-dns-provider-modules-in-caddy-2/8148) diff --git a/src/docs/markdown/build.md b/src/docs/markdown/build.md index 71c1cfe..40290e2 100644 --- a/src/docs/markdown/build.md +++ b/src/docs/markdown/build.md @@ -19,10 +19,14 @@ Build:
cd caddy/cmd/caddy/
 go build
+ + ## xcaddy The [`xcaddy` command](https://github.com/caddyserver/xcaddy) is the easiest way to build Caddy with version information and/or plugins. diff --git a/src/docs/markdown/caddyfile-tutorial.md b/src/docs/markdown/caddyfile-tutorial.md index 3d8ed5d..c5f6323 100644 --- a/src/docs/markdown/caddyfile-tutorial.md +++ b/src/docs/markdown/caddyfile-tutorial.md @@ -32,9 +32,12 @@ localhost ``` + Then hit enter and type what you want it to do. For this tutorial, make your Caddyfile look like this: ```caddy @@ -48,18 +51,28 @@ Save that and run Caddy (since this is a training tutorial, we'll use the `--wat
caddy run --watch
+ The first time, you'll be asked for your password. This is so Caddy can serve your site over HTTPS. - + + Open [localhost](https://localhost) in your browser and see your web server working, complete with HTTPS! - + That's not particularly exciting, so let's change our static response to a [file server](/docs/caddyfile/directives/file_server) with directory listings enabled: @@ -126,7 +139,9 @@ templates file_server browse ``` - + @@ -265,4 +280,4 @@ One last thing that you will find most helpful: if you want to remark or note an - [Common patterns](/docs/caddyfile/patterns) - [Caddyfile concepts](/docs/caddyfile/concepts) -- [Directives](/docs/caddyfile/directives) \ No newline at end of file +- [Directives](/docs/caddyfile/directives) diff --git a/src/docs/markdown/caddyfile/concepts.md b/src/docs/markdown/caddyfile/concepts.md index e7cfef1..607262c 100644 --- a/src/docs/markdown/caddyfile/concepts.md +++ b/src/docs/markdown/caddyfile/concepts.md @@ -172,17 +172,21 @@ These are examples of valid addresses: - `*.example.com` - `http://` + + From the address, Caddy can potentially infer the scheme, host and port of your site. If the address is without a port, the Caddyfile will choose the port matching the scheme if specified, or the default port of 443 will be assumed. -If you specify a hostname, only requests with a matching Host header will be honored. In other words, if the site address is `localhost`, then Caddy will not match requests to `127.0.0.1`. +If you specify a hostname, only requests with a matching `Host` header will be honored. In other words, if the site address is `localhost`, then Caddy will not match requests to `127.0.0.1`. Wildcards (`*`) may be used, but only to represent precisely one label of the hostname. For example, `*.example.com` matches `foo.example.com` but not `foo.bar.example.com`, and `*` matches `localhost` but not `example.com`. To catch all hosts, omit the host portion of the address. -If multiple sites share the same definition, you can list all of them together: +If multiple sites share the same definition, you can list all of them together; notice how the commas indicate the continuation of addresses: ```caddy localhost:8080, example.com, www.example.com @@ -196,10 +200,10 @@ example.com, www.example.com ``` -Notice how the commas indicate the continuation of addresses. - An address must be unique; you cannot specify the same address more than once. +By default, sites bind on all network interfaces. If you wish to override this, use the [`bind` directive](/docs/caddyfile/directives/bind) or the [`default_bind` global option](/docs/caddyfile/options#default-bind) to do so. + ## Matchers diff --git a/src/docs/markdown/caddyfile/directives/bind.md b/src/docs/markdown/caddyfile/directives/bind.md index 808450b..744e6ac 100644 --- a/src/docs/markdown/caddyfile/directives/bind.md +++ b/src/docs/markdown/caddyfile/directives/bind.md @@ -4,11 +4,11 @@ title: bind (Caddyfile directive) # bind -bind overrides the interface to which the server's socket should bind. Normally, the listener binds to the empty (wildcard) interface. However, you may force the listener to bind to another hostname or IP instead. (This directive accepts only a host, not a port.) +Overrides the interface to which the server's socket should bind. Normally, the listener binds to the empty (wildcard) interface. However, you may force the listener to bind to another hostname or IP instead. (This directive accepts only a host, not a port.) -Note that binding sites inconsistently may result in unintended consequences. For example, if two sites on the same port resolve to 127.0.0.1 and only one of those sites is configured with `bind 127.0.0.1`, then only one site will be accessible since the other will bind to the port without a specific host; the OS will choose the more specific matching socket. (Virtual hosts are not shared across different listeners.) +Note that binding sites inconsistently may result in unintended consequences. For example, if two sites on the same port resolve to `127.0.0.1` and only one of those sites is configured with `bind 127.0.0.1`, then only one site will be accessible since the other will bind to the port without a specific host; the OS will choose the more specific matching socket. (Virtual hosts are not shared across different listeners.) -bind also accepts an optional network name: `/`. +`bind` accepts [network addresses](/docs/conventions#network-addresses), but may not include a port. ## Syntax @@ -17,7 +17,7 @@ bind also accepts an optional network name: `/`. bind ``` -- **<hosts...>** is the list of host interfaces to bind which to bind the listener. +- **<hosts...>** is the list of host interfaces to bind which to bind the listener. ## Examples diff --git a/src/docs/markdown/caddyfile/directives/handle_errors.md b/src/docs/markdown/caddyfile/directives/handle_errors.md index 7231f1b..d1fe8f5 100644 --- a/src/docs/markdown/caddyfile/directives/handle_errors.md +++ b/src/docs/markdown/caddyfile/directives/handle_errors.md @@ -8,7 +8,7 @@ Sets up error handlers. When the normal HTTP request handlers return an error, normal processing stops and the error handlers are invoked. Error handlers form a route which is just like normal routes, and they can do anything that normal routes can do. This enables great control and flexibility when handling errors during HTTP requests. For example, you can serve static error pages, templated error pages, or reverse proxy to another backend to handle errors. -A request's context is carried into error routes, so any values set on the request context such as [site root](root) will be preserved in error handlers, too. Additionally, new placeholders are available when handling errors. [The JSON docs for an HTTP server's error routes](/docs/json/apps/http/servers/errors/#routes) describe these placeholders. The `handle_errors` directive simply adds error routes, so you can use those placeholders within a `handle_errors` block. +A request's context is carried into error routes, so any values set on the request context such as [site root](root) or [vars](vars) will be preserved in error handlers, too. Additionally, [new placeholders](#placeholders) are available when handling errors. Note that certain directives, for example [`reverse_proxy`](reverse_proxy) which may write a response with an HTTP status which is classified as an error, will _not_ trigger the error routes. @@ -23,13 +23,25 @@ handle_errors { } ``` -- **** is a list of HTTP handler directives, directive blocks, or matchers; one per line. +- **** is a list of HTTP handler [directives](/docs/caddyfile/directives) and [matchers](/docs/caddyfile/matchers), one per line. +## Placeholders + +The following placeholders are available while handling errors. They are [Caddyfile shorthands](/docs/caddyfile/concepts#placeholders) for the full placeholders which can be found in [the JSON docs for an HTTP server's error routes](/docs/json/apps/http/servers/errors/#routes). + +| Placeholder | Description | +|---|---| +| `{err.status_code}` | The recommended HTTP status code | +| `{err.status_text}` | The status text associated with the recommended status code | +| `{err.message}` | The error message | +| `{err.trace}` | The origin of the error | +| `{err.id}` | An identifier for this occurrence of the error | + ## Examples -Custom error pages based on the status code (i.e. a page called `404.html` for 404 errors). Note that [`file_server`](file_server) preserves the error's HTTP status code when run in `handle_errors`: +Custom error pages based on the status code (i.e. a page called `404.html` for 404 errors). Note that [`file_server`](file_server) preserves the error's HTTP status code when run in `handle_errors` (assumes you set a [site root](/docs/caddyfile/directives/root) in your site beforehand): ```caddy-d handle_errors { @@ -54,7 +66,7 @@ Reverse proxy to a professional server that is highly qualified for handling HTT handle_errors { rewrite * /{err.status_code} reverse_proxy https://http.cat { - header_up Host http.cat + header_up Host {upstream_hostport} } } ``` @@ -67,13 +79,22 @@ handle_errors { } ``` -To handle specific error codes differently, use an [`expression`](/docs/caddyfile/matchers#expression) matcher: +To handle specific error codes differently, use an [`expression`](/docs/caddyfile/matchers#expression) matcher, using [`handle`](/docs/caddyfile/directives/handle) for mutual exclusivity: ```caddy-d handle_errors { - @4xx expression `{err.status_code} >= 400 && {err.status_code} < 500` - respond @4xx "It's a 4xx error!" + @404-410 expression `{err.status_code} in [404, 410]` + handle @404-410 { + respond "It's a 404 or 410 error!" + } - respond "It's not a 4xx error." + @5xx expression `{err.status_code} >= 500 && {err.status_code} < 600` + handle @5xx { + respond "It's a 5xx error." + } + + handle { + respond "It's another error" + } } ``` diff --git a/src/docs/markdown/caddyfile/directives/log.md b/src/docs/markdown/caddyfile/directives/log.md index e07b1be..ec63e6d 100644 --- a/src/docs/markdown/caddyfile/directives/log.md +++ b/src/docs/markdown/caddyfile/directives/log.md @@ -14,9 +14,12 @@ $(function() { Enables and configures HTTP request logging (also known as access logs). + The `log` directive applies to the host/port of the site block it appears in, not any other part of the site address (e.g. path). - [Syntax](#syntax) @@ -131,9 +134,12 @@ output net
{ The **format** subdirective lets you customize how logs get encoded (formatted). It appears within a `log` block. + In addition to the syntax for each individual encoder, these common properties can be set on most encoders: ```caddy-d diff --git a/src/docs/markdown/caddyfile/directives/reverse_proxy.md b/src/docs/markdown/caddyfile/directives/reverse_proxy.md index 47e4589..9cc873f 100644 --- a/src/docs/markdown/caddyfile/directives/reverse_proxy.md +++ b/src/docs/markdown/caddyfile/directives/reverse_proxy.md @@ -516,7 +516,9 @@ transport fastcgi { - **write_timeout** is how long to wait when sending to the FastCGI server. Accepts [duration values](/docs/conventions#durations). Default: no timeout. diff --git a/src/docs/markdown/caddyfile/directives/route.md b/src/docs/markdown/caddyfile/directives/route.md index 53e04c4..aa532af 100644 --- a/src/docs/markdown/caddyfile/directives/route.md +++ b/src/docs/markdown/caddyfile/directives/route.md @@ -58,9 +58,12 @@ route { ``` + And now `file_server` will be chained in before `redir` because the order is taken literally. ## Similar directives diff --git a/src/docs/markdown/caddyfile/options.md b/src/docs/markdown/caddyfile/options.md index 1205302..6fb6fd7 100644 --- a/src/docs/markdown/caddyfile/options.md +++ b/src/docs/markdown/caddyfile/options.md @@ -298,9 +298,12 @@ Customizes [HTTP servers](/docs/json/apps/http/servers/) with settings that pote Can be specified more than once, with different `listener_address` values, to configure different options per server. For example, `servers :443` will only apply to the server that is bound to the listener address `:443`. Omitting the listener address will apply the options to any remaining server. + For example, to configure different options for the servers on port `:80` and `:443`, you would specify two `servers` blocks: ```caddy diff --git a/src/docs/markdown/command-line.md b/src/docs/markdown/command-line.md index 4610e76..c400088 100644 --- a/src/docs/markdown/command-line.md +++ b/src/docs/markdown/command-line.md @@ -337,9 +337,12 @@ Once started, you can use [`caddy stop`](#caddy-stop) or the [`POST /stop`](/doc [--config <path> [--adapter <name>]] + Gracefully stops the running Caddy process (other than the process of the stop command) and causes it to exit. It uses the [`POST /stop`](/docs/api#post-stop) endpoint of the admin API to perform a graceful shutdown. The address of this request can be customized using the `--address` flag, or from the given `--config`, if the running instance's admin API is not using the default listen address. diff --git a/src/docs/markdown/conventions.md b/src/docs/markdown/conventions.md index be6ccd4..0801dcb 100644 --- a/src/docs/markdown/conventions.md +++ b/src/docs/markdown/conventions.md @@ -51,7 +51,9 @@ unix//path/to/socket ``` @@ -60,9 +62,12 @@ unix//path/to/socket Caddy's configuration supports the use of _placeholders_ (variables). Using placeholders is a simple way to inject dynamic values into a static configuration. + Placeholders are bounded on either side by curly braces `{ }` and contain the variable name inside, for example: `{foo.bar}`. Placeholder braces can be escaped, `\{like so\}`. Variable names are typically namespaced with dots to avoid collisions across modules. Which placeholders are available depends on the context. Not all placeholders are available in all parts of the config. For example, [the HTTP app sets placeholders](/docs/json/apps/http/#docs) that are only available in areas of the config related to handling HTTP requests. @@ -94,10 +99,13 @@ This section contains information about where to find various files. File and di There is no single, conventional place for you to put your config files. Put them wherever makes the most sense to you. -Distributions that ship with a default config file should document where this config file is at, even if it might be obvious to the package/distro maintainers. + +Distributions that ship with a default config file should document where this config file is at, even if it might be obvious to the package/distro maintainers. For most Linux installations, the Caddyfile will be found at `/etc/caddy/Caddyfile`. ### Data directory @@ -128,9 +136,12 @@ It is crucial that this directory is persistent and writeable by Caddy. This is where Caddy may store certain configuration to disk. Most notably, it persists the last active configuration (by default) to this folder for easy resumption later using [`caddy run --resume`](/docs/command-line#caddy-run). + If the `XDG_CONFIG_HOME` environment variable is set, it is `$XDG_CONFIG_HOME/caddy`. Otherwise, its path varies by platform, adhering to OS conventions: @@ -150,7 +161,7 @@ It is crucial that this directory is persistent and writeable by Caddy. ## Durations -Duration strings are commonly used throughout Caddy's configuration. They take on the same format as [Go's time.ParseDuration syntax](https://golang.org/pkg/time/#ParseDuration) except you can also use `d` for day (we assume 1 day = 24 hours for simplicity). Valid units are: +Duration strings are commonly used throughout Caddy's configuration. They take on the same format as [Go's `time.ParseDuration` syntax](https://golang.org/pkg/time/#ParseDuration) except you can also use `d` for day (we assume 1 day = 24 hours for simplicity). Valid units are: - `ns` (nanosecond) - `us`/`µs` (microsecond) diff --git a/src/docs/markdown/extending-caddy.md b/src/docs/markdown/extending-caddy.md index 8548e64..829e672 100644 --- a/src/docs/markdown/extending-caddy.md +++ b/src/docs/markdown/extending-caddy.md @@ -49,9 +49,12 @@ foo.gizmo ... + Congratulations, your module registers with Caddy and can be used in [Caddy's config document](/docs/json/) in whatever places use modules in the same namespace. Under the hood, `xcaddy` is simply making a new Go module that requires both Caddy and your plugin (with an appropriate `replace` to use your local development version), then adds an import to ensure it is compiled in: diff --git a/src/docs/markdown/getting-started.md b/src/docs/markdown/getting-started.md index 1ee4ca8..5aac550 100644 --- a/src/docs/markdown/getting-started.md +++ b/src/docs/markdown/getting-started.md @@ -45,9 +45,12 @@ This blocks forever, but what is it doing? At the moment... nothing. By default,
curl localhost:2019/config/
+ We can make Caddy useful by giving it a config. This can be done many ways, but we'll start by making a POST request to the [/load](/docs/api#post-load) endpoint using `curl` in the next section. @@ -83,9 +86,12 @@ Save this to a JSON file (e.g. `caddy.json`): ``` + Then upload it:
curl localhost:2019/load \
@@ -195,9 +201,12 @@ It is important to note that both JSON and the Caddyfile (and [any other support
 ## API vs. Config files
 
 
 
+
 You will also want to decide whether your workflow is API-based or CLI-based. (You _can_ use both the API and config files on the same server, but we don't recommend it: best to have one source of truth.)
 
 API | Config files
@@ -265,4 +274,4 @@ If there are any errors loading the new config, Caddy rolls back to the last wor
 	Technically, the new config is started before the old config is stopped, so for a brief time, both configs are running! If the new config fails, it aborts with an error, while the old one is simply not stopped.
 
 
-
\ No newline at end of file
+
diff --git a/src/docs/markdown/install.md b/src/docs/markdown/install.md
index 6479311..b205208 100644
--- a/src/docs/markdown/install.md
+++ b/src/docs/markdown/install.md
@@ -16,7 +16,9 @@ This page describes various methods for installing Caddy on your system.
 - [DigitalOcean](#digitalocean)
 
 
 
 
diff --git a/src/docs/markdown/logging.md b/src/docs/markdown/logging.md
index 2bd354b..d27e802 100644
--- a/src/docs/markdown/logging.md
+++ b/src/docs/markdown/logging.md
@@ -131,9 +131,12 @@ As you saw above, messages are emitted by **loggers**. The messages are then sen
 Caddy lets you [configure multiple logs](/docs/json/logging/logs/) which can process messages. A log consists of an encoder, writer, minimum level, sampling ratio, and a list of loggers to include or exclude. In Caddy, there is always a default log named `default`. You can customize it by specifying a log keyed as `"default"` in [this object](/docs/json/logging/logs/) in the config.
 
 
 
+
 - **Encoder:** The format for the log. Transforms the in-memory data representation into a byte slice. Encoders have access to all fields of a log message.
 - **Writer:** The log output. Can be any log writer module, like to a file or network socket. It simply writes bytes.
 - **Level:** Logs have various levels, from DEBUG to FATAL. Messages lower than the specified level will be ignored by the log.
diff --git a/src/docs/markdown/metrics.md b/src/docs/markdown/metrics.md
index 155470f..53ef4ab 100644
--- a/src/docs/markdown/metrics.md
+++ b/src/docs/markdown/metrics.md
@@ -135,9 +135,9 @@ All Caddy HTTP middleware handlers are instrumented automatically for
 determining request latency, time-to-first-byte, errors, and request/response
 body sizes.
 
-
+
 
 For the histogram metrics below, the buckets are currently not configurable.
 For durations, the default ([`prometheus.DefBuckets`](https://pkg.go.dev/github.com/prometheus/client_golang/prometheus#pkg-variables)
@@ -220,9 +220,12 @@ Label  | Description
 Once you have Prometheus scraping Caddy's metrics, you can start to see some
 interesting metrics about how Caddy's performing.
 
-
+
+
 
 For example, to see the per-second request rate, as averaged over 5 minutes:
 
diff --git a/src/docs/markdown/quick-starts/caddyfile.md b/src/docs/markdown/quick-starts/caddyfile.md
index 6d995d7..290c2a8 100644
--- a/src/docs/markdown/quick-starts/caddyfile.md
+++ b/src/docs/markdown/quick-starts/caddyfile.md
@@ -13,9 +13,12 @@ localhost
 ```
 
 
 
+
 Then hit enter and type what you want it to do, so it looks like this:
 
 ```caddy
@@ -77,4 +80,4 @@ When you are done with Caddy, make sure to stop it:
 
 - [Common patterns](/docs/caddyfile/patterns)
 - [Caddyfile concepts](/docs/caddyfile/concepts)
-- [Directives](/docs/caddyfile/directives)
\ No newline at end of file
+- [Directives](/docs/caddyfile/directives)
diff --git a/src/docs/markdown/quick-starts/https.md b/src/docs/markdown/quick-starts/https.md
index 7b33d4e..59369f7 100644
--- a/src/docs/markdown/quick-starts/https.md
+++ b/src/docs/markdown/quick-starts/https.md
@@ -30,7 +30,9 @@ Before continuing, verify correct records with an authoritative lookup. Replace
 
 Also make sure your server is externally reachable on ports 80 and 443 from a public interface.
 
-
+
 
 All we have to do is start Caddy with your domain name in the config. There are several ways to do this.