WOR Hostdocumentation v1.0.5 Home Downloads

Services & templates

The five service templates, process providers, per-service PHP-FPM pools, and how to customise a service without losing the change.

The five templates

One service is one runtime kind. The template is chosen at creation (wor create or wor service add --service-type=) and cannot be changed afterwards. If you need two kinds, make two services under the same domain.

TemplateRuntimeProcess providerDefault entryStarter files written
staticnonenone; the web server serves public/-public/, .gitignore
nodeNode.jsPM2 on every OSapp.jsapp.js, package.json, public/, .gitignore
goGosystemd on Linux, PM2 on macOSapp (built binary)main.go, go.mod, public/, .gitignore
pythonPythonsystemd on Linux, PM2 on macOSapp.pyapp.py, empty requirements.txt, public/, .gitignore
phpPHPPHP-FPM (pool files managed by wor)public/index.phppublic/index.php, public/, .gitignore

Every template's public/ holds index.html, example.html, assets/css/app.css and assets/js/app.js. Scaffolds are written only where no file exists yet; a re-run never overwrites your code. node, go and python services listen on a port (auto-picked from 3000 upward unless you pass --port) and are reverse-proxied by the generated vhost. static and php are served from public/.

PHP-FPM: a pool per service

Each php service can have its own pool, its own socket, its own pm.* values and its own PHP-FPM version.

WhenResult
Exactly one PHP-FPM version is detectedThe new service gets a dedicated pool automatically.
Several versions detectedPass --php-version=<version> to choose.
--no-php-poolFalls back to the host-wide PHP_FPM_ENDPOINT.
A php service that predates poolsLeft alone. phpVersion is empty in its config, which means "use the shared endpoint". It is never migrated automatically.

A pool is named wor_<domain>_<service>, the same convention as PM2 and systemd, shortened with a hash if that would exceed 32 characters (long names otherwise silently break useradd). That name is the pool's [section], its unix user on Linux, its <pool>.conf in the version's pool directory and its <pool>.sock in the socket directory.

Platform differences

