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.
| Template | Runtime | Process provider | Default entry | Starter files written |
|---|---|---|---|---|
static | none | none; the web server serves public/ | - | public/, .gitignore |
node | Node.js | PM2 on every OS | app.js | app.js, package.json, public/, .gitignore |
go | Go | systemd on Linux, PM2 on macOS | app (built binary) | main.go, go.mod, public/, .gitignore |
python | Python | systemd on Linux, PM2 on macOS | app.py | app.py, empty requirements.txt, public/, .gitignore |
php | PHP | PHP-FPM (pool files managed by wor) | public/index.php | public/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/.
- Runtime must be installed.
wor createandwor service addstop with a clear "runtime not found" error. There is no "set it up now?" prompt;wor doctoris the one place that reports what is missing and how to fix it. - go is built.
go buildruns when the service is created and on everywor deploythat pulled a new commit, unconditionally. - The two supervisors. PM2 for node everywhere. systemd for go and python on Linux (present on virtually every distro, simpler than a second PM2-based manager), falling back to PM2 on macOS, which has no systemd.
wor doctorreports which one is active. - php has no process wor starts. The php-fpm master is assumed to be a system service already. wor does manage one thing under it: the per-service pool
.conffiles. - Mixed templates are gone.
static-node,node-web,node-phpandphp-nodewere removed. A static service plus a process-backed service under one domain covers those cases better.
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.
| When | Result |
|---|---|
| Exactly one PHP-FPM version is detected | The new service gets a dedicated pool automatically. |
| Several versions detected | Pass --php-version=<version> to choose. |
--no-php-pool | Falls back to the host-wide PHP_FPM_ENDPOINT. |
| A php service that predates pools | Left 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>/fpm | versioned php@<version> formulas and the plain php formula (the current version, no version in its name; confirmed with <binary> -v, never guessed) |
| Isolation | Each 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. |
| Apply | systemctl reload phpX.Y-fpm | brew services restart [email protected] (the LaunchAgent wrapper has no reload) |
| RHEL family | not 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
- wor writes the pool file.
- It validates with
php-fpm -tbefore touching anything live. - Only if that passes does it reload php-fpm.
- 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
-tmust 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.
- nginx writes separate
:80and:443server blocks, matching Apache's two VirtualHosts. The HTTPS redirect lives insidelocation /, not at server level, because a server-levelreturnruns before nginx picks a location and would swallow the ACME challenge. - Every
:80block serves/.well-known/acme-challenge/from$WOR_HOME/ssl/acmeunconditionally, whether or not the host has a certificate yet, because a host with no certificate is exactly the host about to request one. - PHP and PATH_INFO. nginx matches
\.php(/|$), splits withfastcgi_split_path_info, passesPATH_INFO, and returns 404 unless the resolved script exists (so/uploads/evil.jpg/x.phpcannot reach PHP). Apache setsAcceptPathInfo On. Front-controller URLs such as/index.php/controller/actiontherefore work. This fixed an infinite redirect loop in framework routers. - Old vhosts do not self-heal. A vhost generated before a template change picks the change up the next time that host is written.
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
- nginx snippets are included inside the service's
server { }block, Apache snippets inside its<VirtualHost>, in both cases right after wor's own directives. - Which block depends on the HTTPS redirect. With the redirect off, both
:80and:443blocks serve and the snippets are in both. With it on, the:80block only answers ACME challenges and redirects, so snippets go in the:443block only; a snippet in a redirect-only block could never run. - The include is always present and uses a wildcard (
include/IncludeOptional), so an empty or missing directory is fine. Add a file any time and runwor host reload. There is no hidden "did you opt in at create time" state. - You may add directives and locations. On nginx you may not redefine a
locationwor already emits (location /,location ~ \.php): nginx rejects duplicates on reload. To change wor's core routing, edit nginx's main config. - wor writes a non-loaded reference file
default.conf.examplethere on each host write. It does not end in.conf, so it is never loaded. It shows wor's current default block and these rules. Copy it to a new*.conf; do not edit it in place. - Folder lives under
.wor/, not a bareconfig/, so it cannot collide with the many frameworks that ship aconfig/at the repository root. - Works for every service type. Commit
.worto the repository to version it with the code, orwor source clonewill ask what to do with it.
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
- wor reads them; PHP does not. A php-fpm pool cannot include a php.ini of its own. The only per-pool ini mechanism is the
php_value/php_admin_valuefamily in the pool's.conf, andenv[PHP_INI_SCAN_DIR]cannot substitute because the master parses php.ini once at startup and every worker is a fork of it. So wor parses the files and renders directives into the pool, andphp-fpm -tthen validates the result. - Two layers, two files.
memory_limitbecomesphp_value, which the application can stillini_set()past.pm.max_childrenis a pool directive, invisible to the application, governing the worker processes. One file would mean one line silently meaningphp_valueand the next a raw directive, decided by a lookup table the reader cannot see.
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.
| File | Accepted keys |
|---|---|
php.ini as php_value | memory_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.ini | pm 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.
| File | Key | Reason |
|---|---|---|
php.ini | error_log and other log paths | The php-fpm master opens them as root; a service-owned file could aim a privileged write anywhere. |
extension, zend_extension, sendmail_path | They name code to run. Install extensions through the system's PHP packages; configure mail on the host. | |
open_basedir, disable_functions | Host-level containment a service must not be able to widen or shorten. | |
upload_tmp_dir | Points 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.ini | user, group, listen, listen.owner|group|mode | The pool's identity. A service able to set them could run as another service's account or take over its socket. |
chroot, chdir | wor cannot reason about the filesystem the pool sees; it sets the working directory from the document root. | |
error_log, access.log, slowlog | The 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:
pm | Directives written |
|---|---|
dynamic | pm pm.max_children pm.start_servers pm.min_spare_servers pm.max_spare_servers |
static | pm pm.max_children |
ondemand | pm pm.max_children pm.process_idle_timeout |
Applying, and noticing drift
wor deployapplies both files, validating before the first side effect and re-rendering after the build. When the rendered pool equals what is on disk, it skips the write, the test and the reload.wor service reloadapplies them on their own, never skipping. Config only.- Drift is a whole-file comparison: wor compares the rendered pool with the file on disk, which also catches a pool edited by hand.
wor infolists what each file asks for and marksNOT APPLIED;wor diagnosewarns about drift and about a file that no longer parses;wor healthsweeps the fleet for it. All three are read-only and never elevate: a pool file they cannot read is reported as unchecked, never as drifted. - Scope. Only a php service with its own pool reads these files. For a service on the shared endpoint, or a node/go/python/static service that has a stray copy, deploy warns the files are applied to nothing and does not even parse them.
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.
| Key | Default | Meaning |
|---|---|---|
ready.check | yes | no turns the readiness gate off for this service. |
ready.timeout | 30 | Seconds to wait for the service to become ready, from 1 to 600. Raise it for an app that is slow to start. |
ready.path | unset | Also 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.status | 200-399 | Accepted status codes: one, a range, or a comma list such as 200,204,301-308. |
ready.stable | 3 | Seconds 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.timeout | 300 | Seconds a deploy hook may run before it is stopped, from 1 to 3600. |
pm2.instances | 1 | node only. Number of workers, 1 to 64, or max for one per CPU. More than 1 runs the service in PM2 cluster mode. |
pm2.reload | no | node 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-timeout | PM2's own | node 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. |
revert | yes | no 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
- One
key = valueper line.;and#start a comment. No[sections]. - A key that is not listed here is an error, not a skipped line, so a typo (
ready.timout) is reported instead of silently using the default. Adeployreads the file from the tree after the pull and stops, before anything is installed, built or restarted, if it is in that state (so the commit that fixes it can deploy);startandrestartwarn and use the defaults for that run. - wor writes
.wor/deploy.ini.exampleon every deploy, listing the accepted keys. It is never read as settings; do not edit it. wor infoshows the gate that applies to a service and which settings its file sets:
$ 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.
- Node services only. PM2's cluster mode runs a Node script. On a go, python, php or static service, any
pm2.*key is an error that stops the deploy after the pull, before anything is installed, built or restarted. - Switching mode costs one normal restart. PM2 cannot turn a running process from single-process to cluster mode, or change its number of workers, by reloading it. The first deploy after you add the setting, remove it, or change
pm2.instancesdeletes and starts the process, with the usual short outage, and says so. Deploys after that reload. - A reload applies your configuration. A plain
pm2 reloadkeeps the process's stored settings, so a changed environment variable or timeout would not take effect. wor runspm2 startOrReloadagainst the ecosystem file it just regenerated, which is just as gentle and does apply them. - Several workers are one service everywhere.
wor service statusshows2 workers (2 online),wor healthshows a Workers line (andworkersin the JSON),wor infoshows the mode, andwor diagnosereports the service as only as healthy as its worst worker and judges flapping by the worst single worker rather than by the sum of their restarts. - The readiness gate and the automatic revert work as before. The gate fails the deploy if any worker restarts after the reload; the revert puts the previous commit back and reloads again.
wor service restartstill runspm2 restart, which restarts all workers at once. Reload is for deploys.
[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.