WOR Hostdocumentation v1.0.5 Home Downloads

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.

TermWhat it isWhat 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.
ServiceOne 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.
HostA 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:

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:

HostServiceDomain id
api.example.comapi (the subdomain label)com-example (labels of the registrable domain, reversed and joined with -)
example.comwww (no subdomain)com-example
shop.example.co.thshopth-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.

ThingName
PM2 processwor_<domain>_<service>
systemd unit (Linux go/python)wor_<domain>_<service>.service
Vhost filewor__<host>.conf (two underscores)
Default vhost000_wor_default.conf
Per-domain configservices.config.json, databases.config.json, backup.config.json
Generated PM2 filewor.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.

TemplateLinuxmacOSEntry point
staticnone: the web server serves public/-
nodePM2 (every OS)app.js
gosystemdPM2app (built binary)
pythonsystemdPM2app.py
phpPHP-FPM. wor manages the per-service pool files, never the php-fpm master itselfpublic/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.

GateEffectExempt
No sudo worRefuses 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 initialisedStops with "run wor setup first" if WOR_HOME was never fully created.version, help, setup, doctor, shell-init, upgrade
Workspace lockTakes $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

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

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.