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

Few updates and tips to get beginners going

Browse source
This commit is contained in:
Christian Glahn 2022-06-05 10:38:20 +02:00 • committed by GitHub
parent 8f61c3c71f
commit 497686c215
No known key found for this signature in database
GPG key ID: 4AEE18F83AFDEB23
1 changed files with 19 additions and 6 deletions
Download patch file Download diff file Expand all files Collapse all files

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

@ -52,6 +52,9 @@ This blocks forever, but what is it doing? At the moment... nothing. By default,
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.
<aside class="tip" markdown="1">
Caddy is controlled through the `caddy` command. It offers many useful tools for different tasks while running Caddy. Have a closer look at [ `caddy`'s subcommands ](https://caddyserver.com/docs/command-line) to learn what you can do.
</aside>
## Your first config
@ -122,11 +125,12 @@ Another way to configure Caddy is with the [**Caddyfile**](/docs/caddyfile). The
respond "Hello, world!"
```
Save that to a file named `Caddyfile` (no extension) in the current directory.
<aside class="complete">Make a Caddyfile</aside>
Next we check if the configuration is valid.
Stop Caddy if it is already running (Ctrl+C), then run:
<pre><code class="cmd bash">caddy adapt</code></pre>
@ -135,9 +139,14 @@ 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>
You will see JSON output! What happened here?
If you made no errors, 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.
<aside class="tip" markdown="1">
It is always good to test the changes in your `Caddyfile` using `caddy adapt`. If there are errors in your `Caddyfile`, you will see where you made a mistake instead of the JSON.
</aside>
We just used a [_config adapter_](/docs/config-adapters) to convert our Caddyfile to Caddy's native JSON structure.
<aside class="complete">Use the config adapter</aside>
@ -176,6 +185,7 @@ Full range of Caddy functionality | Most common parts of Caddy functionality
Easy to generate | Easy to craft by hand
Easily programmable | Difficult to automate
Extremely expressive | Moderately expressive
Hard to read | Easy to read
Allows config traversal | Cannot traverse within Caddyfile
Partial config changes | Whole config changes only
Can be exported | Cannot be exported
@ -188,7 +198,11 @@ Kind of boring | Kind of fun
You will need to decide which is best for your use case.
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).
<aside class="tip" markdown="1">
The Caddyfile offers shortcuts for many common tasks that are require complex JSON configurations. Use `caddy adapt` to learn how these shortcuts work in JSON.
</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 only 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>
@ -222,7 +236,6 @@ As you can see, Caddy is well-suited for a wide variety of use cases and deploym
<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 after you execute `caddy run` until the process is terminated (usually with Ctrl+C).
@ -266,4 +279,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.
</aside>
<aside class="complete">Zero-downtime config reload</aside>
<aside class="complete">Zero-downtime config reload</aside>