Velocity in a bundle
This page is for bundlers who serve the bundled site with Exponential Velocity. "As of 6.0.15 the root composer.json
requires se7enxweb/exponential-velocity ~0.0.4.57 (through se7enxweb/exponential-php-floor, on PHP 8.0 and later)", so every installation built with Composer already has it
(Velocity engines).
Warning
.htaccess slows down every request. When .htaccess files are enabled (AllowOverride anything but None), let alone
used, Apache looks for them and reads and evaluates them on every request, in every directory of the path, and
page loading times go up drastically (measured). The only real fix is to switch the feature off for
the virtual host: AllowOverride None in the HTTPS virtual host, and the rules in the virtual host's own
configuration as mod_rewrite rules. That is far faster in production speed tests and well worth the time it takes
to optimize a production configuration. Switch over right away: copy the rules of the
example HTTPS virtual host into your virtual host (with the static cache, also
staticcache_offload.conf), set AllowOverride None, run apachectl configtest, reload Apache and
test the site. The same rules for other servers: nginx, LiteSpeed,
Caddy, IIS, Velocity (built in); where virtual host rules go in a control
panel: Plesk, cPanel, DirectAdmin, ISPConfig.
On LiteSpeed or OpenLiteSpeed, the server's own page cache can also answer anonymous visitors and crawlers without PHP: Page caching with LiteSpeed and OpenLiteSpeed.
Contents
Where Velocity comes from
| Form | For | Source |
|---|---|---|
Composer package se7enxweb/exponential-velocity | every Exponential installation | composer.json |
| deb and rpm packages | a system service on Debian 12 and 13, Ubuntu 22.04 and 24.04, Enterprise Linux 9 and 10 | Velocity packages |
Docker images on ghcr.io/se7enxweb/exponential-velocity | containers, amd64 and arm64 | Velocity packages |
| static binaries, the phar, a source kit | single machines, laptops, appliances, unusual platforms | Velocity packages |
"An Exponential installation already has the engine through Composer and needs none of this"; the other forms are
for Velocity outside an installation. "All files of a release carry checksums in SHA256SUMS."
Settings a bundle sets
Settings live in settings/velocity.ini; a bundle overrides them in settings/override/velocity.ini.append.php
(start from doc/eng-us/examples/web-servers/velocity.ini.append.php.example) or with
exp:velocity config set <Block> <Setting> <value>, which writes the same file
(Velocity example).
[ServerSettings]
Engine=qbix"Engine is the default engine ... It ships as php ... any site, from development to production, sets qbix."
The shipped port of qbix is 8088 on 127.0.0.1, "reachable only locally or through a reverse proxy"; a bundle
that answers on 80 and 443 changes the addresses as the example shows.
Users and root
[ServerSettings] UserandGroupname the user the workers run as; "Velocity started as root is fine: only its parent process stays root, and root workers are refused unlessAllowRootWorkers=enabled(shippeddisabled)" (Writable directories and permissions).exp:velocityitself refusesroot"unless--allow-root-useris given" (4.6).- When Velocity and Apache or nginx with PHP-FPM serve the same installation, "they share
var/, the caches and the sessions: give them the same user, or this group setup".
Starting it
- On a server: a systemd unit that runs
php bin/php/console exp:velocity start --allow-root-user. The exampledoc/eng-us/examples/web-servers/exponential-velocity.serviceis "Not shipped as a unit"; copy it, replace the paths and the database unit, and "Do not combine it with the unit of the operating-system package for the same ports". - In a container:
exp:velocity start"detaches the server and returns as soon as it answers", so the entry point loops onexp:velocity status(Container images).
Deploying a change
"A changed PHP class reaches Velocity's workers only after a restart; deploy does it in the right order":
php bin/php/console exp:velocity deploy --dry-run --allow-root-user
php bin/php/console exp:velocity deploy --allow-root-user
php bin/php/console exp:velocity deploy --kernel --allow-root-user # a kernel class was added or renamedSource: Velocity engines. In containers "the usual equivalent is a new image and a new container".
config.php is read once per worker as well. A bundle that sets a value with exp:config:set ... --apply restarts
Velocity afterwards (exp:velocity restart). Velocity does not read .htaccess; a bundle copies it
(exp:setup:htaccess --apply) only when Apache may serve the same tree
(Setting up .htaccess and config.php from the console).
Checks
php bin/php/console exp:velocity status
php bin/php/console exp:velocity ext checkstatus "reports the engine package and its version"; ext check lists the PHP extensions the installation wants and
what is missing. Velocity needs ext-sockets (pcntl and openssl recommended).
Related pages
- Web server and engine choices
- Velocity for hosts, Velocity will not start
- Velocity is part of Exponential 6.0.15
- Setting up .htaccess and config.php from the console
- 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.