docs: expand PHP-FPM tuning section with real guidance#14923
Open
skjnldsv wants to merge 2 commits into
Open
Conversation
Contributor
📖 Documentation Preview📄 1 changed documentation pageLast updated: Wed, 20 May 2026 05:13:25 GMT |
This comment has been minimized.
This comment has been minimized.
This comment has been minimized.
This comment has been minimized.
skjnldsv
force-pushed
the
fix/php-fpm-documentation
branch
from
72b3576 to
cc5d93d
Compare
Replace the two-sentence stub with real content covering: - pm modes (dynamic/static/ondemand) with trade-offs and Nextcloud guidance (ondemand not recommended; sync clients cause repeated cold starts) - Key parameters: pm.max_children, start/min/max spare servers, pm.max_requests, pm.process_idle_timeout — with the RAM-based sizing formula and how to measure actual worker RSS - Example dynamic config for 2 GB PHP RAM - Slow log setup (slowlog + request_slowlog_timeout) - Troubleshooting section: 502, 504, memory growth, cold-start lag - Cross-reference to source_installation.rst for pool/env-var detail Fixes #11591 Signed-off-by: skjnldsv <skjnldsv@protonmail.com>
skjnldsv
force-pushed
the
fix/php-fpm-documentation
branch
from
cc5d93d to
5e0c688
Compare
The list-table with widths 15/85 caused horizontal overflow in the rendered HTML. Definition list avoids the issue and is more idiomatic RST for key-value mode descriptions. Signed-off-by: John Molakvoæ (skjnldsv) <skjnldsv@protonmail.com>
skjnldsv
requested review from
Altahrim,
artonge,
come-nc,
joshtrichards,
pringelmann and
szaimen
skjnldsv
force-pushed
the
fix/php-fpm-documentation
branch
from
ad8ff8a to
df99ddc
Compare
artonge
reviewed
May 20, 2026
|
|
||
| Measure the average RSS of a running pool:: | ||
|
|
||
| ps --no-headers -o rss -C php-fpm8.3 | awk '{sum+=$1} END {print sum/NR/1024 " MB"}' |
Contributor
There was a problem hiding this comment.
This command assume some php process are running, right? Maybe we need to specify it. Else, I got the following error: awk: cmd. line:1: fatal: division by zero attempted
| directory trees. Use the slow log to identify the bottleneck. | ||
|
|
||
| **Memory grows over time** | ||
| Workers are leaking memory (Imagick and XML parsers are common sources). |
Contributor
There was a problem hiding this comment.
Are Imagick and XML parsers really at fault? Do we have some sources for that?
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
☑️ Resolves
Summary
The existing "Tune PHP-FPM" section in
server_tuning.rstwas a two-sentencestub that linked to an external calculator without explaining anything. PHP-FPM is
the only option for Nginx setups and a frequent source of performance problems
(502s, 504s, sync failures) when misconfigured — yet the docs gave admins nothing
to work with.
This PR replaces the stub with a full section covering:
dynamic/static/ondemand) — behaviour,trade-offs, and Nextcloud-specific guidance (
ondemandnot recommended becausedesktop/mobile clients poll every 30s, causing repeated cold-start latency)
pm.max_children,pm.start_servers,pm.min_spare_servers/pm.max_spare_servers,pm.max_requests,pm.process_idle_timeout— with the RAM-based sizing formula and how tomeasure actual worker RSS from a live pool
dynamicconfig as a starting point for a 2 GB PHP-RAM serverslowlog+request_slowlog_timeout) for identifyingbottlenecks
504, memory growth over time, and cold-start lag
source_installation.rst(php_fpm_tips_label) for poolconfig details (env vars, upload sizes, Unix socket vs TCP) to avoid duplication
Content researched from: PHP manual (
install.fpm.configuration), the Mediumarticle linked in the issue, and existing Nextcloud pool config notes in
source_installation.rst.🖼️ Screenshots
✅ Checklist
codespellor similar and addressed any spelling issues