Web server and engine choices for bundles
This page is for bundlers who decide what serves the site inside their bundle. It describes only what the project's
documentation and examples show; the examples are in doc/eng-us/examples/web-servers/.
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
- The rule every server follows
- The choices
- Velocity's engines
- Which one for which bundle
- Before you ship a server configuration
The rule every server follows
"Whatever serves it, the document root is the installation root (the directory with index.php) and the same
routing applies: a short list of asset paths is sent as files, three front controllers run, and every other request
is answered by index.php, which never hands out a file. That is what keeps settings/, var/, vendor/, kernel/,
composer.json and the SQLite database safe although they lie inside the document root"
(Web server examples).
The list is written once in .htaccess_root, and Velocity implements it rule for rule. A bundle that writes its own
web server configuration must implement the same list, in the same order; the examples do.
Only Apache (with AllowOverride All) and LiteSpeed Enterprise read .htaccess as it ships; for them a bundle copies
the template with php bin/php/console exp:setup:htaccess --apply (--static for .htaccess_root_static). OpenLiteSpeed
reads only its rewrite rules, with autoLoadHtaccess and after a restart; nginx, Caddy, FrankenPHP and IIS never read
it; Velocity has the rules built in
(Setting up .htaccess and config.php from the console).
The choices
| Server | Example to start from | How the example was checked |
|---|---|---|
| Velocity (recommended) | Velocity, velocity.ini.append.php.example, exponential-velocity.service | every setting exists in settings/velocity.ini; systemd-analyze verify |
Apache, .htaccess | Apache .htaccess | httpd -t and test requests |
| Apache, virtual host | Apache virtual host | httpd -t, HTTP and HTTPS test requests |
| nginx | nginx, nginx.conf | nginx -t, test requests |
| Caddy | Caddy, Caddyfile.example | frankenphp validate |
| FrankenPHP | FrankenPHP, frankenphp.Caddyfile.example | frankenphp validate |
| LiteSpeed, OpenLiteSpeed | LiteSpeed | rules tested in Apache's mod_rewrite, not on LiteSpeed |
| IIS | IIS, web.config | well-formed XML only, not run on IIS |
| PHP-FPM behind any of them | PHP-FPM pool | php-fpm -t |
Source: the table on Web server examples. Note the last two rows: a bundle on LiteSpeed or IIS must do its own testing.
Velocity's engines
settings/velocity.ini [ServerSettings] Engine chooses Velocity's default engine
(Velocity engines):
| Engine | Role | Notes |
|---|---|---|
qbix | recommended: every stage, development to production | persistent workers, response cache, TLS, HTTP/2 |
frankenphp | production-ready alternative | one downloaded binary, SHA-256 checked; PHP in classic mode; no response cache yet |
php | development (the shipped default) | PHP's built-in server; plain HTTP |
"The shipped default engine stays php"; "To use the server, set Engine=qbix". A bundle that serves with Velocity
sets the engine on purpose (Velocity in a bundle).
Which one for which bundle
| Bundle | Server |
|---|---|
| Container image | Velocity in the container's foreground loop (Container images), or your platform's PHP-FPM image behind a proxy |
| Server image | Velocity with a systemd unit, or Apache or nginx with PHP-FPM |
| Panel installer | whatever the panel runs (Apache or nginx with PHP-FPM, LiteSpeed); install the matching rules (Hosting panel installers) |
| Appliance | Velocity: one product from request to page, with its own TLS |
| Demo or classroom | Velocity, or php for a laptop |
The hosting section compares them in more depth: Choosing a web server.
Before you ship a server configuration
- To do: It routes exactly as
.htaccess_rootdoes; the test requests of the examples page (/.git/config,/.env, scripts below the root) return 404 in your bundle. For an Apache bundle,exp:setup:htaccessexits 0 (the.htaccessis a copy of the template). - To do: The document root is the installation root.
- To do: HTTPS is configured or clearly left to the recipient.
- To do: The PHP that serves the site has the extensions
exp:velocity ext checkasks for. - To do: Trusted proxy settings match the bundle's network (13.10).
Related pages
- Chapter 8: Serving the site
- Velocity in a bundle
- Velocity for hosts
- 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.