WOR Hostdocumentation v1.0.5 Home Downloads

Install & first run

Platforms, installing on a server, the setup wizard, a quick start, configuration and environment variables.

Supported platforms

PlatformRoleWhat install.sh doesState
Debian 12+, Ubuntu 22.04 / 24.04 LTS and newer LTSProduction and developmentInstalls missing runtime packages with apt, then the binary.works
RHEL, Rocky, AlmaLinux 9+, CentOS Stream 9+Production and development (policy)Recognised, then stops: install_rhel() is a placeholder.not implemented
macOS (arm64, amd64)Development hostInstalls the binary only. A Mac is where you run the CLI, not a host wor deploys to, so there are no runtimes to install.works
Windows-Refuses and points at WSL2.removed

Install on a server

Release archives are published at https://wor.worapong.com/download. Each archive contains one binary per target plus install.sh, in a folder that is always named wor-host/.

One-liner

$ curl -fsSL https://wor.worapong.com/download/installer.sh | bash

Asks download/version.php which release is current, downloads that immutable archive, and hands over to the install.sh inside it (which uses sudo itself).

A specific version

$ curl -fsSL https://wor.worapong.com/download/installer.sh | bash -s -- <tag>

Replace <tag> with any tag listed on the download page, for example v1.0.2-b74. installer.sh --url <package-url> installs from an arbitrary archive (for developers testing a build).

Manual

$ curl -fsSL https://wor.worapong.com/download/releases/<tag>.tar.gz -o wor.tar.gz
$ tar -xzf wor.tar.gz            # or: unzip <tag>.zip
$ cd wor-host
$ sudo ./install.sh

.tar.gz and .zip hold identical files. A .sha256 checksum file is published beside them.

What install.sh does

  1. Detects the OS and CPU architecture itself. There is no flag for either: one archive ships every target, and a hand-picked mismatch only shows up later as Exec format error.
  2. On Linux, detects the distro family from ID and ID_LIKE in /etc/os-release.
  3. Looks for an existing wor installation (an older bash wor-cli, or /opt/wor) and offers to reset or remove it. Both need you to type a confirmation word.
  4. Debian family: reports which of these packages are already installed, then asks before installing only the missing ones. It never upgrades, downgrades or removes anything already present.
    git  golang-go  nodejs  python3  python3-pip  php-fpm  php-cli
    nginx | apache2        (per --host-provider)
    certbot + python3-certbot-nginx | -apache   (unless --skip-ssl)
    mariadb-server mariadb-client               (--with-mysql)
    postgresql postgresql-client                (--with-postgres)
    redis-server                                (--with-redis)
    Then installs PM2 with npm -g if npm exists and PM2 does not, and enables and starts the web server and php*-fpm units.
  5. Copies the matching bin/wor-<os>-<arch> to /usr/local/bin/wor (override with --install-dir).
  6. Offers to add eval "$(wor shell-init)" to the operator's ~/.bashrc or ~/.zshrc (chosen from their login shell), which enables wor goto.
OptionMeaning
--host-provider=nginx|apacheWeb server to install. Default nginx.
--with-mysql --with-postgres --with-redisAlso install that database server. Only needed if you use wor database against a local server.
--skip-sslDo not install certbot.
--install-dir=PATHWhere to place the binary. Default /usr/local/bin.
Unattended runsThe "install the missing packages?" question defaults to yes when there is no terminal, so curl | bash automation keeps installing them. The two destructive questions (reset or remove an old installation) only proceed if you type their confirmation word.

macOS

The same installer, binary only. --host-provider, --with-* and --skip-ssl do not apply. Install nginx or Apache, PHP, Node.js and the rest yourself with Homebrew; wor doctor tells you what is missing. The binary is unsigned and not notarized, so macOS may warn the first time you run it.

Build from source instead

$ go build -o wor ./cmd/wor

First run

As the non-root operator account, in this order:

$ wor version      # confirm the binary runs and what version it is
$ wor doctor       # read-only checklist of what is installed and what is missing
$ wor setup        # one-time wizard; safe to re-run

Do not run wor with sudo. wor refuses (sudo wor ... fails with an explanation) and asks for elevation itself, once, only for the operations that need it. A server whose only account is root is fine: the refusal triggers only when SUDO_USER is set.

Example outputs on this page come from real runs of wor on macOS. Machine-specific values (tool versions, disk sizes, dates, file names) have been replaced with typical ones and long paths shortened, so your numbers will differ. On Linux, paths and a few platform-specific checks differ.

wor version prints the version, the build, and the platform:

$ wor version
WOR Host
--------
Version  : 1.0.5
Release  : v1.0.5-bN
OS       : macOS
Build    : darwin/amd64
  ✓ Workspace initialized

A real wor setup run, with your answers after each prompt (an Enter on its own takes the bracketed default). On Linux a sixth question, the operator account, appears before the summary:

