mirrors/caddy-website
1
0
Fork 0
mirror of https://github.com/caddyserver/website.git synced 2025-06-22 14:10:32 -04:00
Code Issues Projects Releases Packages Wiki Activity Actions

A bit of polish on patterns

Browse source
This commit is contained in:
Francis Lavoie 2022-03-11 02:00:33 -05:00
parent 2e419616b4
commit 8670d0ab74
No known key found for this signature in database
GPG key ID: E73DB3ECE64E7885
1 changed files with 59 additions and 44 deletions
Download patch file Download diff file Expand all files Collapse all files

103
src/docs/markdown/caddyfile/patterns.md
View file

@ -22,10 +22,10 @@ These are not drop-in solutions; you will have to customize your domain name, po
## Static file server ## Static file server
```caddy ```caddy
example.com example.com {
root * /var/www
root * /var/www file_server
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). 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: Proxy all requests:
```caddy ```caddy
example.com example.com {
reverse_proxy localhost:5000
reverse_proxy localhost:5000 }
``` ```
Only proxy requests having a path starting with `/api/` and serve static files for everything else: Only proxy requests having a path starting with `/api/` and serve static files for everything else:
```caddy ```caddy
example.com example.com {
root * /var/www
root * /var/www reverse_proxy /api/* localhost:5000
reverse_proxy /api/* localhost:5000 file_server
file_server }
``` ```
@ -57,14 +57,15 @@ file_server
With a PHP FastCGI service running, something like this works for most modern PHP apps: With a PHP FastCGI service running, something like this works for most modern PHP apps:
```caddy ```caddy
example.com example.com {
root * /srv/public
root * /var/www encode gzip
php_fastcgi /blog/* localhost:9000 php_fastcgi localhost:9000
file_server 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). 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 ```caddy
example.com { example.com {
redir https://www.example.com{uri} redir https://www.{host}{uri}
} }
www.example.com { 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 ## 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. 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: This uses the [`rewrite`](/docs/caddyfile/directives/rewrite) directive. Caddy will rewrite the URI internally to add or remove the trailing slash:
```caddy ```caddy
example.com example.com {
rewrite /add /add/
rewrite /add /add/ rewrite /remove/ /remove
rewrite /remove/ /remove }
``` ```
Using a rewrite, requests with and without the trailing slash will be the same. 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: 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 ```caddy
example.com example.com {
redir /add /add/
redir /add /add/ redir /remove/ /remove
redir /remove/ /remove }
``` ```
Using a redirect, the client will have to re-issue the request, enforcing a single acceptable URI for a resource. Using a redirect, the client will have to re-issue the request, enforcing a single acceptable URI for a resource.
## Wildcard certificates ## 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: 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. 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) ## 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. 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: The most basic SPA config usually looks something like this:
```caddy ```caddy
example.com 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 root * /path/to/site
try_files {path} /index.html try_files {path} /index.html
file_server 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
}
}
```