Skip to content

Add an Apache variant and let PHP-FPM finish requests on stop - #265

Merged
csandanov merged 4 commits into
masterfrom
feature/apache-variant
Nov 4, 2026
Merged

csandanov merged 4 commits into
masterfrom
feature/apache-variant

Conversation

@csandanov

Copy link
Copy Markdown
Member

Problem

Ready-to-use PHP applications such as Mautic, Matomo or Adminer can't run from a single prebuilt image based on wodby/php. The image only runs PHP-FPM, so a separate web server container must serve the application's static files. That container can't see files baked into the PHP image, so today every such application has to be built from the customer's own repository, once for the PHP image and once for the web server image.

Separately, when a PHP-FPM container is stopped, requests that are still running are cut off instead of finishing.

Cause

wodby/php has no web server, and a web server in another container only sees files that are copied into its own image or shared through a volume.

PHP-FPM only waits for running scripts on a graceful stop when process_control_timeout is set, and the image never set it.

Solution

Add an -apache variant of every PHP version. Apache runs in the same container as PHP-FPM: it serves static files and the application's own .htaccess rules, and hands PHP scripts to the PHP-FPM next to it. An application image can then be built once on top of it and run without a separate web server or a customer build. The existing images and tags don't change.

PHP-FPM now gives running scripts up to 20 seconds to finish on a graceful stop, in every image. The new PHP_FPM_PROCESS_CONTROL_TIMEOUT variable changes the limit, and 0 restores the previous behavior.

Details

  • The Dockerfile's existing build becomes the php stage; a new apache stage adds Alpine's apache2 and apache2-proxy on top of it. PHP_WEB=apache make builds the apache stage and tags it <minor>-apache; builds without a target still produce the PHP-FPM image.
  • Apache 2.4 with the event MPM runs as www-data, listens on port 80 and passes PHP scripts to 127.0.0.1:9000 over FastCGI. The configuration is rendered from APACHE_* variables, following the names of wodby/apache (documented in the README).
  • X-Forwarded-Proto: https sets HTTPS=on, matching what wodby/nginx passes to PHP-FPM. CGIPassAuth passes the Authorization header. X-Forwarded-For is applied to the client address only when APACHE_REMOTEIP_TRUSTED_PROXIES is set.
  • php-fpm-apache, the default command, runs both servers and stops the container when either exits. A stop signal gracefully stops Apache (httpd -k graceful-stop, at most APACHE_GRACEFUL_SHUTDOWN_TIMEOUT seconds) and PHP-FPM. Other commands, such as cron jobs or queue workers, run without Apache.
  • /.healthz answers 204, and the check-ready action checks Apache as well as PHP-FPM in this variant.
  • wodby may run httpd with sudo, as it may already run php-fpm. Like the PHP-FPM configuration, the Apache configuration is rendered by the entrypoint as wodby.
  • CI builds, tests, scans and publishes the variant for every PHP version and both architectures; there is no -dev variant. Release revisions get <minor>-apache-rN and <version>-apache-rN tags, and 8-apache follows the latest PHP version.

Validation

  • Built 8.4-apache and 8.4 locally from scratch with make (arm64).
  • PHP_WEB=apache make test (8/tests/apache.sh) passes:
    • configuration syntax and the Apache user;
    • PHP through PHP-FPM, static files without PHP, .htaccess rewrites;
    • HTTPS=on behind a proxy, the Authorization header;
    • hidden files denied, a missing script answers 404, /.healthz;
    • a graceful stop that lets a running request finish;
    • the container stops when PHP-FPM exits.
  • The release script produces 8.5-apache, 8-apache and 8.5-apache-r12 for the variant and unchanged tags for the other images. The workflow and action parse.
  • make -n shows every build target passes the stage, and PHP_WEB=apache PHP_DEV=1 is refused.

PHP-FPM only waits for running scripts on SIGQUIT, the image's stop
signal, when process_control_timeout is set. The image never set it, so
stopping a container cut off requests in progress. Give them up to 20
seconds by default, within Kubernetes' default 30-second grace period,
and make the limit configurable with PHP_FPM_PROCESS_CONTROL_TIMEOUT.
Ready-to-use PHP applications need a web server that can see their
static files. With the web server in another container, the files must
be built into a second image. The new apache stage runs Apache in front
of PHP-FPM in the same container, so an application image built on it
needs no separate web server.

Apache serves static files and .htaccess rules and passes PHP scripts to
the local PHP-FPM over FastCGI. X-Forwarded-Proto: https sets HTTPS=on,
as wodby/nginx does, and the Authorization header reaches PHP. The
php-fpm-apache command runs both servers, stops the container when
either exits and stops both gracefully. /.healthz answers 204 and
check-ready also checks Apache.

PHP_WEB=apache make builds and tests the stage as <minor>-apache.
Builds without a target still produce the PHP-FPM image. The variant
has its own test, apache.sh, because its PHP layer is the one run.sh
already tests.
The build matrix adds the apache variant for every PHP version and
both architectures, without development images. It is tested with
apache.sh and scanned like the other images.

Releases tag it <minor>-apache, and the latest PHP version also
<major>-apache. Revision tags follow the same pattern
(<minor>-apache-rN), and the revision aliases add <version>-apache-rN.
The variant gets no latest tag.
@csandanov
csandanov merged commit 0cb7d38 into master Nov 4, 2026
36 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.

1 participant