mirror of
https://github.com/caddyserver/website.git
synced 2025-04-24 14:06:17 -04:00
Initial commit
This commit is contained in:
Matthew Holt
commit
03b6fddeb0
77 changed files with 7599 additions and 0 deletions
108
src/docs/markdown/quick-starts/api.md
Normal file
108
src/docs/markdown/quick-starts/api.md
Normal file
|
|
@ -0,0 +1,108 @@
|
|||
---
|
||||
title: API Quick-start
|
||||
---
|
||||
|
||||
# API quick-start
|
||||
|
||||
**Prerequisites:**
|
||||
- Basic terminal / command line skills
|
||||
- `caddy` and `curl` in your PATH
|
||||
|
||||
---
|
||||
|
||||
First start Caddy:
|
||||
|
||||
<pre><code class="cmd bash">caddy start</code></pre>
|
||||
|
||||
Caddy is currently running idle (with a blank configuration). Give it a simple config with `curl`:
|
||||
|
||||
<pre><code class="cmd bash">curl localhost:2019/load \
|
||||
-X POST \
|
||||
-H "Content-Type: application/json" \
|
||||
-d @- << EOF
|
||||
{
|
||||
"apps": {
|
||||
"http": {
|
||||
"servers": {
|
||||
"hello": {
|
||||
"listen": [":2015"],
|
||||
"routes": [
|
||||
{
|
||||
"handle": [{
|
||||
"handler": "static_response",
|
||||
"body": "Hello, world!"
|
||||
}]
|
||||
}
|
||||
]
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
EOF</code></pre>
|
||||
|
||||
Giving a POST body with [Heredoc](https://en.wikipedia.org/wiki/Here_document#Unix_shells) can be tedious, so if you prefer to use files, save the JSON to a file called `caddy.json` and then use this command instead:
|
||||
|
||||
<pre><code class="cmd bash">curl localhost:2019/load \
|
||||
-X POST \
|
||||
-H "Content-Type: application/json" \
|
||||
-d @caddy.json
|
||||
</code></pre>
|
||||
|
||||
Now load [localhost:2015](http://localhost:2015) in your browser or use `curl`:
|
||||
|
||||
<pre><code class="cmd"><span class="bash">curl localhost:2015</span>
|
||||
Hello, world!</code></pre>
|
||||
|
||||
We can also define multiple sites on different interfaces with this JSON:
|
||||
|
||||
```json
|
||||
{
|
||||
"apps": {
|
||||
"http": {
|
||||
"servers": {
|
||||
"hello": {
|
||||
"listen": [":2015"],
|
||||
"routes": [
|
||||
{
|
||||
"handle": [{
|
||||
"handler": "static_response",
|
||||
"body": "Hello, world!"
|
||||
}]
|
||||
}
|
||||
]
|
||||
},
|
||||
"bye": {
|
||||
"listen": [":2016"],
|
||||
"routes": [
|
||||
{
|
||||
"handle": [{
|
||||
"handler": "static_response",
|
||||
"body": "Goodbye, world!"
|
||||
}]
|
||||
}
|
||||
]
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
Update your JSON then perform the API request again.
|
||||
|
||||
Try out your new "goodbye" endpoint [in your browser](http://localhost:2016) or with `curl` to make sure it works:
|
||||
|
||||
<pre><code class="cmd"><span class="bash">curl localhost:2016</span>
|
||||
Goodbye, world!</code></pre>
|
||||
|
||||
When you are done with Caddy, make sure to stop it:
|
||||
|
||||
<pre><code class="cmd bash">caddy stop</code></pre>
|
||||
|
||||
There's a lot more you can do with the API, including exporting configuration and making fine-grained changes to the config (as opposed to updating the whole thing). Be sure to read the [full API tutorial](/docs/api-tutorial) to learn how!
|
||||
|
||||
## Further reading
|
||||
|
||||
- [Full API tutorial](/docs/api-tutorial)
|
||||
- [API documentation](/docs/api)
|
||||
68
src/docs/markdown/quick-starts/caddyfile.md
Normal file
68
src/docs/markdown/quick-starts/caddyfile.md
Normal file
|
|
@ -0,0 +1,68 @@
|
|||
---
|
||||
title: Caddyfile Quick-start
|
||||
---
|
||||
|
||||
# Caddyfile quick-start
|
||||
|
||||
Create a new text file named `Caddyfile` (no extension).
|
||||
|
||||
The first thing to type in a Caddyfile is your site's address:
|
||||
|
||||
```
|
||||
localhost
|
||||
```
|
||||
|
||||
Then hit enter and type what you want it to do, so it looks like this:
|
||||
|
||||
```
|
||||
localhost
|
||||
|
||||
respond "Hello, world!"
|
||||
```
|
||||
|
||||
Save this and run Caddy from the same folder that contains your Caddyfile:
|
||||
|
||||
<pre><code class="cmd bash">caddy start</code></pre>
|
||||
|
||||
Either open your browser to [localhost:2015](http://localhost:2015) or `curl` it:
|
||||
|
||||
<pre><code class="cmd"><span class="bash">curl localhost:2015</span>
|
||||
Hello, world!</code></pre>
|
||||
|
||||
You can define multiple sites in a Caddyfile by wrapping them in curly braces `{ }`. Change your Caddyfile to be:
|
||||
|
||||
```
|
||||
localhost {
|
||||
respond "Hello, world!"
|
||||
}
|
||||
|
||||
localhost:2016 {
|
||||
respond "Goodbye, world!"
|
||||
}
|
||||
```
|
||||
|
||||
You can give Caddy the updated configuration two ways, either with the API directly:
|
||||
|
||||
<pre><code class="cmd bash">curl localhost:2019/load \
|
||||
-X POST \
|
||||
-H "Content-Type: text/caddyfile" \
|
||||
--data-binary @Caddyfile
|
||||
</code></pre>
|
||||
|
||||
or with the reload command, which does the same API request for you:
|
||||
|
||||
<pre><code class="cmd bash">caddy reload</code></pre>
|
||||
|
||||
Try out your new "goodbye" endpoint [in your browser](http://localhost:2016) or with `curl` to make sure it works:
|
||||
|
||||
<pre><code class="cmd"><span class="bash">curl localhost:2016</span>
|
||||
Goodbye, world!</code></pre>
|
||||
|
||||
When you are done with Caddy, make sure to stop it:
|
||||
|
||||
<pre><code class="cmd bash">caddy stop</code></pre>
|
||||
|
||||
## Further reading
|
||||
|
||||
- [Caddyfile concepts](/docs/caddyfile/concepts)
|
||||
- [Directives](/docs/caddyfile/directives)
|
||||
82
src/docs/markdown/quick-starts/file-server.md
Normal file
82
src/docs/markdown/quick-starts/file-server.md
Normal file
|
|
@ -0,0 +1,82 @@
|
|||
---
|
||||
title: File server quick-start
|
||||
---
|
||||
|
||||
# File server quick-start
|
||||
|
||||
This guide will show you how to get a production-ready static file server up and running quickly.
|
||||
|
||||
**Prerequisites:**
|
||||
- Basic terminal / command line skills
|
||||
- `caddy` in your PATH
|
||||
- A folder containing your website
|
||||
|
||||
---
|
||||
|
||||
There are two easy ways to get a quick file server up and running. We'll show you two equivalent ways to do the same thing.
|
||||
|
||||
## Command line
|
||||
|
||||
In your terminal, change to the root directory of your site and run:
|
||||
|
||||
<pre><code class="cmd bash">caddy file-server</code></pre>
|
||||
|
||||
The default address is :2015, so load [localhost:2015](http://localhost:2015) in your browser to see your site!
|
||||
|
||||
If you don't have an index file but you want to display a file listing, use the `--browse` option:
|
||||
|
||||
<pre><code class="cmd bash">caddy file-server --browse</code></pre>
|
||||
|
||||
You can also listen on port 80 easily enough:
|
||||
|
||||
<pre><code class="cmd bash">caddy file-server --listen :80</code></pre>
|
||||
|
||||
Or set use another folder as the site root:
|
||||
|
||||
<pre><code class="cmd bash">caddy file-server --root ~/mysite</code></pre>
|
||||
|
||||
|
||||
|
||||
## Caddyfile
|
||||
|
||||
In the root of your site, create a file called `Caddyfile` with these contents:
|
||||
|
||||
```
|
||||
localhost
|
||||
|
||||
file_server
|
||||
```
|
||||
|
||||
Then, from the same directory, run:
|
||||
|
||||
<pre><code class="cmd bash">caddy run</code></pre>
|
||||
|
||||
You can then load [localhost:2015](http://localhost:2015) to see your site!
|
||||
|
||||
The [`file_server` directive](/docs/caddyfile/directives/file_server) has more options for you to customize your site. Make sure to [reload](/docs/command-line#caddy-reload) Caddy (or stop and start it again) when you change the Caddyfile!
|
||||
|
||||
If you don't have an index file but you want to display a file listing, use the `browse` argument:
|
||||
|
||||
```
|
||||
localhost
|
||||
|
||||
file_server browse
|
||||
```
|
||||
|
||||
You can also listen on port 80 easily enough:
|
||||
|
||||
```
|
||||
:80
|
||||
|
||||
file_server
|
||||
```
|
||||
|
||||
Or set use another folder as the site root:
|
||||
|
||||
```
|
||||
localhost
|
||||
|
||||
root /home/me/mysite
|
||||
file_server
|
||||
```
|
||||
|
||||
99
src/docs/markdown/quick-starts/https.md
Normal file
99
src/docs/markdown/quick-starts/https.md
Normal file
|
|
@ -0,0 +1,99 @@
|
|||
---
|
||||
title: HTTPS quick-start
|
||||
---
|
||||
|
||||
# HTTPS quick-start
|
||||
|
||||
This guide will show you how to get up and running with [fully-managed HTTPS](/docs/automatic-https) in no time.
|
||||
|
||||
**Prerequisites:**
|
||||
- Basic terminal / command line skills
|
||||
- Basic understanding of DNS
|
||||
- A registered public domain name
|
||||
- External access to ports 80 and 443
|
||||
- `caddy` and `curl` in your PATH
|
||||
|
||||
---
|
||||
|
||||
In this tutorial, replace `example.com` with your actual domain name.
|
||||
|
||||
Set your domain's A/AAAA records point to your server. You can do this by logging into your DNS provider and managing your domain name.
|
||||
|
||||
Before continuing, verify correct records with an authoritative lookup. Replace `example.com` with your domain name, and if you are using IPv6 replace `type=A` with `type=AAAA`:
|
||||
|
||||
<pre><code class="cmd bash">curl "https://cloudflare-dns.com/dns-query?name=example.com&type=A" \
|
||||
-H "accept: application/dns-json"</code></pre>
|
||||
|
||||
<aside class="tip">If you're on your home network or some other restricted intranet, you may need to forward ports or adjust firewall settings.</aside>
|
||||
|
||||
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.
|
||||
|
||||
## Caddyfile
|
||||
|
||||
This is the most common way to get HTTPS; it works for almost any kind of site.
|
||||
|
||||
Create a file called `Caddyfile` (no extension) where the first line is your domain name, for example:
|
||||
|
||||
```
|
||||
example.com
|
||||
|
||||
respond "Hello, privacy!"
|
||||
```
|
||||
|
||||
Then from the same directory, run:
|
||||
|
||||
<pre><code class="cmd bash">caddy run</code></pre>
|
||||
|
||||
You will see Caddy provision a TLS certificate and serve your site over HTTPS.
|
||||
|
||||
|
||||
## The `file-server` command
|
||||
|
||||
If all you need is a file server over HTTPS, run this command (replacing your domain name):
|
||||
|
||||
<pre><code class="cmd bash">caddy file-server --domain example.com</code></pre>
|
||||
|
||||
You will see Caddy provision a TLS certificate and serve your site over HTTPS.
|
||||
|
||||
|
||||
## The `reverse-proxy` command
|
||||
|
||||
If all you need is a simple reverse proxy over HTTPS (as a TLS terminator), run this command (replacing your domain name and actual backend address):
|
||||
|
||||
<pre><code class="cmd bash">caddy reverse-proxy --from example.com --to localhost:9000</code></pre>
|
||||
|
||||
You will see Caddy provision a TLS certificate and serve your site over HTTPS.
|
||||
|
||||
|
||||
## JSON config
|
||||
|
||||
The general rule of thumb is that any [host matcher](/docs/json/apps/http/servers/routes/match/host/) with a host that looks like a domain name will trigger automatic HTTPS.
|
||||
|
||||
Thus, a JSON config such as the following will enable production-ready [automatic HTTPS](/docs/automatic-https):
|
||||
|
||||
```json
|
||||
{
|
||||
"apps": {
|
||||
"http": {
|
||||
"servers": {
|
||||
"hello": {
|
||||
"listen": [":443"],
|
||||
"routes": [
|
||||
{
|
||||
"match": [{
|
||||
"host": ["example.com"]
|
||||
}],
|
||||
"handle": [{
|
||||
"handler": "static_response",
|
||||
"body": "Hello, privacy!"
|
||||
}]
|
||||
}
|
||||
]
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
65
src/docs/markdown/quick-starts/reverse-proxy.md
Normal file
65
src/docs/markdown/quick-starts/reverse-proxy.md
Normal file
|
|
@ -0,0 +1,65 @@
|
|||
---
|
||||
title: Reverse proxy quick-start
|
||||
---
|
||||
|
||||
# Reverse proxy quick-start
|
||||
|
||||
This guide will show you how to get a production-ready reverse proxy up and running quickly.
|
||||
|
||||
**Prerequisites:**
|
||||
- Basic terminal / command line skills
|
||||
- `caddy` in your PATH
|
||||
- A running backend process to proxy to
|
||||
|
||||
---
|
||||
|
||||
There are two easy ways to get a quick reverse proxy up and running. We'll show you two equivalent ways to do the same thing.
|
||||
|
||||
This tutorial assumes you have a backend HTTP service running on `127.0.0.1:9000`.
|
||||
|
||||
|
||||
## Command line
|
||||
|
||||
In your terminal, run this command:
|
||||
|
||||
<pre><code class="cmd bash">caddy reverse-proxy --to 127.0.0.1:9000</code></pre>
|
||||
|
||||
Caddy's default address is :2015, so make a request to [localhost:2015](http://localhost:2015) to see it working!
|
||||
|
||||
It's easy to change the proxy's address:
|
||||
|
||||
<pre><code class="cmd bash">caddy reverse-proxy --from :2016 --to 127.0.0.1:9000</code></pre>
|
||||
|
||||
Now you can access the proxy at [localhost:2016](http://localhost:2016).
|
||||
|
||||
|
||||
|
||||
## Caddyfile
|
||||
|
||||
In the current working directory, create a file called `Caddyfile` with these contents:
|
||||
|
||||
```
|
||||
localhost
|
||||
|
||||
reverse_proxy 127.0.0.1:9000
|
||||
```
|
||||
|
||||
Then, from the same directory, run:
|
||||
|
||||
<pre><code class="cmd bash">caddy run</code></pre>
|
||||
|
||||
You can then make a request to [localhost:2015](http://localhost:2015) to see it working!
|
||||
|
||||
It's easy to change the proxy's address:
|
||||
|
||||
```
|
||||
:2016
|
||||
|
||||
reverse_proxy 127.0.0.1:9000
|
||||
```
|
||||
|
||||
Make sure to [reload](/docs/command-line#caddy-reload) Caddy (or stop and start it again) when you change the Caddyfile.
|
||||
|
||||
Now you can access the proxy at [localhost:2016](http://localhost:2016).
|
||||
|
||||
There is a lot more you can do with the [`reverse_proxy` directive](/docs/caddyfile/directives/reverse_proxy).
|
||||
Loading…
Add table
Add a link
Reference in a new issue