mirrors/caddy-website
1
0
Fork 0
mirror of https://github.com/caddyserver/website.git synced 2025-04-23 05:26:16 -04:00
Code Issues Projects Releases Packages Wiki Activity Actions

docs: All-new design, along with many content updates in prep for RC1

Browse source
This commit is contained in:
Matthew Holt 2020-03-30 15:38:40 -06:00
parent fe58da0269
commit 3ecf039665
No known key found for this signature in database
GPG key ID: 2A349DD577D586A5
23 changed files with 562 additions and 435 deletions
Download patch file Download diff file Expand all files Collapse all files

90
src/docs/markdown/getting-started.md
View file

@ -34,15 +34,17 @@ Oops; without a subcommand, the `caddy` command only displays help text. You can
To start Caddy as a daemon, use the `run` subcommand:
<aside class="complete">✅ Run the daemon</aside>
<pre><code class="cmd bash">caddy run</code></pre>
<aside class="complete">Run the daemon</aside>
This blocks forever, but what is it doing? At the moment... nothing. By default, Caddy's configuration ("config") is blank. We can verify this using the [admin API](/docs/api) in another terminal:
<aside class="complete">✅ Try the API</aside>
<pre><code class="cmd bash">curl localhost:2019/config/</code></pre>
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`.
<aside class="complete">Try the API</aside>
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.
@ -50,10 +52,6 @@ We can make Caddy useful by giving it a config. This can be done many ways, but
To prepare our request, we need to make a config. At its core, Caddy's configuration is simply a [JSON document](/docs/json/).
<aside class="tip">
Config files are not required. The admin API can always be used without files, which is handy when automating.
</aside>
Save this to a JSON file:
```json
@ -78,15 +76,19 @@ Save this to a JSON file:
}
```
<aside class="tip">
You do not have to use files for configuration. The <a href="/docs/api">admin API</a> can always be used without files, which is handy when automating.
</aside>
Then upload it:
<pre><code class="cmd bash">curl localhost:2019/load \
-X POST \
-H "Content-Type: application/json" \
-d @caddy.json
-X POST \
-H "Content-Type: application/json" \
-d @caddy.json
</code></pre>
<aside class="complete">✅ Give Caddy a config</aside>
<aside class="complete">Give Caddy a config</aside>
We can verify that Caddy applied our new config with another GET request:
@ -97,10 +99,9 @@ Test that it works by going to [localhost:2015](http://localhost:2015) in your b
<pre><code class="cmd"><span class="bash">curl localhost:2015</span>
Hello, world!</code></pre>
<aside class="complete">✅ Test config</aside>
If you see _Hello, world!_, then congrats -- it's working! It's always a good idea to make sure your config works as you expect, especially before deploying into production.
<aside class="complete">Test config</aside>
## Your first Caddyfile
@ -115,10 +116,11 @@ Another way to configure Caddy is with the [**Caddyfile**](/docs/caddyfile). The
respond "Hello, world!"
```
<aside class="complete">✅ Make a Caddyfile</aside>
Save that to a file named `Caddyfile` (no extension) in the current directory.
<aside class="complete">Make a Caddyfile</aside>
Stop Caddy if it is already running (Ctrl+C), then run:
<pre><code class="cmd bash">caddy adapt</code></pre>
@ -127,31 +129,29 @@ Or if you stored the Caddyfile somewhere else or named it something other than `
<pre><code class="cmd bash">caddy adapt --config /path/to/Caddyfile</code></pre>
<aside class="complete">✅ Use the config adapter</aside>
You will see JSON output! What happened here?
We just used a [_config adapter_](/docs/config-adapters) to convert our Caddyfile to Caddy's native JSON structure.
While we could take that output and make another API request, we can skip all those steps because the `caddy` command can do it for us.
<aside class="complete">Use the config adapter</aside>
Since the Caddyfile is so common, if there is a file called Caddyfile in the current directory and no other config is specified, Caddy will load the Caddyfile, adapt it for us, and run it right away.
While we could take that output and make another API request, we can skip all those steps because the `caddy` command can do it for us. If there is a file called Caddyfile in the current directory and no other config is specified, Caddy will load the Caddyfile, adapt it for us, and run it right away.
So now that there is a Caddyfile in the current folder, let's do `caddy run` again:
Now that there is a Caddyfile in the current folder, let's do `caddy run` again:
<pre><code class="cmd bash">caddy run</code></pre>
Or if your Caddyfile is somewhere else (or named something else):
Or if your Caddyfile is somewhere else:
<pre><code class="cmd bash">caddy run \
--config /path/to/Caddyfile \
--adapter caddyfile</code></pre>
<pre><code class="cmd bash">caddy run --config /path/to/Caddyfile</code></pre>
(If it is called something else that doesn't start with "Caddyfile", you will need to specify `--adapter caddyfile`.)
You can now try loading your site again and you will see that it is working!
<aside class="complete">✅ Start with an initial config</aside>
<aside class="complete">Start with an initial config</aside>
As you can see, we can start Caddy with an initial config several ways:
As you can see, there are several ways you can start Caddy with an initial config:
- A file named Caddyfile in the current directory
- The `--config` flag (optionally with the `--adapter` flag)
@ -160,9 +160,9 @@ As you can see, we can start Caddy with an initial config several ways:
## JSON vs. Caddyfile
Now you know that the Caddyfile is just converted to JSON under the hood.
Now you know that the Caddyfile is just converted to JSON for you.
The Caddyfile seems simpler than the JSON, but should you always use it? There are pros and cons to each approach. The answer depends on your requirements and use case.
The Caddyfile seems easier than JSON, but should you always use it? There are pros and cons to each approach. The answer depends on your requirements and use case.
JSON | Caddyfile
-----|----------
@ -182,15 +182,15 @@ Kind of boring | Kind of fun
You will need to decide which is best for your use case.
<aside class="complete">✅ Compare JSON and Caddyfile</aside>
It is important to note that both JSON and the Caddyfile (and [any other supported config adapter](/docs/config-adapters)) can be used with [Caddy's API](/docs/api). However, you get the full range of Caddy's functionality and API features if you use JSON. If using a config adapter, the only way to load or change the config with the API is the [/load endpoint](/docs/api#post-load).
It is important to note that both JSON and the Caddyfile (and [any other supported config adapter](/docs/config-adapters)) can be used with Caddy's API. However, you get the full range of Caddy's functionality and API features if you use JSON. If using a config adapter, the only way to load or change the config with the API is the [/load endpoint](/docs/api#post-load).
<aside class="complete">Compare JSON and Caddyfile</aside>
## API vs. Config files
<aside class="tip">
Under the hood, even config files go through Caddy's API endpoints; but the `caddy` command wraps the API calls up for you.
Under the hood, even config files go through Caddy's API endpoints; the <code>caddy</code> command just wraps up those API calls for you.
</aside>
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.)
@ -204,22 +204,22 @@ Really fun | Also fun
**Learn more: [API tutorial](/docs/api-tutorial)** | **Learn more: [Caddyfile tutorial](/docs/caddyfile-tutorial)**
<aside class="tip">
Manually managing a server's configuration with the API is actually totally doable with proper tools, for example: a REST client GUI application.
Manually managing a server's configuration with the API is totally doable with proper tools, for example: any REST client application.
</aside>
The choice of API or config file workflow is orthogonal to the use of config adapters: you can use JSON but store it in a file and use the command line interface; conversely, you can also use the Caddyfile (e.g. from a template) with the API.
The choice of API or config file workflow is orthogonal to the use of config adapters: you can use JSON but store it in a file and use the command line interface; conversely, you can also use the Caddyfile with the API.
But most people will use JSON+API or Caddyfile+CLI combinations.
As you can see, Caddy is well-suited for a wide variety of use cases and deployments!
<aside class="complete">✅ Compare API and config files</aside>
<aside class="complete">Compare API and config files</aside>
## Start, stop, run
Since Caddy is a server, it runs indefinitely. That means your terminal won't unblock (can't be used) after you execute `caddy run` until the process is terminated (usually Ctrl+C).
Since Caddy is a server, it runs indefinitely. That means your terminal won't unblock after you execute `caddy run` until the process is terminated (usually with Ctrl+C).
Although `caddy run` is the most common and is usually recommended (especially when making a system service!), you can alternatively use `caddy start` to start Caddy and have it run in the background:
@ -233,27 +233,31 @@ You will then have to stop the process yourself, since Ctrl+C won't stop it for
Or use [the /stop endpoint](/docs/api#post-stop) of the API.
<aside class="complete">✅ Run in the background</aside>
<aside class="complete">Run in the background</aside>
## Reloading config
Whether using the API or command line, your server can perform zero-downtime config reloads or changes.
Your server can perform zero-downtime config reloads/changes.
All [API endpoints](/docs/api) that load or change config are already graceful with zero downtime.
All [API endpoints](/docs/api) that load or change config are graceful with zero downtime.
When using config files with the CLI, however, it may be tempting to use Ctrl+C to stop your server and restart it again to pick up the new configuration. This is sometimes fine in local dev environments, but is a bad idea on a production server.
Instead, use the [`caddy reload`](/docs/command-line#caddy-reload) command:
When using the command line, however, it may be tempting to use Ctrl+C to stop your server and then restart it again to pick up the new configuration. Don't do this: stopping and starting the server is orthogonal to config changes, and will result in downtime.
<aside class="tip">
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, the old one is simply not stopped, rather than being "rolled back".
Stopping your server will cause the server to go down.
</aside>
Instead, use the [`caddy reload`](/docs/command-line#caddy-reload) command for a graceful config change:
<pre><code class="cmd bash">caddy reload</code></pre>
This actually just uses the API under the hood, but it will load and (if necessary) adapt your config file to JSON, then gracefully replace the active configuration without downtime.
This actually just uses the API under the hood. It will load and, if necessary, adapt your config file to JSON, then gracefully replace the active configuration without downtime.
If there are any errors loading the new config, Caddy rolls back to the last working config.
<aside class="complete">✅ Zero-downtime config reload</aside>
<aside class="tip">
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.
</aside>
<aside class="complete">Zero-downtime config reload</aside>