Install & first run
Platforms, installing on a server, the setup wizard, a quick start, configuration and environment variables.
Supported platforms
| Platform | Role | What install.sh does | State |
|---|---|---|---|
| Debian 12+, Ubuntu 22.04 / 24.04 LTS and newer LTS | Production and development | Installs 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 host | Installs 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 |
- Deliberately unsupported on Linux: Fedora (release cadence), openSUSE and Arch (a third package manager and layout each), and Alpine or anything without systemd (wor's Linux process provider is systemd).
- macOS is a development host. Homebrew services are LaunchAgents: they start when you log in, so after a power cut nothing comes back until someone signs in. Serving production traffic from a Mac is outside the support promise.
- Windows:
v1.0.2-b74was the last build with a Windows binary and stays on the download page. A Windows source build fails with exactly one error,undefined: wor_does_not_build_for_windows__use_WSL2. Develop and run wor inside WSL2 (Debian or Ubuntu).
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
- 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. - On Linux, detects the distro family from
IDandID_LIKEin/etc/os-release. - 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. - 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.
Then installs PM2 withgit 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)npm -gif npm exists and PM2 does not, and enables and starts the web server andphp*-fpmunits. - Copies the matching
bin/wor-<os>-<arch>to/usr/local/bin/wor(override with--install-dir). - Offers to add
eval "$(wor shell-init)"to the operator's~/.bashrcor~/.zshrc(chosen from their login shell), which enableswor goto.
| Option | Meaning |
|---|---|
--host-provider=nginx|apache | Web server to install. Default nginx. |
--with-mysql --with-postgres --with-redis | Also install that database server. Only needed if you use wor database against a local server. |
--skip-ssl | Do not install certbot. |
--install-dir=PATH | Where to place the binary. Default /usr/local/bin. |
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
| Step | Question | Notes |
|---|---|---|
| 1 | Environment: 1 = production, 2 = development | Default is production on Linux, development on macOS. Currently also used to pick the default WOR_HOME. |
| 2 | WOR_HOME | Default /opt/wor (Linux production) or ~/wor (macOS, or development). Or a custom path. |
| 3 | Web server provider | nginx or apache; detected binaries and versions are recorded. |
| 4 | Default SSL provider | letsencrypt, self-signed, custom or none. |
| 5 | PHP and PHP-FPM | Detects PHP; records the host-wide PHP_FPM_ENDPOINT used by legacy shared-pool services. |
| 6 | The 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
- Create. Chooses the service type, scaffolds a starter tree, writes and validates the vhost.
- 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
.envand.wor. - Deploy. A fresh clone has no dependencies or build output, so this is what makes it runnable.
- Secure and monitor.
ssl issueasks whether plain HTTP should redirect to HTTPS; pass--redirector--no-redirectto answer without a prompt.wor healththen proves the site answers.
Configuration and environment
Where settings come from
Two layers, plus defaults:
~/.wor/config, your personal file (path override:WOR_CONFIG_FILE).$WOR_HOME/configs/host.env, per-machine values: web server paths and commands, the php-fpm endpoint, the operator account.- 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
| Variable | Meaning |
|---|---|
WOR_HOME | Root of everything wor owns. See layout. |
WOR_ENV | production 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_USER | Operator account override. |
WOR_CONFIG_FILE | Path of the personal config instead of ~/.wor/config. |
WOR_NONINTERACTIVE | 1, true or yes: same as --non-interactive. See running wor from a program. |
PHP_FPM_ENDPOINT | The 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_* equivalents | Override 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_COLOR | Disable ANSI colour. Colour is also off automatically when output is not a terminal. |
WOR_DOWNLOAD_BASE | Where 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. |
TMPDIR | Scratch directory (falls back to the OS temp dir). |
Web server paths per platform
| Platform | nginx vhosts | Apache 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/servers | Same 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).