Deploying a change
This page is for engineers who ship changes to a running site. Exponential keeps code in more than one runtime (PHP-FPM with OPcache, Velocity's persistent workers) and rendered output in several caches; a deploy that does the right steps in the wrong order looks as if it had not worked. The standard is Compatibility, releases and deployment; the command is documented in Deploying a PHP change.
Contents
- One command
- The steps and their order
- Which change needs what
- Upgrading an installation
- Rules for code that ships
- After the deploy
One command
php bin/php/console exp:velocity deploy --dry-run --allow-root-user # what it would do, and nothing else
php bin/php/console exp:velocity deploy --allow-root-user # the usual case
php bin/php/console exp:velocity deploy --kernel --allow-root-user # a kernel class was added or renamedIt prints PASS, FAIL or SKIP with the time of each step, stops at the first failure and exits with status 1, listing
the steps not run. --packer also clears the packed scripts and styles.
The steps and their order
| # | Step | Why here |
|---|---|---|
| 1 | Extension class maps (ezpgenerateautoloads.php -e) | new classes must be findable |
| 2 | Kernel class maps, only with --kernel | the same for the kernel |
| 3 | INI caches (--clear-tag=ini) | settings are read again |
| 4 | Template, template-override, translation and design_base caches | new templates and design directories are found |
| 5 | The engine archive, when Velocity runs from one | rebuilt only when kernel/, lib/ or autoload/ changed, every file parsed first |
| 6 | PHP-FPM: wait for OPcache to revalidate, or reload it | the new code runs under FPM |
| 7 | Restart Velocity, when it is running | workers inherit the classes of the warm-up |
| 8 | Content, HTTP cache and template-block caches | rendered output is cleared only now |
| 9 | Velocity's response cache | the same, in the server |
| 10 | Warm-up URLs ([DeploySettings] WarmUpURL[]) | the first visitor does not rebuild every cache |
The order is the point. Cleared before step 6 and 7, every page requested in between is rendered by the old code and cached again. A file that does not parse fails step 5, before PHP-FPM or Velocity is touched.
PHP-FPM is reloaded only when it has to be ([DeploySettings] PhpFpmReload=auto): a reload makes every pool of
that PHP version wait for its longest running request. When OPcache revalidates files, the deploy waits
revalidate_freq plus one second instead. On a server with several PHP versions, name the service that really serves
the site in [DeploySettings] PhpFpmService.
Which change needs what
| Change | Needs |
|---|---|
| A PHP class, operator or INI file | the whole deploy |
| A new or renamed kernel class | the deploy with --kernel |
| An existing template | the template caches and Velocity's response cache; no restart |
| A stylesheet or script of a design | the deploy with --packer, or the packer and template-block caches |
| Content | nothing; the kernel invalidates |
| A newly activated extension | the deploy: its classes, settings and design directories (design_base) |
Upgrading an installation
- Back up files and database.
- Put the new code in place, regenerate the class maps, clear all caches, reload PHP-FPM, restart Velocity.
- Apply the database update once, whole, in order (
update/database/<driver>/6.0/), then the scripts the guide names. - Read the upgrade notes of every period passed in
doc/eng-us/bc/6.0/and the changelogs. - Check extensions:
./console exp:checkclassesreports classes PHP refuses to load. - Run the upgrade check: Setup > System upgrade, or
php bin/php/checkmanifest.php --all --extensions.
Guides: Upgrading, Update with Git.
Rules for code that ships
- A new class referenced from a shipped INI file should be guarded with
class_exists()in the kernel: a Velocity worker started before the deploy does not know it. - Templates that use a new class or operator must not reach the servers before the class does; deploy the kernel side first.
- A deployment must reach every PHP runtime that serves the site; clearing caches alone leaves PHP-FPM and Velocity on the old classes.
- With several web nodes, deploy each node;
exp:velocity deploycovers one machine. - In production, consider
ManagedByDeployment=enabled, so that the administration cannot write settings or templates that the next deploy would drop (Configuration managed by the deployment).
After the deploy
- Request the front page and the administration login; check a page whose content you know.
- Watch
error.login the log viewer for a few minutes. - After a Velocity restart, check that a new parent process runs and the port answers (Velocity persistent workers).
Related pages
- Deploying
- Deployment pipeline
- Deploying changes, for hosts
- Free documentation: this page is free to copy, translate and improve under the GNU FDL 1.3.
Become an Exponential Partner
Partners share their information, provide funding, contribute back and develop the products with us, and that is how Exponential grows. A partner website and dashboard are planned for mid-2027: please become a partner today to speed up our growth rate and land new features faster.