From 9791668f48d8de339c17642bd4d98877466191f6 Mon Sep 17 00:00:00 2001 From: Francis Lavoie Date: Sun, 17 May 2020 19:00:02 -0400 Subject: [PATCH] docs: Cross-link root, file_server, php_fastcgi directives (#45) * docs: Cross-link the `root` directive with file_server/php_fastcgi * Minor touch-ups Co-authored-by: Matthew Holt --- .../caddyfile/directives/file_server.md | 13 ++++++++++-- .../caddyfile/directives/php_fastcgi.md | 7 +++++++ .../markdown/caddyfile/directives/root.md | 21 +++++++++++++------ 3 files changed, 33 insertions(+), 8 deletions(-) diff --git a/src/docs/markdown/caddyfile/directives/file_server.md b/src/docs/markdown/caddyfile/directives/file_server.md index 7cc95ec..824dc03 100644 --- a/src/docs/markdown/caddyfile/directives/file_server.md +++ b/src/docs/markdown/caddyfile/directives/file_server.md @@ -4,7 +4,9 @@ title: file_server (Caddyfile directive) # file_server -A static file server. It works by appending the request's URI path to the [site's root path](/docs/caddyfile/directives/root). +A static file server. It works by appending the request's URI path to the [site's root path](/docs/caddyfile/directives/root). By default, it enforces canonical URIs; if necessary, requests to directories will be redirected to have a trailing forward slash, and requests to files will be redirected to strip the trailing slash. + +Most often, the `file_server` directive is paired with the [`root`](/docs/caddyfile/directives/root) directive to set file root for the whole site. ## Syntax @@ -19,7 +21,7 @@ file_server [] [browse] { ``` - **browse** enables file listings for requests to directories that do not have an index file. -- **root** sets the path to the site root for just this file server instance, overriding any other. Default: `{http.vars.root}` or the current working directory. Note: When specified as a subdirective like this, only this directive will know this root; for other directives (like [try_files](/docs/caddyfile/directives/try_files) or [templates](/docs/caddyfile/directives/templates)) to know the same site root, use the [root](/docs/caddyfile/directives/root) directive, not subdirective. +- **root** sets the path to the site root for just this file server instance, overriding any other. Default: `{http.vars.root}` or the current working directory. Note: This subdirective only changes the root for this directive. For other directives (like [`try_files`](/docs/caddyfile/directives/try_files) or [`templates`](/docs/caddyfile/directives/templates)) to know the same site root, use the [`root`](/docs/caddyfile/directives/root) directive, not this subdirective. - **hide** is a list of files to hide; if requested, the file server will pretend they do not exist. The active configuration file will be added by default. - **index** is a list of filenames to look for as index files. Default: `index.html index.txt` - **** is an optional custom template file to use for directory listings. @@ -44,3 +46,10 @@ Only serve static files out of the `/static` folder: ```caddy-d file_server /static/* ``` + +The `file_server` directive is usually paired with the [`root` directive](/docs/caddyfile/directives/root) to set the root path from which to serve files: + +```caddy-d +root * /home/user/public_html +file_server +``` diff --git a/src/docs/markdown/caddyfile/directives/php_fastcgi.md b/src/docs/markdown/caddyfile/directives/php_fastcgi.md index ef75233..fa9ae83 100644 --- a/src/docs/markdown/caddyfile/directives/php_fastcgi.md +++ b/src/docs/markdown/caddyfile/directives/php_fastcgi.md @@ -79,3 +79,10 @@ When using php-fpm listening via a unix socket: ```caddy-d php_fastcgi unix//run/php/php7.4-fpm.sock ``` + +The [`root` directive](/docs/caddyfile/directives/root) is often used to specify the directory containing the PHP files: + +```caddy-d +root * /var/www/html +php_fastcgi 127.0.0.1:9000 +``` \ No newline at end of file diff --git a/src/docs/markdown/caddyfile/directives/root.md b/src/docs/markdown/caddyfile/directives/root.md index 62b6c11..34d0613 100644 --- a/src/docs/markdown/caddyfile/directives/root.md +++ b/src/docs/markdown/caddyfile/directives/root.md @@ -8,6 +8,8 @@ Sets the root path of the site, used by various matchers and directives that acc Specifically, this directive sets the `{http.vars.root}` placeholder. It is mutually exclusive to other `root` directives in the same block, so it is safe to define multiple roots with matchers that intersect: they will not cascade and overwrite each other. +This directive does not automatically enable serving static files, so it is often used in conjunction with the [`file_server` directive](/docs/caddyfile/directives/file_server) or the [`php_fastcgi` directive](/docs/caddyfile/directives/php_fastcgi). + ## Syntax @@ -17,28 +19,35 @@ root [] - **<path>** is the path to use for the site root. -Note that a matcher token is usually required since the first argument is a path, which could look like a path matcher. +Note that the `` argument could be confused by the parser as a [matcher token](/docs/caddyfile/matchers#syntax) if the it begins with `/`. To disambiguate, specify a wildcard matcher token (`*`). See examples below. ## Examples Set the site root to `/home/user/public_html` for all requests: +(Note that a [wildcard matcher](/docs/caddyfile/matchers#wildcard-matchers) is required here because the first argument is ambiguous with a [path matcher](/docs/caddyfile/matchers#path-matchers).) + ```caddy-d root * /home/user/public_html ``` -(A [wildcard matcher](/docs/caddyfile/matchers#wildcard-matchers) is required in this case because the first argument is ambiguous with a [path matcher](/docs/caddyfile/matchers#path-matchers).) - Set the site root to `public_html` (relative to current working directory) for all requests: +(No matcher token is required here because our site root is a relative path, so it does not start with a forward slash and thus is not ambiguous.) + ```caddy-d root public_html ``` -(No matcher token is required here because our site root is a relative path, so it does not start with a forward slash and thus is not ambiguous.) - -Set the site root only for requests in `/foo`: +Change the site root only for requests in `/foo/*`: ```caddy-d root /foo/* /home/user/public_html/foo ``` + +The `root` directive is commonly paired with [`file_server`](/docs/caddyfile/directives/file_server) to serve static files and/or with [`php_fastcgi`](/docs/caddyfile/directives/php_fastcgi) to serve a PHP site: + +```caddy-d +root * /home/user/public_html +file_server +```