diff --git a/src/docs/markdown/caddyfile/directives/php_fastcgi.md b/src/docs/markdown/caddyfile/directives/php_fastcgi.md index 7ab7183..40e43df 100644 --- a/src/docs/markdown/caddyfile/directives/php_fastcgi.md +++ b/src/docs/markdown/caddyfile/directives/php_fastcgi.md @@ -18,11 +18,11 @@ An opinionated directive that proxies requests to a PHP FastCGI server such as p - [Explanation](#explanation) - [Examples](#examples) -Caddy's [`reverse_proxy`](/docs/caddyfile/directives/reverse_proxy) is capable of serving any FastCGI application, but this directive is tailored specifically for PHP apps. This directive is actually just a convenient way to use a longer, more common configuration (below). +Caddy's [`reverse_proxy`](reverse_proxy) is capable of serving any FastCGI application, but this directive is tailored specifically for PHP apps. This directive is a convenient shortcut, replacing a [longer configuration](#expanded-form). -It expects that any `index.php` at the site root acts as a router. If that is not desirable, either reconfigure the `try_files` option to modify the default rewrite behaviour, or take the [expanded form](#expanded-form) below as a basis and customize it to your needs. +It expects that any `index.php` at the site root acts as a router. If that is not desirable, either reconfigure the [`try_files` subdirective](#try_files) to modify the default rewrite behaviour, or take the [expanded form](#expanded-form) as a basis and customize it to your needs. -It supports all the subdirectives of [`reverse_proxy`](/docs/caddyfile/directives/reverse_proxy) and passes them through to the underlying `reverse_proxy` handler, plus a few subdirectives that customize the FastCGI transport specifically. +In addition to the subdirectives listed below, this directive also supports all the subdirectives of [`reverse_proxy`](reverse_proxy#syntax). For example, you may enable load balancing and health checks. **Most modern PHP apps work fine without extra subdirectives or customization.** Subdirectives are usually only used in certain edge cases or with legacy PHP apps. @@ -32,43 +32,43 @@ It supports all the subdirectives of [`reverse_proxy`](/docs/caddyfile/directive php_fastcgi [] { root split - env [ ] index |off try_files + env [ ] resolve_root_symlink + capture_stderr dial_timeout read_timeout write_timeout - capture_stderr } ``` -- **** are the [addresses](/docs/conventions#network-addresses) of the FastCGI servers. +- **** are the [addresses](/docs/conventions#network-addresses) of the FastCGI servers. Typically, either a TCP socket, or a unix socket file. -- **root** sets the root folder to the site. Default: [`root` directive](/docs/caddyfile/directives/root). +- **root** sets the root folder to the site. It's recommended to always use the [`root` directive](root) in conjunction with `php_fastcgi`, but overriding this can be useful when your PHP-FPM upstream is using a different root than Caddy (see [an example](#docker)). Defaults to the value of the [`root` directive](root) if used, otherwise defaults to Caddy's current working directory. - **split** sets the substrings for splitting the URI into two parts. The first matching substring will be used to split the "path info" from the path. The first piece is suffixed with the matching substring and will be assumed as the actual resource (CGI script) name. The second piece will be set to PATH_INFO for the CGI script to use. Default: `.php` -- **env** sets an extra environment variable to the given value. Can be specified more than once for multiple environment variables. +- **index** specifies the filename to treat as the directory index file. This affects the file matcher in the [expanded form](#expanded-form). Default: `index.php`. Can be set to `off` to disable rewrite fallback to `index.php` when a matching file is not found. -- **index** specifies the filename to treat as the directory index file. This affects the file matcher in the [expanded form](#expanded-form). Default: `index.php`. Can be set to `off` to disable rewriting to `index.php` when a matching file is not found. +- **try_files** specifies an override for the default try-files rewrite. See the [`try_files` directive](try_files) for details. Default: `{path} {path}/index.php index.php`. -- **try_files** specifies an override for the default try-files rewrite. See the [`try_files` directive](/docs/caddyfile/directives/try_files) for details. Default: `{path} {path}/index.php index.php`. +- **env** sets an extra environment variable to the given value. Can be specified more than once for multiple environment variables. By default, all the relevant FastCGI environment variables are already set (including HTTP headers) but you may add or override variables as needed. -- **resolve_root_symlink** enables resolving the `root` directory to its actual value by evaluating a symbolic link, if one exists. - -- **dial_timeout** is how long to wait when connecting to the upstream socket. Accepts [duration values](/docs/conventions#durations). Default: `3s`. - -- **read_timeout** is how long to wait when reading from the FastCGI server. Accepts [duration values](/docs/conventions#durations). Default: no timeout. - -- **write_timeout** is how long to wait when sending to the FastCGI server. Accepts [duration values](/docs/conventions#durations). Default: no timeout. +- **resolve_root_symlink** when the [`root`](#root) directory is a symbolic link (symlink), this enables resolving it to its actual value. This is sometimes used as a deployment strategy, by simply swapping the symlink to point to the new version in another directory. Disabled by default to avoid repeated system calls. - **capture_stderr** enables capturing and logging of any messages sent by the upstream fastcgi server on `stderr`. Logging is done at `WARN` level by default. If the response has a `4xx` or `5xx` status, then the `ERROR` level will be used instead. By default, `stderr` is ignored. +- **dial_timeout** is a [duration value](/docs/conventions#durations) that sets how long to wait when connecting to the upstream socket. Default: `3s`. -Since this directive is an opinionated wrapper over a reverse proxy, you can use any of [`reverse_proxy`](/docs/caddyfile/directives/reverse_proxy#syntax)'s subdirectives to customize it. +- **read_timeout** is a [duration value](/docs/conventions#durations) that sets how long to wait when reading from the FastCGI upstream. Default: no timeout. + +- **write_timeout** is a [duration value](/docs/conventions#durations) that sets how long to wait when sending to the FastCGI upstream. Default: no timeout. + + +Since this directive is an opinionated wrapper over a reverse proxy, you can use any of [`reverse_proxy`](reverse_proxy#syntax)'s subdirectives to customize it. ## Expanded form @@ -105,25 +105,25 @@ route { - The first section deals with canonicalizing the request path. The goal is to ensure that requests that target a directory on disk actually have the trailing slash `/` added to the request path, so that only a single URL is valid for requests to that directory. - This is performed by using a request matcher that matches only requests that _don't_ end in a slash, and which map to a directory on disk which contains an `index.php` file, and if it matches, performs a HTTP 308 redirect with the trailing slash appended. So, for example it would redirect the request to path `/foo` to `/foo/` (appending a `/`, to canonicalize the path to the directory), if `/foo/index.php` exists on disk. + This is performed by using a request matcher that matches only requests that _don't_ end in a slash, and which map to a directory on disk which contains an `index.php` file, and if it matches, performs a HTTP 308 redirect with the trailing slash appended. So for example, it would redirect a request with path `/foo` to `/foo/` (appending a `/`, to canonicalize the path to the directory), if `/foo/index.php` exists on disk. - The next section deals with performing path rewrites based on whether a matching file exists on disk. This also has the side-effect of remembering the part of the path after `.php` (if the request path had `.php` in it). This is important for Caddy to correctly set the FastCGI environment variables. - - First, it checks if `{path}` is a file that exists on disk. If so, it rewrites to that path. This essentially short-circuits the rest, and makes sure that requests to files that _do_ exists on disk don't get otherwise rewritten (see next steps below). So if for example you have a `/js/app.js` file on disk, then the request to that path will be kept the same. + - First, it checks if `{path}` is a file that exists on disk. If so, it rewrites to that path. This essentially short-circuits the rest, and makes sure that requests to files that _do exist_ on disk don't get otherwise rewritten (see next steps below). So if for example you have a `/js/app.js` file on disk, then the request to that path will be kept the same. - - Second, it checks if `{path}/index.php` is a file that exists on disk. If so, it rewrites to that path. For requests to a directory like `/foo/` it'll then look for `/foo//index.php` (which gets normalized to `/foo/index.php`), and rewrite the request to that path if it exists. This behaviour is sometimes useful if you're running a PHP app in a subdirectory of another. + - Second, it checks if `{path}/index.php` is a file that exists on disk. If so, it rewrites to that path. For requests to a directory like `/foo/` it'll then look for `/foo//index.php` (which gets normalized to `/foo/index.php`), and rewrite the request to that path if it exists. This behaviour is sometimes useful if you're running another PHP app in a subdirectory of your webroot. - Lastly, it'll rewrite to `index.php` if that file exists (it almost always should for modern PHP apps). This allows your PHP app to handle any request for paths that _don't_ map to files on disk, by using the `index.php` script as its entrypoint. - And finally, the last section is what actually proxies the request to your PHP FastCGI (or PHP-FPM) service to actually run your PHP code. The request matcher will only match requests which end in `.php`, so, any file that _isn't_ a PHP script and that _does_ exist on disk, will _not_ be handled by this directive, and will fall through. -The `php_fastcgi` directive is not usually enough on its own. It should almost always be paired with the [`root` directive](/docs/caddyfile/directives/root) to set the location of your files on disk (for modern PHP apps, this may be `/var/www/html/public`, where the `public` directory is what contains your `index.php`), and the [`file_server` directive](/docs/caddyfile/directives/file_server) to serve your static files (your JS, CSS, images, etc) which aren't otherwise handled by this directive and fell through. +The `php_fastcgi` directive is not usually enough on its own. It should almost always be paired with the [`root` directive](root) to set the location of your files on disk (for modern PHP apps, this may be `/var/www/html/public`, where the `public` directory is what contains your `index.php`), and the [`file_server` directive](file_server) to serve your static files (your JS, CSS, images, etc) which aren't otherwise handled by this directive and fell through. ## Examples -Proxy all PHP requests to a FastCGI responder listening at 127.0.0.1:9000: +Proxy all PHP requests to a FastCGI responder listening at `127.0.0.1:9000`: ```caddy-d php_fastcgi 127.0.0.1:9000 @@ -132,24 +132,48 @@ php_fastcgi 127.0.0.1:9000 Same, but only for requests under `/blog/`: ```caddy-d -php_fastcgi /blog/* 127.0.0.1:9000 +php_fastcgi /blog/* localhost:9000 ``` -When using php-fpm listening via a unix socket: +When using PHP-FPM listening via a unix socket: ```caddy-d php_fastcgi unix//run/php/php8.2-fpm.sock ``` -The [`root` directive](/docs/caddyfile/directives/root) is typically used to specify the directory containing the PHP scripts, and the [`file_server` directive](/docs/caddyfile/directives/file_server) to serve static files: +The [`root` directive](root) is almost always used to specify the directory containing the PHP scripts, and the [`file_server` directive](file_server) to serve static files: -```caddy-d -root * /var/www/html/public -php_fastcgi 127.0.0.1:9000 -file_server +```caddy +example.com { + root * /var/www/html/public + php_fastcgi 127.0.0.1:9000 + file_server +} ``` -For a PHP site which does not use `index.php` as an entrypoint, you may fallback to emitting a `404` error instead. The error may be handled with the [`handle_errors` directive](/docs/caddyfile/directives/handle_errors): + When serving multiple PHP apps with Caddy, your webroot for each app must be different so that Caddy can read and serve your static files separately and detect if PHP files exist. + +If you're using Docker, often your PHP-FPM containers will have the files mounted at the same root. In that case, the solution is to mount the files to your Caddy container in different directories, then use the [`root` subdirective](#root) to set the root for each container: + +```caddy +app1.example.com { + root * /srv/app1/public + php_fastcgi app1:9000 { + root /var/www/html/public + } + file_server +} + +app2.example.com { + root * /srv/app2/public + php_fastcgi app2:9000 { + root /var/www/html/public + } + file_server +} +``` + +For a PHP site which does not use `index.php` as an entrypoint, you may fallback to emitting a `404` error instead. The error may be caught and handled with the [`handle_errors` directive](handle_errors): ```caddy-d php_fastcgi localhost:9000 { diff --git a/src/docs/markdown/caddyfile/directives/reverse_proxy.md b/src/docs/markdown/caddyfile/directives/reverse_proxy.md index fba3197..5a223bc 100644 --- a/src/docs/markdown/caddyfile/directives/reverse_proxy.md +++ b/src/docs/markdown/caddyfile/directives/reverse_proxy.md @@ -731,7 +731,7 @@ handle_path /old-prefix/* { ``` -X-Accel-Redirect support, i.e. serving static files as requested by the proxy upstream: +`X-Accel-Redirect` support, i.e. serving static files as requested by the proxy upstream: ```caddy-d reverse_proxy localhost:8080 { @@ -760,7 +760,7 @@ reverse_proxy localhost:8080 { ``` -Get backends dynamically from A/AAAA record DNS queries: +Get backends dynamically from `A`/`AAAA` record DNS queries: ```caddy-d reverse_proxy { @@ -769,7 +769,7 @@ reverse_proxy { ``` -Get backends dynamically from SRV record DNS queries: +Get backends dynamically from `SRV` record DNS queries: ```caddy-d reverse_proxy { diff --git a/src/docs/markdown/caddyfile/options.md b/src/docs/markdown/caddyfile/options.md index 334d921..abf7836 100644 --- a/src/docs/markdown/caddyfile/options.md +++ b/src/docs/markdown/caddyfile/options.md @@ -206,7 +206,7 @@ Customizing the storage module is typically needed when syncing Caddy's storage ##### `storage_clean_interval` -How often to scan storage units for old or expired assets and remove them. These scans exert lots of reads (and list operations) on the storage module, so choose a longer interval for large deployments. The value is a [duration value](/docs/conventions#durations). Default: `24h`. +How often to scan storage units for old or expired assets and remove them. These scans exert lots of reads (and list operations) on the storage module, so choose a longer interval for large deployments. Accepts [duration values](/docs/conventions#durations). Default: `24h`. Storage will always be cleaned when the process first starts. Then, a new cleaning will be started this duration after the previous cleaning started if the previous cleaning finished in less than half the time of this interval (otherwise next start will be skipped).