$ wor setup
WOR Setup Wizard
================

Select Environment (1=Production, 2=Development) [2]:
Select WOR_HOME (1=Default: ~/wor, 2=Custom) [1]:
Select Web Server Provider
1. nginx : nginx/1.24.0
2. apache : Apache/2.4.58 (Ubuntu)
3. skip
Choose [3]: 1
Default SSL Provider
1. self-signed : OpenSSL 3.0.13
2. letsencrypt : certbot 2.9.0
3. skip/none
Choose [1]:
PHP / PHP-FPM
php     : PHP 8.3.6 (cli) (NTS)
php-fpm : not installed
Enter PHP-FPM endpoint (unix:/path/to.sock or host:port), or leave blank to configure later []:

Setup Summary
=============
environment  : development
WOR_HOME     : ~/wor
host_provider: nginx
ssl_provider : self-signed
php_fpm      : not configured (PHP services will fail preflight)
config       : ~/.wor/config

Proceed with setup? [Y/n]:
[OK] Config written: ~/.wor/config
[OK] WOR_HOME ready: ~/wor
[OK] Default host configured

What wor setup asks

StepQuestionNotes
1Environment: 1 = production, 2 = developmentDefault is production on Linux, development on macOS. Currently also used to pick the default WOR_HOME.
2WOR_HOMEDefault /opt/wor (Linux production) or ~/wor (macOS, or development). Or a custom path.
3Web server providernginx or apache; detected binaries and versions are recorded.
4Default SSL providerletsencrypt, self-signed, custom or none.
5PHP and PHP-FPMDetects PHP; records the host-wide PHP_FPM_ENDPOINT used by legacy shared-pool services.
6The operator account (Linux only)The single unix user that owns everything wor creates. Recorded in host.env, not in your personal config, because it describes the machine. Empty is allowed: files then stay owned by whoever runs wor. On macOS everything runs as the login user.

It then prints a summary and asks to proceed. On confirmation it writes the config, creates the WOR_HOME tree, hands each directory to the operator (so a root-owned parent such as /opt does not leave root-owned directories behind), and checks the default vhost. Every run refreshes the default vhost 000_wor_default.conf if it points its document root somewhere other than the current workspace; other admin edits are preserved. It ends by offering to create your first website.

Quick start: your first site

After wor setup, four commands take a hostname to a deployed, HTTPS-secured, monitored service. The names below assume the host myapp.example.com, which wor turns into domain com-example and service myapp (see how a hostname becomes a domain).

$ wor create myapp.example.com                          # interactive wizard: type, domain, hosts entry
$ wor source clone com-example/myapp https://git.example.com/you/myapp.git
$ wor deploy myapp.example.com                          # pull, deps, build, restart, health check
$ wor ssl issue myapp.example.com --provider=letsencrypt
$ wor health                                            # is everything actually serving?

wor create is a wizard and has no fixed output. The other steps print:

Clone (it asks what to do with the service's .wor folder, because a fresh clone replaces the whole tree; pressing Enter keeps it):

$ wor source clone com-example/myapp <sandbox>/repo.git
[WARN] ==================== .wor ====================
[WARN] .wor exists in ~/wor/domains/com-example/myapp
[WARN] It holds this service's own wor configuration: web-server
[WARN] snippets (.wor/nginx, .wor/apache) and PHP settings
[WARN] (.wor/php.ini). A fresh clone replaces the whole tree, and
[WARN] the source backup honors .gitignore -- so if .wor is
[WARN] gitignored it is NOT in the backup zip and can be lost.
[WARN] The cloned repository does NOT contain a .wor.
[WARN] ==============================================
  1) keep   -- keep the current .wor; the repo's copy (if any) is saved as .wor.new
  2) delete -- use the repo's .wor only (or none); the current .wor is DISCARDED
Choose 1-2 [1=keep]: [OK] Cloned: com-example/myapp
[INFO] A fresh clone has no installed dependencies or build output (node_modules, go binary, ...).
Deploy com-example/myapp now (install deps + build + restart)? [y/N]: 
(no answer -- skipped)
[INFO] Skipped. Run `wor deploy com-example/myapp --no-pull --force` before starting the service.

Deploy:

$ wor deploy myapp.example.com
Already up to date.
[INFO] static service deployed. Reloading host provider.
[OK] Deploy completed: com-example/myapp

Secure:

$ wor ssl issue myapp.example.com --provider=self-signed --no-redirect
[OK] Self-signed SSL installed: myapp.example.com
[INFO] HTTP -> HTTPS redirect: off (change it with `wor ssl redirect myapp.example.com on|off`)

Monitor:

$ wor health
WOR Health (2 enabled services)
--------------------------------------------
Disk Usage  : 38.0G / 100.0G (38%)
--------------------------------------------

[ok] com-example/myapp
    Status : Online (served by web server)
    Runtime: static
    [ok] cert myapp.example.com: valid for 1000 more day(s)
    [ok] https://myapp.example.com -> 200

