Velocity for hosts #

This page is for system administrators and support staff at hosting companies who run Exponential Velocity for customer sites. It answers: what Velocity needs from a server, how to install and configure it, how to keep it running across reboots and crashes, how a change reaches it, where it logs, how to watch it, and how to give each customer their own instance. The sources are Chapter 8 and Velocity engines; every command below is run from the installation root.

Contents #

1. What Velocity is, for a host
2. Requirements
3. Install and first start
4. Settings and how to change them
5. Ports, address and the worker user
6. Keeping it running: boot service and watchdog
7. Deploying a change
8. Logs, status and monitoring
9. The dashboard and the control panel
10. One Velocity per customer
11. Checklist

What Velocity is, for a host #

Velocity is an application server written for Exponential. A parent process loads the application once and forks workers that answer one request after another; between requests each worker is reset to the state it had when it was forked. The parent accepts every connection, answers static files, response-cache hits and its own pages without a worker, and terminates TLS, so a Velocity site needs no Apache, nginx, PHP-FPM or separate TLS terminator (Chapter 8, section 8.3).

What that means for your operations:

The command is exp:velocity (also exp:vc, or php bin/php/velocity.php). It drives three engines with the same verbs: qbix (Velocity's own server, the subject of this page), frankenphp (FrankenPHP) and php (PHP's built-in development server).

Requirements #

At start-up the engine refuses to run without process isolation (pcntl, or a php-cgi binary) and without openssl when HTTPS is configured; for the rest it warns once. Ask the machine what it lacks:

php bin/php/console exp:velocity ext check
php bin/php/console exp:velocity ext install-hint <extension>    # the install command for this operating system

On Red Hat Enterprise Linux 9 and its rebuilds the stock PHP is 8.0: enable a newer module stream first (Chapter 2, section 2.9).

Install and first start #

composer require se7enxweb/exponential-velocity:~0.0.4.44
php bin/php/console exp:velocity config set --apply ServerSettings Engine qbix
php bin/php/console exp:velocity start
php bin/php/console exp:velocity status
curl -sI http://127.0.0.1:8088/ | head -1

• The package lands in vendor/se7enxweb/exponential-velocity. The tilde constraint accepts later 0.0.4.x releases; 0.0.4.44 is the version Exponential's composer.json suggests and the first that reads forwarded protocol headers only from trusted proxies (Chapter 8, section 8.8).
• settings/velocity.ini ships Engine=php because PHP's built-in server always works; every real site sets qbix.
• start writes the configuration, starts the server detached, waits until the port answers and prints the status.
• The engine also exists as deb and rpm packages and Docker images (Velocity packages and binaries), but for an Exponential installation the Composer package is what exp:velocity drives.

What can go wrong on a first start (chapter 8): no server script (package not installed), the port already in use (exp:velocity status --all), no answer from another machine (Host is still 127.0.0.1), a warning that workers run as root (no worker user and a root-owned document root), or a maintenance page left on by an installation run (php bin/php/maintenance.php status, then off).

Settings and how to change them #

php bin/php/console exp:velocity config list                    # every setting; * marks the ones you set
php bin/php/console exp:velocity config get ServerSettings Workers
php bin/php/console exp:velocity config set --apply ServerSettings Workers 16
php bin/php/console exp:velocity config unset --apply ServerSettings Workers
php bin/php/console exp:velocity config paths

A changed setting reaches the server at the next restart or graceful. The /etc/vc tree is laid out like Debian's /etc/apache2 (vc.conf, ports.conf, envvars, conf-, mods- and sites-available with -enabled symlinks), with exp:velocity site|conf|mod enable|disable <name> as the a2ensite family (Velocity on-disk layout). Generated files carry "_generated": "exp:velocity"; remove that marker from a file and it is never overwritten again.

Ports, address and the worker user #

To face visitors directly on the standard ports:

php bin/php/console exp:velocity config set --apply ServerSettings Host 0.0.0.0 --allow-root-user
php bin/php/console exp:velocity config set --apply ServerSettings Port 80 --allow-root-user
php bin/php/console exp:velocity config set --apply ServerSettings HTTPSPort 443 --allow-root-user
php bin/php/console exp:velocity config set --apply ServerSettings User <customer> --allow-root-user
php bin/php/console exp:velocity config set --apply ServerSettings Group <customer> --allow-root-user
php bin/php/console exp:velocity restart --allow-root-user

Started as root, the parent keeps root (ports, certificate, reloads) and every worker gives it up right after the fork, before any application code runs. The worker user is decided in this order: [ServerSettings] User and Group; then VC_RUN_USER and VC_RUN_GROUP from the environment or /etc/vc/envvars; then the owner of the document root. A user that does not exist stops the start. Check the start-up line Workers as: ... in var/vc/qbix/run/console.log. HTTPS is on Velocity HTTPS certificates; pool size on Velocity workers and pools.

Keeping it running: boot service and watchdog #

exp:velocity has no command that installs a boot service. Two routes (Chapter 8, section 8.3.11):

