June 23, 2026 - CentOS 9 : Architecture & Installation Report — FrankenPHP + Magento 2 (PHP 8.5 ZTS)
1. Technical Architecture & Paradigm Shift
For over a decade, the combination of Nginx and PHP-FPM has been the industry standard for hosting demanding PHP applications like Magento 2. In that traditional model, Nginx acts as a reverse proxy that forwards HTTP requests to an isolated pool of PHP-FPM workers. While highly robust, this traditional lifecycle is strictly stateless: for every single request, the environment boots up, executes the script, and tears down. This introduces inter-process communication (IPC) overhead and constant filesystem I/O.
FrankenPHP introduces a fundamental paradigm shift that aligns PHP with modern runtimes like Node.js or Go. In a Node.js ecosystem, the application server is persistent; it stays alive in memory, listens to ports natively, and handles incoming requests instantly without re-initializing the application framework. By embedding the PHP interpreter directly into the Go-based Caddy web server via Zend Thread Safety (ZTS), FrankenPHP allows PHP to adopt this exact worker model. The application stays resident in memory, eliminating Unix/TCP socket overhead, delivering native HTTP/3 out of the box, and unlocking immense performance gains while retaining full compatibility with complex monoliths like Magento 2.
The objective of this specific implementation is to seamlessly integrate FrankenPHP with a Magento 2 (v2.4.9) project deployed in the standard Linux web directory (/var/www/html/magento2), while adhering to two major constraints:
- System & Home Directory Isolation: Utilizing the
/var/www/ path for the web root, combined with a minimal Systemd override (ProtectHome=false) to ensure FrankenPHP can interact smoothly with any local user environment assets without breaking core system security rules.
- Native Development Mode: Allowing Magento 2 to generate and serve static assets natively using Symbolic Links (Symlinks) and successfully passing the built-in security signature validation (
Sign Static Files) without tampering with the core application.
Routing Flow Mechanics:
When a browser requests a static asset that hasn't been generated yet (e.g., calendar.css):
1. Browser ➡️ Sends request with a version token (/static/versionXXXX/css...) ➡️ Caddy/FrankenPHP.
2. Caddy detects the absence of the physical file ➡️ It performs a surgical rewrite of the resource argument (removing the version token) BUT preserves the original raw URI containing the version inside $_SERVER['REQUEST_URI'].
3. Magento (static.php) validates the security signature via the raw URI, reads the cleaned resource argument, and creates the native symlink from pub/static/ to vendor/.
4. Subsequent requests hit the actual symlink ➡️ Caddy serves it instantly in HTTP/3 via its file_server without ever hitting PHP again.
2. Step-by-Step Installation & Legacy Services Cleanup
FrankenPHP relies on a worker architecture powered by threads. It strictly requires PHP extensions compiled with ZTS (Zend Thread Safety). To avoid port conflicts on 80 and 443, any legacy web server (Nginx) and PHP processor (PHP-FPM) must be stopped and disabled. We then leverage the recommended Native RPM Repository method to install FrankenPHP and its ZTS 8.5 dependencies dynamically linked with Remi's repository.
Stop and disable legacy engines to free ports 80/443 and prevent socket overlaps:
- sudo systemctl disable --now nginx php-fpm
Add the official RPM repository providing production-ready FrankenPHP builds for Enterprise Linux:
- sudo dnf config-manager --add-repo https://rpms.henderkes.de/henderkes-rpms.repo
Reset the standard single-threaded DNF PHP module to allow a custom repository override:
- sudo dnf module reset php -y
Switch to Remi's PHP 8.5 repository to align our runtime with Magento 2.4.9 prerequisites:
- sudo dnf module enable php:remi-8.5 -y
Install FrankenPHP alongside PHP-ZTS. Why PHP-ZTS? Because FrankenPHP embeds PHP directly into its Go-based server. Standard PHP is non-thread-safe (NTS) and crashes under simultaneous multi-threaded requests; ZTS (Zend Thread Safety) isolates memory per thread, enabling safe, high-performance concurrent request processing:
- sudo dnf install frankenphp php-zts-pdo php-zts-pdo-mysql php-zts-mysqlnd php-zts-intl php-zts-gd php-zts-bcmath php-zts-soap php-zts-zip php-zts-opcache php-zts-mbstring php-zts-xml -y
3. Linux Cross-Permissions & Home Directory Penetration (Standard vs ACL)
To establish a secure bridge between your local development user (PK) and the webserver, FrankenPHP requires execution rights (traverse permission) on the user's home directory. Two strategies can be deployed depending on the desired granularity:
Option A: Standard Group Strategy (Used in this setup)
FrankenPHP is added to the user's private group, and the home directory's permission is widened to 710. This grants FrankenPHP the exact execution right needed to traverse the home directory structure (--x) while blocking any other unprivileged system users.
- sudo usermod -aG PK frankenphp
- sudo chmod 710 /home/PK
Option B: Advanced ACL Strategy (Granular Alternative)
If you prefer to keep your home directory strictly private (700) without altering standard POSIX groups, you can use Linux Access Control Lists (ACLs). This explicitly targets the frankenphp user alone, granting it traverse rights without exposing the folder to a whole group.
- sudo setfacl -m u:frankenphp:--x /home/PK
Regardless of the chosen home directory traversal method, the /var/www/html/ deployment path must be configured with full group ownership and proper write access to handle Magento's dynamic code compilation and asset generation processes seamlessly:
- cd /var/www/html/
- sudo chown -R PK:frankenphp magento2
- cd magento2
- find . -type d -exec chmod 755 {} +
- find . -type f -exec chmod 644 {} +
- chmod -R 775 var/ generated/ pub/static/ pub/media/
- find var/ generated/ pub/static/ pub/media/ -type d -exec chmod g+s {} +
4. SELinux Security Considerations
On Enterprise Linux 9 systems, SELinux enforcement will immediately block FrankenPHP from serving files or executing scripts if the security contexts do not match. We must apply the correct httpd_sys_content_t context for read-only areas and httpd_sys_rw_content_t for areas where Magento needs to write or generate Symlinks at runtime.
- sudo semanage fcontext -a -t httpd_sys_content_t "/var/www/html/magento2(/.*)?"
- sudo semanage fcontext -a -t httpd_sys_rw_content_t "/var/www/html/magento2/var(/.*)?"
- sudo semanage fcontext -a -t httpd_sys_rw_content_t "/var/www/html/magento2/generated(/.*)?"
- sudo semanage fcontext -a -t httpd_sys_rw_content_t "/var/www/html/magento2/pub/static(/.*)?"
- sudo semanage fcontext -a -t httpd_sys_rw_content_t "/var/www/html/magento2/pub/media(/.*)?"
- sudo restorecon -R -v /var/www/html/magento2
Additionally, we must authorize the webserver process to communicate with the network (e.g., Database connections, Elasticsearch/OpenSearch, and Redis instances):
- sudo setsebool -P httpd_can_network_connect 1
5. Systemd Service Surcharge (Override)
To guarantee that FrankenPHP can resolve user-level operations, handle CLI tasks seamlessly, and access any required local environment configurations, the native home directory protection must be disabled.
- sudo systemctl edit frankenphp
Inside the override file, inject the following minimal configuration:
[Service]
ProtectHome=false
- sudo systemctl daemon-reload
6. Modular Caddy & FrankenPHP Configuration
To ensure a clean, maintainable infrastructure, the main Caddyfile handles global directives and dynamically includes sub-configurations. Magento 2 routing logic is isolated inside its own file.
Main File: /etc/frankenphp/Caddyfile
{
# Global Configuration
frankenphp
order php_server before file_server
}
# Include all modular site configurations
import /etc/frankenphp/Caddyfile.d/*.caddyfile
Sub-File: /etc/frankenphp/Caddyfile.d/magento2.caddyfile
magento2.localhost.com {
# Document root strictly pointing to Magento's pub/ folder
root * /var/www/html/magento2/pub
tls internal
encode zstd gzip
header {
X-Content-Type-Options "nosniff"
X-XSS-Protection "1; mode=block"
X-Frame-Options "SAMEORIGIN"
}
# 1. Handle missing versioned static assets (Sign Static Files active)
@static_versioned_missing {
path_regexp versioned ^/static/version\d+/(.+)
not file {path}
}
rewrite @static_versioned_missing /static.php?resource={re.versioned.1}
# 2. Handle missing unversioned static assets
@static_normal_missing {
path /static/*
not path_regexp ^/static/version\d+/
not file {path}
}
rewrite @static_normal_missing /static.php?resource={bits.path.strip_prefix./static/}
# 3. Handle missing media (On-the-fly catalog image resizing)
@media_missing {
path /media/*
not file {path}
}
rewrite @media_missing /get.php?resource={path}
# 4. Global application fallback router (HTML pages and root /)
@magento_fallback {
not file {path}
not path /static/* /media/*
}
rewrite @magento_fallback /index.php?{query}
# 5. Execution Engines
file_server
php_server
}
7. Deployment & Cache Clearance
To enable the RPM-managed service, apply the new architecture, and completely flush any previous 403/404 errors cached by the system or application:
- sudo systemctl enable --now frankenphp
- cd /var/www/html/magento2/
- rm -rf pub/static/frontend/* pub/static/adminhtml/* var/view_preprocessed/* var/cache/* var/page_cache/*
- sudo systemctl restart frankenphp
The core application runs flawlessly, database interactions are up, SELinux enforcement policies are respected, signatures match perfectly, and the Luma theme renders instantly via native Linux symlinks!