[warn] default/web
    Status : Online (served by web server)
    Runtime: static
    [i] no host registered -- HTTP not probed

--------------------------------------------
Healthy : 1
Warning : 1
Failed  : 0
  1. Create. Chooses the service type, scaffolds a starter tree, writes and validates the vhost.
  2. Clone. Replaces the starter tree with your repository, from any git server (hosted or self-hosted; see source clone for deploy keys and private CAs). An existing tree is backed up first, and wor asks what to do with its .env and .wor.
  3. Deploy. A fresh clone has no dependencies or build output, so this is what makes it runnable.
  4. Secure and monitor. ssl issue asks whether plain HTTP should redirect to HTTPS; pass --redirect or --no-redirect to answer without a prompt. wor health then proves the site answers.

Configuration and environment

Where settings come from

Two layers, plus defaults:

  1. ~/.wor/config, your personal file (path override: WOR_CONFIG_FILE).
  2. $WOR_HOME/configs/host.env, per-machine values: web server paths and commands, the php-fpm endpoint, the operator account.
  3. Platform defaults.

A process environment variable overrides the files for only a few settings: WOR_HOME, WOR_ENV, WOR_USER and WOR_CONFIG_FILE (plus WOR_NONINTERACTIVE, WOR_DOWNLOAD_BASE, NO_COLOR and TMPDIR, which are read directly). Everything else, including PHP_FPM_ENDPOINT and the NGINX_* and APACHE_* values, is read from the two files only; setting it in the environment has no effect.

One setting reverses the file order: the operator account reads host.env before ~/.wor/config, because two admins have two personal files and the value only means something if every admin agrees. WOR_USER still wins over both.

Both files are plain KEY=value lines. wor env prints the values in effect.

Variables

VariableMeaning
WOR_HOMERoot of everything wor owns. See layout.
WOR_ENVproduction or development. When unset it is currently inferred (a WOR_HOME under /opt, /srv or /var means production; otherwise Linux defaults to production, macOS to development).
WOR_USEROperator account override.
WOR_CONFIG_FILEPath of the personal config instead of ~/.wor/config.
WOR_NONINTERACTIVE1, true or yes: same as --non-interactive. See running wor from a program.
PHP_FPM_ENDPOINTThe shared host-wide php-fpm endpoint used by services created with --no-php-pool and by services that predate per-service pools. A host.env or config-file value; the process environment is not read for it.
NGINX_SITES_AVAILABLE, NGINX_SITES_ENABLED, NGINX_LOG_DIR, NGINX_TEST_COMMAND, NGINX_RELOAD_COMMAND, and the APACHE_* equivalentsOverride where vhosts and logs live and how the server is tested and reloaded. Set them in host.env; the process environment is not read for them.
NO_COLORDisable ANSI colour. Colour is also off automatically when output is not a terminal.
WOR_DOWNLOAD_BASEWhere wor upgrade asks for releases. Process environment only. Exists so the command can be pointed at a local php -S while working on the download site.
TMPDIRScratch directory (falls back to the OS temp dir).

Web server paths per platform

Platformnginx vhostsApache vhosts"Enabled"
Debian family/etc/nginx/sites-available/etc/apache2/sites-available (a2ensite)Symlink into sites-enabled
RHEL family (designed)would be /etc/nginx/conf.d/etc/httpd/conf.d (already the fallback)Same directory, no symlink
macOS Homebrew/opt/homebrew/etc/nginx/servers (or /usr/local/etc/... on Intel)/opt/homebrew/etc/httpd/serversSame directory: writing the file enables it

Override any of them in host.env.

Shell integration

A process cannot change its parent shell's directory, so wor goto is a shell function that wraps cd "$(command wor path ...)", the same approach as zoxide or nvm. Enable it with one line in your rc file (the installer offers to add it):

eval "$(wor shell-init)"
$ wor goto myapp/api       # cd into that service's folder
$ wor goto .               # WOR_HOME itself
$ wor goto ./logs          # any folder under WOR_HOME
$ wor goto                 # numbered picker

Upgrading

$ wor upgrade             # shows installed vs published, asks, installs
$ wor upgrade --yes       # no confirmation

It asks download/version.php, not a directory listing, so the archive it fetches is an immutable versioned URL. Installation is handed to the install.sh inside that archive; there is one install path, not two. Replacing the running binary is safe: install(1) unlinks the target before writing, so the running process continues from the old inode.

Moving to 1.0.2 needs no migration: a service with no settings files renders exactly the pool config it had before, so the upgrade does not rewrite or reload anything by itself. Existing vhosts are not regenerated either; they pick up newer templates the next time that host is written. One thing does not self-heal: macOS php-fpm pools created before 2026-07-05 still have old-style pool files and unix users, so remove and re-add those services (back up the source first).