Linux (Debian family)macOS (Homebrew)
Layout detected/etc/php/<version>/fpmversioned php@<version> formulas and the plain php formula (the current version, no version in its name; confirmed with <binary> -v, never guessed)
IsolationEach pool runs as its own dedicated unix user, created with useradd --system --no-create-home and added to the document root's original owning group with chmod g+rX. The document root's owner is never changed.None. Every pool runs as the login user that runs the php-fpm master. A non-root master cannot chown a socket or switch workers to another user (failed to chown() the socket), so there is no privilege separation between services on macOS.
Applysystemctl reload phpX.Y-fpmbrew services restart [email protected] (the LaunchAgent wrapper has no reload)
RHEL familynot supported by auto-detect yet: the layout differs (/etc/php-fpm.d or Remi's /etc/opt/remi/phpXY/php-fpm.d). Designed, not built.

Lifecycle

  1. wor writes the pool file.
  2. It validates with php-fpm -t before touching anything live.
  3. Only if that passes does it reload php-fpm.
  4. If validation or the reload fails, the previous pool contents are restored byte for byte (or the file removed if there was none, because a config that fails -t must never be left behind to break the next reload of every pool under that master).

wor never starts, stops or restarts the php-fpm master on its own initiative (wor run starts a stopped one for you). It only adds and removes pool files, just as host reload only tells nginx to reload.

How a vhost is generated

Templates are built into the binary: one per service type per web server, filled in with the service's values. The generated file starts with a "Generated by WOR Host" banner and is fully regenerated on every write; never edit it. Customise through the service's own .wor folder instead.

Custom web-server config per service

Every generated vhost includes any *.conf you drop into the service's own folder:

$WOR_HOME/domains/<domain>/<service>/.wor/nginx/*.conf
$WOR_HOME/domains/<domain>/<service>/.wor/apache/*.conf

Custom PHP settings per service

A php service with its own pool configures itself through two optional files:

.wor/php.ini        PHP ini settings        -> php_value[...] / php_admin_value[...]
.wor/php-fpm.ini    pool tuning             -> pool directives, written as-is

Both are plain key = value lists. ; and # start a comment. [sections] are not supported: each file already applies to exactly one service. Both live above the document root, so the web server never serves them.

Example files (the keys are from the lists below; pm = ondemand suits a small machine, static a busy one):

# .wor/php.ini
memory_limit = 256M
upload_max_filesize = 64M
post_max_size = 64M
date.timezone = Asia/Bangkok

# .wor/php-fpm.ini
pm = dynamic
pm.max_children = 20
pm.start_servers = 4
pm.min_spare_servers = 2
pm.max_spare_servers = 6
pm.max_requests = 500

Apply them with wor deploy or, for a settings-only change, wor service reload <domain>/<service>. A rejected value does not reach the live pool: the previous configuration is restored and the command says what php-fpm objected to.

Why two files, and why wor reads them

What is accepted

Only an allowlist of keys. A key outside it is an error, not a skipped line: a setting that was asked for and silently not applied is the failure this feature exists to avoid. wor refuses the whole file and names the line.

FileAccepted keys
php.ini as php_valuememory_limit max_execution_time max_input_time max_input_vars upload_max_filesize post_max_size default_socket_timeout date.timezone error_reporting display_errors log_errors output_buffering zlib.output_compression session.gc_maxlifetime session.cookie_lifetime
php.ini as php_admin_value (PHP_INI_SYSTEM; php_value would be silently ignored)max_file_uploads expose_php
php-fpm.inipm pm.max_children pm.start_servers pm.min_spare_servers pm.max_spare_servers pm.max_requests pm.process_idle_timeout request_terminate_timeout rlimit_files

wor also writes php.ini.example and php-fpm.ini.example beside them, listing the keys it currently accepts, regenerated whenever the pool is rendered. The error messages list them too.

What is refused on purpose, and why

These files live in the service tree, which the deploy account writes, while the pool config they feed is written by root. Everything on the allowlist affects only the requesting service's own workers, which is the blast radius its code already has. Keys that reach beyond that stay out, and the error says why.

FileKeyReason
php.inierror_log and other log pathsThe php-fpm master opens them as root; a service-owned file could aim a privileged write anywhere.
extension, zend_extension, sendmail_pathThey name code to run. Install extensions through the system's PHP packages; configure mail on the host.
open_basedir, disable_functionsHost-level containment a service must not be able to widen or shorten.
upload_tmp_dirPoints uploads outside the service tree, which wor cannot reason about.
opcache.*Allocated once by the master, so a per-pool value would be ignored rather than applied. Change it in the version's own php.ini.
php-fpm.iniuser, group, listen, listen.owner|group|modeThe pool's identity. A service able to set them could run as another service's account or take over its socket.
chroot, chdirwor cannot reason about the filesystem the pool sees; it sets the working directory from the document root.
error_log, access.log, slowlogThe root master opens them.
php_value, php_admin_value, php_flag, php_admin_flag, env[...]PHP ini settings belong in php.ini, which picks the right directive; wor does not manage a pool's environment.

Parsing is strictly line, key and value, and every value is checked for control characters before the allowlist is even consulted: a value with a newline would otherwise end the php_value directive and let the rest of the line become a pool directive of the author's choosing. Verified against a real php-fpm, -t rejects min_spare > max_spare, max_children = 0, an unknown pm value and an unknown directive.

Pool tuning replaces defaults; it is not appended

Without a php-fpm.ini a pool gets pm = dynamic and pm.max_children = 5. php-fpm takes the last assignment of a directive, so appending would work, but would leave pm.max_children = 5 and = 40 four lines apart for the reader to untangle. wor merges by key and emits each directive once. Setting pm = static or pm = ondemand also changes which directives the block carries:

pmDirectives written
dynamicpm pm.max_children pm.start_servers pm.min_spare_servers pm.max_spare_servers
staticpm pm.max_children
ondemandpm pm.max_children pm.process_idle_timeout

Applying, and noticing drift

Upgrading from before this existedA pool for a service with no settings files renders identically under the new code, so an upgrade does not rewrite or reload anything. This was checked against a live pool on a production host (Debian 13, PHP 8.4): no drift after the upgrade.

Deploy settings: .wor/deploy.ini

An optional file in the service's own tree that tunes how wor deploy, wor service start and wor service restart decide that the service is really up. It sits beside php.ini and is versioned with your code. With no file, every default below applies.

KeyDefaultMeaning
ready.checkyesno turns the readiness gate off for this service.
ready.timeout30Seconds to wait for the service to become ready, from 1 to 600. Raise it for an app that is slow to start.
ready.pathunsetAlso require an HTTP GET of this path, on the service's own port, to answer with an accepted status. Unset: a TCP connection is enough. For a static or php service (which have no port) it is requested through the web server, and without it they are not checked at all.
ready.status200-399Accepted status codes: one, a range, or a comma list such as 200,204,301-308.
ready.stable3Seconds the process must stay up after it first answers, from 0 to 60; 0 turns it off. Catches an app that opens its port and then crashes.
hooks.timeout300Seconds a deploy hook may run before it is stopped, from 1 to 3600.
pm2.instances1node only. Number of workers, 1 to 64, or max for one per CPU. More than 1 runs the service in PM2 cluster mode.
pm2.reloadnonode only. yes: wor deploy uses pm2 reload instead of pm2 restart, so the workers are replaced one at a time. Implies cluster mode.
pm2.listen-timeout, pm2.kill-timeoutPM2's ownnode only. Milliseconds (100 to 600000), passed to PM2 as listen_timeout and kill_timeout: how long PM2 waits for a new worker to listen, and how long it gives an old one to exit.
revertyesno turns off the automatic revert: a deploy that fails its readiness check is then left in place instead of being rolled back.
# .wor/deploy.ini
ready.timeout = 90          ; a slow-starting app
ready.path    = /healthz    ; must answer 200-399 before the deploy counts
ready.stable  = 5
revert        = yes         ; roll back a deploy that fails the check (the default)
hooks.timeout = 120         ; a migration that takes a while
$ wor info api.example.com
...
Deploy:
  readiness: port 3000, up to 30s, GET /healthz must answer 200-399, then stay up 5s
  pm2      : cluster mode, 2 worker(s), deploys use pm2 reload
  hooks    : [pre-restart post-deploy]
  revert   : on (a deploy that fails readiness is rolled back when that is safe)
  settings : .wor/deploy.ini
             ready.path = /healthz
             ready.stable = 5

PM2 cluster mode and reload (node services)

A restart stops the process and starts it again, and requests that arrive in between are refused for as long as the application takes to start. With pm2.reload = yes a deploy instead replaces the workers one at a time while the others keep answering. That needs more than one process to hand over between, which is what PM2's cluster mode is: several workers of your script behind one port.

# .wor/deploy.ini
pm2.instances = 2
pm2.reload    = yes

In a test with a request every 30 milliseconds against an app that takes a second to start, a plain restart refused requests for about that second, and a reload with two workers refused none. A reload with a single worker in cluster mode also refused none, because PM2 starts the new worker and waits for it to listen before it stops the old one.

Your application has to tolerate several workerswor cannot detect any of this: state kept in the process's own memory that the other workers do not have (a session store, a cache you rely on being shared), a scheduled job inside the app that must run only once (it runs once per worker), and sticky websocket sessions. If your app does any of those, leave this off.
[INFO] Reloading wor_com-example_api one worker at a time, so the others keep answering...
[OK] Ready: com-example/api (3.9s)
[WARN] Restarting wor_com-example_api the normal way, once: pm2 cannot switch a running process from fork mode to cluster mode by reloading it.
[INFO] Later deploys will not need this.
$ wor service status
PM2 (node)
  [on]   com-example/api   :3000   2 workers (2 online)  4m   online

TLS certificate files

Whatever the provider, the vhost points at wor's own copy at $WOR_HOME/ssl/hosts/<host>/{fullchain,privkey}.pem, mode 0600, owned by whoever owns WOR_HOME. Why, and how renewal keeps it fresh, is on the SSL & certificates page.