• the engine's own units (vendor/se7enxweb/exponential-velocity/service/qbixserver.service and the operating-system package's exponential-velocity.service), which start the engine directly and therefore bypass what exp:velocity adds (the generated site file, KeepGlobals, [PHPSettings] IniOptions[], the worker user, instances);
• a unit of your own that runs exp:velocity start, stop and graceful (Type=forking, PIDFile= the installation's var/vc/qbix/run/server.pid). Chapter 8 gives a derived example; it is not shipped.

The watchdog is a second safety net for a crash, an out-of-memory kill or a stop by another tool. It is off until installed (root, systemd), and it starts the engine only when no process of it runs, nobody stopped it on purpose, no restart is in progress and it is not backing off. It never stops or restarts a running server (Velocity engines, The watchdog):

php bin/php/console exp:velocity watchdog install --apply --allow-root-user   # vc-watchdog.service + .timer
php bin/php/console exp:velocity watchdog status --allow-root-user
php bin/php/console exp:velocity watchdog remove --apply --allow-root-user

Every check that does more than find the server running writes a line to var/log/velocity-watchdog.log, and a start or back-off is recorded in the audit trail as system.velocity.watchdog.*.

Deploying a change #

Workers keep classes, INI values and compiled templates in memory. One command brings a site up to date in the order that works (Chapter 8, section 8.3.14):

php bin/php/console exp:velocity deploy --dry-run --allow-root-user   # what it would do
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 renamed

It regenerates autoloads, clears the INI and template caches, rebuilds the engine archive when one is used, reloads PHP-FPM when needed, restarts Velocity, clears the rendered-output caches and the response cache, and requests the [DeploySettings] WarmUpURL[] pages. Each step prints PASS, FAIL or SKIP; the first failure stops the run. Set [DeploySettings] PhpFpmService=disabled when Velocity serves the site alone. For a template or stylesheet change no restart is needed: clear the template caches and run exp:velocity cache clear. exp:velocity graceful re-executes the server while keeping the listening socket, so it drops no request.

Logs, status and monitoring #

[LogSettings] FileMode and DirMode ship as 0640 and 0750: an access log names visitors. exp:velocity status says running only for a server that answers an HTTP request, and exits non-zero otherwise; status --json is meant for monitoring. /Q/health answers "ok" to everyone; full figures, /Q/stats and Prometheus /Q/metrics need this machine, the dashboard token or a panel session. See Monitoring overview.

The dashboard and the control panel #

The first visit of /Q/panel sets its password (at least 16 characters). On a machine reachable from the internet set it at once, and reach a remote panel through an SSH tunnel to the server's own port. A token is any long random string, for example from openssl rand -hex 24. Leave [DashboardSettings] Remote at disabled unless a firewall already restricts the port (Velocity control panel).

The panel's Domains tab can set a domain to suspended (answers 503 with Retry-After) or disabled (answers 404); the server's own /Q/ and /.well-known/ paths keep working, so certificate renewals continue.

One Velocity per customer #

A single server serving several sites "is a routing convenience, not a security boundary" (README.md). For several customers on one machine, run one installation and one Velocity per customer:

• each as the customer's own user ([ServerSettings] User and Group), never as another customer's;
• each on its own ports (Port, HTTPSPort), with Host=127.0.0.1 behind a proxy, or on its own address;
• each with its own boot unit and its own watchdog UnitName;
• the proxy trusted by Velocity (Velocity beside Apache or nginx).

See Multi-tenant isolation.

Checklist #

From Chapter 8, Checklist, for each customer site:

• To do: Engine=qbix set, exp:velocity status shows the server running, the site answers.
• To do: Host, Port, HTTPSPort as intended; firewall open where Velocity faces visitors.
• To do: Workers run as the site's user (Workers as: ... in console.log), never root.
• To do: HTTPS: a CA certificate is served, not the self-signed stand-in; renewal planned.
• To do: A boot service starts Velocity after a reboot; the watchdog installed if you want it.
• To do: [DeploySettings] PhpFpmService=disabled when Velocity serves the site alone; deploy --dry-run shows the expected steps.
• To do: The panel password set, Remote left disabled, a dashboard token stored in your secrets store.
• To do: var/ and settings/ writable by the one user that runs PHP; no root-owned files in var/.

Demo mode under Velocity. Workers inherit the server's environment. /etc/vc/envvars is shared by the server of every installation on the host, so demo mode never goes there (the workers refuse it from that file and log demo/refused). Add export EXP_DEMO_MODE=1 to the demo's own site envvars, /etc/vc/sites-available/<site>.envvars: exp:velocity start passes it to that installation's server only, and exp:velocity restart or deploy from any shell keeps it. The demo's own unit environment (velocity-demo-mode.conf) works too. The file cannot set PATH, LD_*, PHPRC and the other loader and shell variables (on-disk layout). Demo mode for hosts.

Related pages #

• Velocity workers and pools
• Velocity HTTPS certificates
• Velocity response cache
• Velocity will not start
• Velocity: running Exponential in a persistent-worker web server
• Free documentation: this page is free to copy, translate and improve under the GNU FDL 1.3.