Servers and deployment: Apache and PHP-FPM, Velocity, FrankenPHP #

This page is for developers who deploy framework applications to PHP-FPM, to an application server (Laravel Octane, RoadRunner, FrankenPHP worker mode) or to Gunicorn, Puma or a servlet container. Exponential runs under three servers, all driven by ./console exp:velocity and settings/velocity.ini, and ships one command that performs every step a code change needs (Servers: Velocity, PHP-FPM and FrankenPHP).

Contents #

1. Three ways to serve
2. Rules for persistent workers
3. Deploying a change
4. What moves how
5. A release, step by step
6. Compared with other stacks

Three ways to serve #

As of 6.0.15 Velocity is part of Exponential: composer.json requires se7enxweb/exponential-velocity, so every installation has it. velocity.ini [ServerSettings] Engine ships as php (PHP's built-in server, for development); any real site sets qbix (Velocity engines, Serving the site, Deploying guide).

Rules for persistent workers #

• No per-request state in static properties or globals without a reset.
• No exit for flow control except eZExecution::cleanExit(), and never catch its exception.
• Read input through eZHTTPTool, which the kernel prepares per request, not $_POST directly.
• Event listener registrations must be idempotent.
• A changed class or setting reaches the workers only after a restart; a new kernel class needs --kernel.

These are the same rules Octane or RoadRunner impose; write code that keeps them and it behaves the same under PHP-FPM (Velocity: the persistent-worker server).

Deploying a change #

./console exp:velocity deploy --dry-run --allow-root-user   # what it would do
./console exp:velocity deploy --allow-root-user             # the usual case
./console exp:velocity deploy --kernel --allow-root-user    # a kernel class was added or renamed

In order: extension autoloads (--kernel: kernel too), INI and template caches, the engine archive when kernel files changed (every file parsed first, so a broken file stops the deploy before any server is touched), a PHP-FPM reload when needed, the Velocity restart, then content, HTTP and template-block caches and Velocity's response cache last, so a page rendered by old code is never cached again. It prints PASS, FAIL or SKIP per step and stops at the first failure (Deploying with Velocity). --packer also clears packed stylesheets and scripts.

What moves how #

From A deployment pipeline:

A release, step by step #

1. Tests pass in CI.
2. Deploy to staging, run the upgrade steps, test.
3. Back up production.
4. Maintenance mode if the release changes data (php bin/php/maintenance.php on --allow-admin).
5. Update the code (Git or composer update <package>), run the upgrade steps.
6. ./console exp:velocity deploy (--kernel when kernel classes changed).
7. Maintenance off; verify with exp:velocity status, exp:cache status, the pages and the error log.

Rollback is the previous tag plus a backup restore when upgrade steps changed data.

Compared with other stacks #

Related pages #

• Velocity is part of Exponential 6.0.15
• FrankenPHP as the Exponential web engine
• Scaling applications
• Free documentation: this page is free to copy, translate and improve under the GNU FDL 1.3.