From 360c3b2ad0eb669a3818461bb4e396aa6b730e74 Mon Sep 17 00:00:00 2001 From: Matt Holt Date: Sun, 17 May 2020 16:29:01 -0600 Subject: [PATCH] docs: New page: common Caddyfile patterns (#42) * docs: New common uses page for Caddyfile * Apply the quick and easy suggestions from code review Co-authored-by: Francis Lavoie * Apply discussions from code review * Add syntax highlighting to php_fastcgi docs * Rename page and add more links to it Co-authored-by: Francis Lavoie --- src/docs/markdown/caddyfile-tutorial.md | 1 + src/docs/markdown/caddyfile.md | 3 +- src/docs/markdown/caddyfile/patterns.md | 127 ++++++++++++++++++++ src/docs/markdown/quick-starts/caddyfile.md | 1 + src/includes/docs-nav.html | 1 + 5 files changed, 132 insertions(+), 1 deletion(-) create mode 100644 src/docs/markdown/caddyfile/patterns.md diff --git a/src/docs/markdown/caddyfile-tutorial.md b/src/docs/markdown/caddyfile-tutorial.md index e70bc77..3d8ed5d 100644 --- a/src/docs/markdown/caddyfile-tutorial.md +++ b/src/docs/markdown/caddyfile-tutorial.md @@ -263,5 +263,6 @@ One last thing that you will find most helpful: if you want to remark or note an ## Further reading +- [Common patterns](/docs/caddyfile/patterns) - [Caddyfile concepts](/docs/caddyfile/concepts) - [Directives](/docs/caddyfile/directives) \ No newline at end of file diff --git a/src/docs/markdown/caddyfile.md b/src/docs/markdown/caddyfile.md index 19da678..638f218 100644 --- a/src/docs/markdown/caddyfile.md +++ b/src/docs/markdown/caddyfile.md @@ -18,7 +18,7 @@ file_server (That's a real, production-ready Caddyfile that serves WordPress with fully-managed HTTPS.) -The basic idea is that you first type the address of your site, then the features or functionality you need your site to have. +The basic idea is that you first type the address of your site, then the features or functionality you need your site to have. [View more common patterns.](/docs/caddyfile/patterns) ## Menu @@ -28,6 +28,7 @@ The basic idea is that you first type the address of your site, then the feature - #### [Directives](/docs/caddyfile/directives) - #### [Request matchers](/docs/caddyfile/matchers) - #### [Global options](/docs/caddyfile/options) +- #### [Common patterns](/docs/caddyfile/patterns) diff --git a/src/docs/markdown/caddyfile/patterns.md b/src/docs/markdown/caddyfile/patterns.md new file mode 100644 index 0000000..7589f62 --- /dev/null +++ b/src/docs/markdown/caddyfile/patterns.md @@ -0,0 +1,127 @@ +--- +title: Common Caddyfile Patterns +--- + +# Common Caddyfile Patterns + +This page demonstrates a few complete and minimal Caddyfile configurations for common use cases. These can be helpful starting points for your own Caddyfile documents. + +These are not drop-in solutions; you will have to customize your domain name, ports/sockets, directory paths, etc. They are intended to illustrate some of the most common configuration patterns. + +#### Menu + +- [Static file server](#static-file-server) +- [Reverse proxy](#reverse-proxy) +- [PHP](#php) +- [Redirect `www.` subdomain](#redirect-www-subdomain) +- [Trailing slashes](#trailing-slashes) + + +## Static file server + +```caddy +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). + + +## Reverse proxy + +Proxy all requests: + +```caddy +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 +``` + + +## PHP + +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 +``` + +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. + +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). + + +## Redirect `www.` subdomain + +To **add** the `www.` subdomain with an HTTP redirect: + +```caddy +example.com { + redir https://www.example.com{uri} +} + +www.example.com { +} +``` + + +To **remove** it: + +```caddy +www.example.com { + redir https://example.com{uri} +} + +example.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. + +However, if you need to, you can still enforce trailing slashes with your config. There are two ways to do it: internally or externally. + +### Internal enforcement + +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 +``` + +Using a rewrite, requests with and without the trailing slash will be the same. + + +### External enforcement + +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 +``` + +Using a redirect, the client will have to re-issue the request, enforcing a single acceptable URI for a resource. diff --git a/src/docs/markdown/quick-starts/caddyfile.md b/src/docs/markdown/quick-starts/caddyfile.md index 0c498f1..30539f7 100644 --- a/src/docs/markdown/quick-starts/caddyfile.md +++ b/src/docs/markdown/quick-starts/caddyfile.md @@ -76,5 +76,6 @@ When you are done with Caddy, make sure to stop it: ## Further reading +- [Common patterns](/docs/caddyfile/patterns) - [Caddyfile concepts](/docs/caddyfile/concepts) - [Directives](/docs/caddyfile/directives) \ No newline at end of file diff --git a/src/includes/docs-nav.html b/src/includes/docs-nav.html index 6dfbfbc..65ee2e4 100644 --- a/src/includes/docs-nav.html +++ b/src/includes/docs-nav.html @@ -32,6 +32,7 @@
  • Directives
  • Request matchers
  • Global options
    • +
  • Common patterns
  • Modules