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: `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.