Skip to content

Documentation: recommend the fpm variant with its built-in Apache, PHP-FPM pools and v6 roadmap - #427

Merged
mistraloz merged 3 commits into
thecodingmachine:v5from
mistraloz:docs/maintenance-fpm-v6
Nov 5, 2026
Merged

mistraloz merged 3 commits into
thecodingmachine:v5from
mistraloz:docs/maintenance-fpm-v6

Conversation

@mistraloz

Copy link
Copy Markdown
Collaborator

Summary

Depends on #426 (this PR contains its commit, the diff will shrink once it is merged).

This PR is a maintenance update of the documentation:

  • Bug
  • Feature
  • Breaking changes

php2shell is no longer the main news of the images. The README now highlights the fpm variant with its built-in Apache, the recommended way to serve a web application (2 to 3 times more traffic with 4 times less memory than mod_php, see the benchmark):

  • the README banner presents the built-in Apache of the fpm variant instead of php2shell;
  • the usage examples start with the fpm variant and its built-in Apache, the apache variant comes last;
  • the apache section of docs/variants.md recommends the fpm variant for new applications;
  • php2shell is mentioned in the supported versions, and its page stays available;
  • a new Roadmap section links to the v6 roadmap (Roadmap #359).

It also documents two questions of #190 in docs/fpm.md:

  • an application outside /var/www/html (APACHE_DOCUMENT_ROOT and working directory);
  • additional PHP-FPM pools with their own settings, routed by the built-in Apache (LocationMatch + SetHandler) or
    by your own web server.

Fixes #190

Test plan (required)

Documentation only: make blueprint, links checked. The examples of docs/fpm.md were run on a PHP 8.4 fpm image:

  • /info.php is served by the www pool (memory_limit=128M), /wp-admin/info.php by the admin pool
    (memory_limit=512M), a missing /wp-admin/*.php file gets a 404, the workers of both pools run as docker;
  • the application mounted in /var/www with APACHE_DOCUMENT_ROOT=/var/www/public is served;
  • without the built-in Apache, the admin pool starts without warning.

Checklist

  • I followed the guidelines in CONTRIBUTING guide
  • I have squashed any insignificant commits
  • This change has comments for package types, values, functions, and non-obvious lines of code

@mistraloz
mistraloz merged commit a3d037b into thecodingmachine:v5 Nov 5, 2026
25 checks passed
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

Changing app dir for php-fpm / multiple pools

1 participant