Concepts
Domains, services and hosts; the WOR_HOME layout; the rules every command follows.
The model: domain, service, host
Three words carry most of wor. Getting them straight makes every command predictable.
| Term | What it is | What it is not |
|---|---|---|
| Domain (domain id) | A folder under $WOR_HOME/domains/<domain>/ that groups related services, with its own JSON config files. Slug: lowercase a-z, 0-9 and - only. | Not a DNS name. It does not include the services' processes or vhosts; those belong to the services and are removed by service remove. |
| Service | One deployable unit under a domain, of exactly one runtime kind (static, node, go, python or php). Lives in domains/<domain>/<service>/, which is also the deploy root. Same slug rule. | Not a mix. The mixed templates from v1 (static-node, node-php...) were removed; use two services instead. |
| Host | A fully-qualified hostname bound to a service through a generated nginx or Apache vhost, e.g. api.example.com. One service can have several. | Not an IP address and not localhost. Names need at least one dot (use app.test for local work). |
Targets
Commands name what they act on in one of two forms:
<domain>/<service>, e.g.com-example/api. Some commands accept a bare<domain>too (source clone,source pull,source backup,path);rollbacknever does.<host>, e.g.api.example.com, resolved through the registry.deploy,infoanddiagnosetake either form.
How a hostname becomes a domain and a service
When you give a host to wor create or wor host add, wor derives the names using the embedded Public Suffix List, so .co.th and .co.uk behave correctly:
| Host | Service | Domain id |
|---|---|---|
api.example.com | api (the subdomain label) | com-example (labels of the registrable domain, reversed and joined with -) |
example.com | www (no subdomain) | com-example |
shop.example.co.th | shop | th-co-example |
wor create lets you override the derived domain id. An apex host also gets its www. alias. A host ending in .test, .localhost or .local is suggested as a local domain type, anything else public.
The $WOR_HOME layout
Everything wor owns lives under one root. Default /opt/wor on a Linux production host, ~/wor otherwise. wor treats exactly these directories as its own and will not re-chown anything else it finds in WOR_HOME (a CI upload area, for example).
$WOR_HOME/
.wor.lock advisory lock held by every writing command
domains/
<domain>/
services.config.json the services of this domain
databases.config.json registered database profiles
backup.config.json source/database backup behaviour
wor.config.json generated PM2 ecosystem file
<service>/ the deploy root (git checkout lives here)
public/ document root for static and php
.wor/ this service's own wor config (never served)
nginx/*.conf apache/*.conf web server snippets
php.ini php-fpm.ini PHP settings (php services with a pool)
*.example regenerated reference files, do not edit
configs/
host.env per-machine settings (paths, operator account...)
database/<profile>.env one file per database connection profile
backups/
<domain>/source/ zip archives from `wor source backup`
<domain>/database/<profile>/<yyyymmdd>/ gzip dumps
logs/<domain>/
ssl/
hosts/<host>/ ssl.json, sync.json, fullchain.pem, privkey.pem
acme/.well-known/acme-challenge/ certbot webroot, served by every vhost
tmp/ scripts/ bin/
Outside WOR_HOME, wor writes only what the web server and process managers require: vhost files, php-fpm pool files, systemd units and /etc/hosts entries.
Names that must not change
These conventions come from v1 and other tools depend on them. Treat them as a public interface.
| Thing | Name |
|---|---|
| PM2 process | wor_<domain>_<service> |
| systemd unit (Linux go/python) | wor_<domain>_<service>.service |
| Vhost file | wor__<host>.conf (two underscores) |
| Default vhost | 000_wor_default.conf |
| Per-domain config | services.config.json, databases.config.json, backup.config.json |
| Generated PM2 file | wor.config.json |
| Template variables | {{VAR}} substitution, unchanged from v1 |
The prefixes are also how wor reset and wor clean know what is theirs: wor_* processes and units, wor__*.conf vhosts. They never touch anything that does not match.
Process providers
A service's template decides what supervises it.
| Template | Linux | macOS | Entry point |
|---|---|---|---|
| static | none: the web server serves public/ | - | |
| node | PM2 (every OS) | app.js | |
| go | systemd | PM2 | app (built binary) |
| python | systemd | PM2 | app.py |
| php | PHP-FPM. wor manages the per-service pool files, never the php-fpm master itself | public/index.php | |
PM2 and systemd feel the same from the CLI: same naming, same start, stop, restart, status and logs commands. A template cannot be changed after the service is created.
Rules every command follows
Three gates before dispatch
wor applies these before any command runs.
| Gate | Effect | Exempt |
|---|---|---|
No sudo wor | Refuses when running as root and SUDO_USER is set. A real root login is fine. | wor ssl sync only, because certbot runs the renewal hook as root. |
| Workspace initialised | Stops with "run wor setup first" if WOR_HOME was never fully created. | version, help, setup, doctor, shell-init, upgrade |
| Workspace lock | Takes $WOR_HOME/.wor.lock for the whole command, non-blocking. A second writer fails with "another wor command is running". | version, help, path, shell-init, upgrade, diagnose, health, service logs, host logs, ssl renew |
The lock exemptions each have a reason. diagnose and health are read-only and must never wait during an incident. logs can follow indefinitely. path and shell-init run on every cd and every new terminal. ssl renew writes nothing itself and would deadlock against its own certbot hook if it held the lock. ssl sync --skip-if-busy exits quietly when it cannot get the lock, for the same reason.
Privilege elevation
- wor tries the operation unprivileged first and adds
sudoonly on failure. Homebrew directories on macOS never reach the prompt. - The first time a process needs
sudoit asks[Y/n]once; never up front, never again in the same command. Declining makes every later privileged step fail immediately. - The operator account owns everything under
WOR_HOME. No root-owned files appear there; that is whysudo woris refused. --non-interactiveturns every question into an error and runssudo -n. See running wor from a program.
Questions never answer themselves
If stdin ends before an answer arrives, the command stops with ERROR: no answer to "<question>" (stdin closed) -- cancelled. and exit code 1. An empty answer taken from a closed pipe used to accept every [Y/n], including the last question of wor domain remove that deletes files. Pressing Enter in a terminal still takes the default, and piped answers (printf 'y\n' | wor ...) still work until they run out.
How state is stored
- JSON, not JS.
services.config.jsonand friends use plain JSON; no Node.js is needed to manage configuration, not even for a static-only host. Old v1*.config.jsfiles must be converted by hand (stripmodule.exports =and the trailing;); there is no automatic migration. - Atomic writes. Config files are replaced atomically, so read-only commands (
health,diagnose) never see a half-written file. - Store decisions, derive facts. A choice the operator made (HTTP to HTTPS redirect, which PHP version a pool uses) is stored and never recomputed. A fact about the machine (who owns
WOR_HOME) is read at the moment of use and never stored. - Persist last. A command stopped at a question has not yet recorded the change it asked about, so aborting is always safe.
Flags
A single shared parser reads only --name and --name=value. A space-separated value (--port 3000) is not understood, short flags such as -y are not accepted, and the parser does not reject flags it does not know. --non-interactive and --json are recognised everywhere by Run itself (and --json then only on the four commands that support it).
Read-only listings use colour on a terminal and plain [ok], [fail], [on], [off], [ssl] tags otherwise. NO_COLOR turns colour off. No colour library is used.