From b056525026b066c1998eb58803b0201f13343c1d Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?K=C3=A9vin=20Dunglas?= <kevin@dunglas.fr>
Date: Mon, 26 Aug 2024 22:11:43 +0200
Subject: [PATCH] docs: add performance docs

---
 docs/config.md               |  1 +
 docs/performance.md          | 68 ++++++++++++++++++++++++++++++++++++
 testdata/benchmark.Caddyfile |  5 ++-
 3 files changed, 73 insertions(+), 1 deletion(-)
 create mode 100644 docs/performance.md

diff --git a/docs/config.md b/docs/config.md
index c114ee0da..c332fed11 100644
--- a/docs/config.md
+++ b/docs/config.md
@@ -127,6 +127,7 @@ php_server [<matcher>] {
 	split_path <delim...> # 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 script to use. Default: `.php`
 	resolve_root_symlink false # Disables resolving the `root` directory to its actual value by evaluating a symbolic link, if one exists (enabled by default).
 	env <key> <value> # Sets an extra environment variable to the given value. Can be specified more than once for multiple environment variables.
+	file_server off # Disables the built-in file_server directive.
 }
 ```
 
diff --git a/docs/performance.md b/docs/performance.md
new file mode 100644
index 000000000..0f16434a8
--- /dev/null
+++ b/docs/performance.md
@@ -0,0 +1,68 @@
+# Performance
+
+By default, FrankenPHP tries to offer a good compromise between performance and ease of use.
+However, it is possible to slightly improve performance using the appropriate configuration.
+
+## Number of Threads and of Workers
+
+By default, FrankenPHP starts 2 times more threads and workers (in worker mode) than the available numbers of CPU.
+
+The appropriate values depend heavily on how your application is written, what it does and your hardware.
+We strongly recommend to change these values.
+
+To find the right values, it's best to try out different values and run load tests simulating real traffic.
+[k6](https://k6.io) and [Gatling](https://gatling.io) are good tools for this.
+
+## Worker Mode
+
+Enabling [the worker mode](worker.md) will dramatically improve the performance,
+but your app must be adapted to be comptible with this mode:
+you need to create a worker script and to be sure that the app is not leaking memory.
+
+## Go Runtime Configuration
+
+FrankenPHP is written and Go.
+
+In general, the Go runtime doesn't require any special configuration, but in certain circumstances it can be helped to perform better.
+
+You likely want to set the `GODEBUG` environement variable to `cgocheck=0` (the default in the FrankenPHP Docker images).
+
+If you run FrankenPHP in containers (Docker, Kubernetes, LXC...) and limit the memory available for the containers,
+set the `GOMEMLIMIT` environement variable to the available amount of memory.
+
+For more details, [the Go documentation page dedicated to this subject](https://pkg.go.dev/runtime#hdr-Environment_Variables) is a must-read to get the most out of the runtime.
+
+## `file_server`
+
+By default, the `php_server` directive automatically sets up a file server to
+serve static files (assets) stored in the root directory.
+
+This feature is convenient, but comes with a cost.
+To disable it, use the following config:
+
+```caddyfile
+php_server {
+    file_server off
+}
+```
+
+## Placeholders
+
+You can use [placeholders](https://caddyserver.com/docs/conventions#placeholders) in the `root` and `env` directives.
+However, this prevent caching these values, and comes with a significant performance cost.
+
+If possible, avoid placeholders in these directives.
+
+## `resolve_root_symlink`
+
+By default, if the document root is a symbolic link, it is automatically resolved by FrankenPHP (this is needed by PHP).
+If the document root is not a symlink, you can disable this feature.
+
+```caddyfile
+php_server {
+    resolve_root_symlink false
+}
+```
+
+This will improve performance if the `root` directive contains [placeholders](https://caddyserver.com/docs/conventions#placeholders). The gain will be negilible in other cases.
+
diff --git a/testdata/benchmark.Caddyfile b/testdata/benchmark.Caddyfile
index 5d061fa4c..ceec74a9c 100644
--- a/testdata/benchmark.Caddyfile
+++ b/testdata/benchmark.Caddyfile
@@ -7,6 +7,9 @@ http:// {
 		root * .
 
 		encode zstd br gzip
-		php_server
+		php_server {
+			file_server off
+			resolve_root_symlink false
+		}
 	}
 }