mirror of
https://github.com/caddyserver/website.git
synced 2025-04-22 04:56:17 -04:00
Docs for upcoming v2.5.0 release (#216)
* docs: new `log` filters in Caddyfile * docs: `renew_interval` global option * docs: Update access log example * docs: `log_credentials` global option * docs: `vars`, `vars_regexp` matchers * docs: `roll_uncompressed`, `roll_local_time` * docs: `http_redirect` listener wrapper * docs: `pki` app * docs: `strict_sni_host` options * docs: `default_bind` option * docs: `method` directive * docs: `tls internal` subdirectives * Apply suggestions from code review Co-authored-by: Matt Holt <mholt@users.noreply.github.com> * Matchers, options, file_server, reverse_proxy * More clarifications / corrections * Corrections from review * Typo fix * One more note about dynamic upstreams * Tab -> space * Update module namespaces * Update some docs about logging * `copy_response`, `copy_response_headers`, `replace_status` * `dns_challenge_domain_override` * `caddy trust`, API endpoints * `trusted_proxies` * Note about `pass_thru` being only useful inside `route` * Improve logging docs to clarify the difference * A bit of polish on patterns * request_body: Clarify error behavior * review Co-authored-by: Matt Holt <mholt@users.noreply.github.com>
This commit is contained in:
Francis Lavoie
GitHub
parent
c734cc3e64
commit
a1ddadf798
19 changed files with 575 additions and 157 deletions
|
|
@ -22,10 +22,10 @@ These are not drop-in solutions; you will have to customize your domain name, po
|
|||
## Static file server
|
||||
|
||||
```caddy
|
||||
example.com
|
||||
|
||||
root * /var/www
|
||||
file_server
|
||||
example.com {
|
||||
root * /var/www
|
||||
file_server
|
||||
}
|
||||
```
|
||||
|
||||
As usual, the first line is the site address. The [`root` directive](/docs/caddyfile/directives/root) specifies the path to the root of the site (the `*` means to match all requests, so as to disambiguate from a [path matcher](/docs/caddyfile/matchers#path-matchers))—change the path to your site if it isn't the current working directory. Finally, we enable the [static file server](/docs/caddyfile/directives/file_server).
|
||||
|
|
@ -36,19 +36,19 @@ As usual, the first line is the site address. The [`root` directive](/docs/caddy
|
|||
Proxy all requests:
|
||||
|
||||
```caddy
|
||||
example.com
|
||||
|
||||
reverse_proxy localhost:5000
|
||||
example.com {
|
||||
reverse_proxy localhost:5000
|
||||
}
|
||||
```
|
||||
|
||||
Only proxy requests having a path starting with `/api/` and serve static files for everything else:
|
||||
|
||||
```caddy
|
||||
example.com
|
||||
|
||||
root * /var/www
|
||||
reverse_proxy /api/* localhost:5000
|
||||
file_server
|
||||
example.com {
|
||||
root * /var/www
|
||||
reverse_proxy /api/* localhost:5000
|
||||
file_server
|
||||
}
|
||||
```
|
||||
|
||||
|
||||
|
|
@ -57,14 +57,15 @@ file_server
|
|||
With a PHP FastCGI service running, something like this works for most modern PHP apps:
|
||||
|
||||
```caddy
|
||||
example.com
|
||||
|
||||
root * /var/www
|
||||
php_fastcgi /blog/* localhost:9000
|
||||
file_server
|
||||
example.com {
|
||||
root * /srv/public
|
||||
encode gzip
|
||||
php_fastcgi localhost:9000
|
||||
file_server
|
||||
}
|
||||
```
|
||||
|
||||
Customize the site root and path matcher accordingly; this example assumes PHP is only in the `/blog/` subdirectory—all other requests will be served as static files.
|
||||
Customize the site root accordingly; this example assumes that your PHP app's webroot is within a `public` directory—requests for files that exist on disk will be served with `file_server`, and anything else will be routed to `index.php` for handling by the PHP app.
|
||||
|
||||
The [`php_fastcgi` directive](/docs/caddyfile/directives/php_fastcgi) is actually just a shortcut for [several pieces of configuration](/docs/caddyfile/directives/php_fastcgi#expanded-form).
|
||||
|
||||
|
|
@ -75,7 +76,7 @@ To **add** the `www.` subdomain with an HTTP redirect:
|
|||
|
||||
```caddy
|
||||
example.com {
|
||||
redir https://www.example.com{uri}
|
||||
redir https://www.{host}{uri}
|
||||
}
|
||||
|
||||
www.example.com {
|
||||
|
|
@ -95,6 +96,18 @@ example.com {
|
|||
```
|
||||
|
||||
|
||||
To remove it for **multiple domains** at once:
|
||||
|
||||
```caddy
|
||||
www.example-one.com, www.example-two.com {
|
||||
redir https://{labels.1}{labels.0}{uri}
|
||||
}
|
||||
|
||||
example-one.com, example-two.com {
|
||||
}
|
||||
```
|
||||
|
||||
|
||||
## Trailing slashes
|
||||
|
||||
You will not usually need to configure this yourself; the [`file_server` directive](/docs/caddyfile/directives/file_server) will automatically add or remove trailing slashes from requests by way of HTTP redirects, depending on whether the requested resource is a directory or file, respectively.
|
||||
|
|
@ -106,10 +119,10 @@ However, if you need to, you can still enforce trailing slashes with your config
|
|||
This uses the [`rewrite`](/docs/caddyfile/directives/rewrite) directive. Caddy will rewrite the URI internally to add or remove the trailing slash:
|
||||
|
||||
```caddy
|
||||
example.com
|
||||
|
||||
rewrite /add /add/
|
||||
rewrite /remove/ /remove
|
||||
example.com {
|
||||
rewrite /add /add/
|
||||
rewrite /remove/ /remove
|
||||
}
|
||||
```
|
||||
|
||||
Using a rewrite, requests with and without the trailing slash will be the same.
|
||||
|
|
@ -120,15 +133,16 @@ Using a rewrite, requests with and without the trailing slash will be the same.
|
|||
This uses the [`redir`](/docs/caddyfile/directives/redir) directive. Caddy will ask the browser to change the URI to add or remove the trailing slash:
|
||||
|
||||
```caddy
|
||||
example.com
|
||||
|
||||
redir /add /add/
|
||||
redir /remove/ /remove
|
||||
example.com {
|
||||
redir /add /add/
|
||||
redir /remove/ /remove
|
||||
}
|
||||
```
|
||||
|
||||
Using a redirect, the client will have to re-issue the request, enforcing a single acceptable URI for a resource.
|
||||
|
||||
|
||||
|
||||
## Wildcard certificates
|
||||
|
||||
If you need to serve multiple subdomains with the same wildcard certificate, the best way to handle them is with a Caddyfile like this, making use of the [`handle`](/docs/caddyfile/directives/handle) directive and [`host`](/docs/caddyfile/matchers#host) matchers:
|
||||
|
|
@ -159,6 +173,7 @@ If you need to serve multiple subdomains with the same wildcard certificate, the
|
|||
Note that you must enable the [ACME DNS challenge](/docs/automatic-https#dns-challenge) to have Caddy automatically manage wildcard certificates.
|
||||
|
||||
|
||||
|
||||
## Single-page apps (SPAs)
|
||||
|
||||
When a web page does its own routing, servers may receive lots of requests for pages that don't exist server-side, but which are renderable client-side as long as the singular index file is served instead. Web applications architected like this are known as SPAs, or single-page apps.
|
||||
|
|
@ -168,25 +183,25 @@ The main idea is to have the server "try files" to see if the requested file exi
|
|||
The most basic SPA config usually looks something like this:
|
||||
|
||||
```caddy
|
||||
example.com
|
||||
|
||||
root * /path/to/site
|
||||
try_files {path} /index.html
|
||||
file_server
|
||||
```
|
||||
|
||||
If your SPA is coupled with an API or other server-side-only endpoints, you will want to use `handle` blocks to treat them exclusively:
|
||||
|
||||
```caddy
|
||||
example.com
|
||||
|
||||
handle /api/* {
|
||||
reverse_proxy backend:8000
|
||||
}
|
||||
|
||||
handle {
|
||||
example.com {
|
||||
root * /path/to/site
|
||||
try_files {path} /index.html
|
||||
file_server
|
||||
}
|
||||
```
|
||||
|
||||
If your SPA is coupled with an API or other server-side-only endpoints, you will want to use `handle` blocks to treat them exclusively:
|
||||
|
||||
```caddy
|
||||
example.com {
|
||||
handle /api/* {
|
||||
reverse_proxy backend:8000
|
||||
}
|
||||
|
||||
handle {
|
||||
root * /path/to/site
|
||||
try_files {path} /index.html
|
||||
file_server
|
||||
}
|
||||
}
|
||||
```
|
||||
|
|
|
|||
Loading…
Add table
Add a link
Reference in a new issue