create-wordjs 2.8.0 → 2.10.0

package/README.md

@@ -53,7 +53,7 @@ in CI — plus a pure-JS *SQLite (legacy / WASM)* fallback for hosts where the n
 | --- | --- |
 | `--zip <path-or-url>` | Use a local release ZIP (or a direct **`https://`** ZIP URL — plain `http://` is refused) instead of querying the GitHub API. Handy offline or when rate-limited. |
 | `--sha256 <hex>` | Refuse the ZIP unless its SHA-256 is exactly this (the value in the release's `.sha256` asset). Use it to pin a `--zip` file or URL; with a GitHub download it is checked on top of the release checksum. |
-| `--version <tag>` | Install a specific release (e.g. `--version v2.1.0`) instead of the latest. |
+| `--version <tag>` | Install a specific release (e.g. `--version v2.9.0`) instead of the latest. |
 | `--http` | Serve plain HTTP instead of self-signed HTTPS (sets `WORDJS_HTTP=1`). |
 | `--no-start` | Scaffold and install dependencies only — start the server yourself later. |
 | `--yes`, `-y` | Skip the confirmation prompt (required when `upgrade` runs non-interactively). |
@@ -62,6 +62,7 @@ in CI — plus a pure-JS *SQLite (legacy / WASM)* fallback for hosts where the n
 | `--systemd` | (create, `upgrade`; Linux) Also write a systemd unit, `wordjs.service`, to a private staging directory outside the site and print how to install it. The unit runs WordJS as a dedicated non-root account with **no Linux capabilities**. With create it implies `--no-start`. See [Run it as a service](#run-it-as-a-service-linux). |
 | `--port <n>` | (with `--systemd`) Public port written into the unit (`PORT=<n>`); default: the site's configured port, else `3000`. Below 1024 it also stages `60-wordjs-ports.conf`. |
 | `--service-user <name>` | (with `--systemd`) The account the service runs as (default `wordjs`; `root` is refused). |
+| `--mail` | (with `--systemd`) The site will receive mail (mail-server plugin, SMTP on 25): the drop-in also allows 25. Implied on `upgrade` when that plugin is installed. |
 | `-h`, `--help` | Show usage. |
 
 Separate-mode options:
@@ -77,15 +78,39 @@ Separate-mode options:
 
 ## Upgrade an existing site
 
+**From the admin panel first.** On a standard install (the monolith started by its service, with its
+own files — the `--systemd` layout) **Admin → Updates** lists the newer releases with their notes and
+installs one with your password and a two-factor code: it takes a backup, runs this same command with
+`--version <tag>`, restarts WordJS by itself and puts the previous version back if the new one fails to
+install or to start. In a container, a git checkout, split or separate mode, or when the code belongs
+to another account, the screen says so and gives you the command instead.
+
+**From the command line:**
+
 ```bash
 cd .. && npx create-wordjs@latest upgrade my-site      # or run it from inside: npx create-wordjs@latest upgrade .
 ```
 
 Downloads the newest release and replaces the app code while **preserving your data**: the database
-directory (`backend/data`), `backend/uploads/`, `wordjs-config.json`, `.env`, gateway secrets
-(`gateway/gateway-config.json`) and any user-installed plugins survive. It asks for confirmation
-before touching an existing install — on a non-interactive shell it refuses unless you pass `--yes`.
-Restart the server afterwards (schema migrations run automatically on the next start).
+directory (`backend/data`), `backend/uploads/`, `backend/backups/`, `wordjs-config.json`, `.env`,
+gateway secrets (`gateway/gateway-config.json`) and any user-installed plugins survive; the small config
+files are also copied to a `.upgrade-backup-<time>/` folder first. It asks for confirmation before
+touching an existing install — on a non-interactive shell it refuses unless you pass `--yes`. On a
+site that is already on the target version it does nothing unless you pass `--force`. Restart the
+server afterwards (`sudo systemctl restart wordjs` for a service); schema migrations run automatically
+on the next start.
+
+```bash
+npx create-wordjs@latest upgrade /srv/wordjs --yes                                   # unattended
+npx create-wordjs@latest upgrade /srv/wordjs --version v2.9.0 --yes                  # a given release
+npx create-wordjs@latest upgrade /srv/wordjs --zip ./wordjs-v2.9.0.zip --sha256 <hex> --yes --force   # offline, re-apply
+```
+
+`--zip` takes a release ZIP you downloaded (or an `https://` URL) instead of asking GitHub, and
+`--sha256` pins it to the value in `wordjs-<tag>.zip.sha256`. To go back, run `upgrade` with
+`--version <old-tag>` (add `--force` if the site already reports that version); your data stays
+intact. Run it as root (`sudo npx …`) when the site's files belong to the service account: the upgraded
+files are given back to the site's owner.
 
 ## Run it as a service (Linux)
 
@@ -108,7 +133,10 @@ boot must run as the service account so that account owns the database and certi
 
 **Ports below 1024 (80/443).** The unit never grants `CAP_NET_BIND_SERVICE`. For a port below 1024,
 `--systemd` also stages `60-wordjs-ports.conf`, a `sysctl.d` drop-in that sets
-`net.ipv4.ip_unprivileged_port_start` to that port. Read its trade-off before installing it: it lets
+`net.ipv4.ip_unprivileged_port_start` low enough for every port the site will bind: that port, `80` too
+for an HTTPS site (Let's Encrypt HTTP-01, turned on later in the admin panel) and `25` with `--mail`
+(incoming mail; implied on `upgrade` when the mail-server plugin is installed). Read its trade-off before
+installing it: it lets
 **every** unprivileged process on the host bind ports from that value up to 1023, not just WordJS. On a
 shared host, prefer a reverse proxy (nginx, Caddy) on 80/443 forwarding to WordJS on a high port.
 
@@ -144,8 +172,11 @@ npx create-wordjs@latest join frontend --gateway 10.0.0.1 --token <t> --ca-hash
 `--ca-hash` is required: `join` refuses to enroll without it, and there is no trust-on-first-use
 opt-out. Each `join` downloads the release, enrolls against the gateway (the token authorizes exactly one
 certificate signing; it is burned afterwards, and the ones `gateway` printed also expire after 120
-minutes — mint more on the gateway with `node scripts/cluster.js token <backend|frontend>`, which
-defaults to a 60-minute TTL and takes `--ttl <minutes>`), then starts the service, which registers
+minutes — once the first backend has joined, mint more from **Admin → Servers → Add a server**, which
+also prints the `node-join` command for the new machine
+([managing the cluster from the admin panel](https://github.com/jaimemartinez/wordjs/blob/main/documentation/separate-mode.md#managing-the-cluster-from-the-admin-panel));
+the second way is `node scripts/cluster.js token <backend|frontend>` on the gateway, which defaults to
+a 60-minute TTL and takes `--ttl <minutes>`), then starts the service, which registers
 with the gateway over mTLS. Browse `https://<gateway>:3000` when all three are up. `join` machines
 need `openssl` on the PATH. Full details, port matrix and the manual (source-checkout) procedure:
 [documentation/separate-mode.md](https://github.com/jaimemartinez/wordjs/blob/main/documentation/separate-mode.md).
@@ -165,8 +196,8 @@ need `openssl` on the PATH. Full details, port matrix and the manual (source-che
 - **GitHub rate limit / offline**: the release lookup uses the unauthenticated GitHub API. If it
   is rate-limited or you're offline, download `wordjs-v*.zip` from the
   [releases page](https://github.com/jaimemartinez/wordjs/releases) and run
-  `npx create-wordjs@latest my-site --zip ./wordjs-v2.1.0.zip` — add
-  `--sha256 <hex>` with the value from `wordjs-v2.1.0.zip.sha256` to have it verified.
+  `npx create-wordjs@latest my-site --zip ./wordjs-v2.9.0.zip` — add
+  `--sha256 <hex>` with the value from `wordjs-v2.9.0.zip.sha256` to have it verified.
 - **Existing directories**: the target directory must not exist (or must be empty) — the tool
   refuses to overwrite anything.
 
@@ -189,9 +220,9 @@ need `openssl` on the PATH. Full details, port matrix and the manual (source-che
 ## What gets created
 
 A ready-to-run WordJS bundle: backend (pre-compiled to `dist/`), frontend (pre-built `.next`),
-gateway, the bundled plugins and the four bundled themes (`circuito`, `default`, `gaceta`,
-`vergel`). Marketplace plugins are **not** in the bundle — they ship as separate release assets and
-are installed from the admin. Secrets (JWT, DB password, install token) are generated
+gateway and the four bundled themes (`circuito`, `default`, `gaceta`,
+`vergel`). No plugin ships in the bundle: plugins come from the marketplace (separate release assets),
+installed from **Admin → Plugins**. Secrets (JWT, DB password, install token) are generated
 locally during install — nothing sensitive ships in the bundle. See `INSTALL.md` inside the
 scaffolded directory for the manual steps and `documentation/deployment.md` for production
 deployment.

package/index.js

@@ -84,8 +84,13 @@ Options:
                         the first boot must run as that account.
   --port <n>            (with --systemd) Public port, written into the unit as PORT=<n> (default:
                         the site's configured port, else 3000). Below 1024 it also stages
-                        60-wordjs-ports.conf (net.ipv4.ip_unprivileged_port_start), never a capability.
+                        60-wordjs-ports.conf (net.ipv4.ip_unprivileged_port_start), never a capability,
+                        low enough for every port the site will bind: with HTTPS also 80 (Let's
+                        Encrypt HTTP-01 from Admin -> Security), with --mail also 25.
   --service-user <name> (with --systemd) The account the service runs as (default: wordjs). Not root.
+  --mail                (with --systemd) The site will receive mail (the mail-server plugin, SMTP on
+                        port 25): the drop-in then lowers the floor to 25. Implied on upgrade when the
+                        mail-server plugin is installed.
   -h, --help            Show this help.
 
 Examples:
@@ -126,7 +131,7 @@ function parseArgs(argv) {
     const opts = {
         mode: 'create', dir: null, zip: null, version: null, http: false, start: true, yes: false, force: false, install: true,
         role: null, gateway: null, token: null, caHash: null, advertise: null, enrollPort: null, host: null,
-        systemd: false, port: null, serviceUser: null,
+        systemd: false, port: null, serviceUser: null, mail: false,
         sha256: null,
     };
     // A leading subcommand selects the mode (default is the monolith create flow).
@@ -159,11 +164,12 @@ function parseArgs(argv) {
         else if (a === '--systemd') opts.systemd = true;
         else if (a === '--port') opts.port = argv[++i] || fail('--port needs a value (1-65535).');
         else if (a === '--service-user') opts.serviceUser = argv[++i] || fail('--service-user needs an account name.');
+        else if (a === '--mail') opts.mail = true;
         else if (a.startsWith('-')) fail(`Unknown option: ${a}`, 'Run with --help to see the available options.');
         else positionals.push(a);
     }
-    if ((opts.port !== null || opts.serviceUser !== null) && !opts.systemd) {
-        fail('--port and --service-user only apply together with --systemd.',
+    if ((opts.port !== null || opts.serviceUser !== null || opts.mail) && !opts.systemd) {
+        fail('--port, --service-user and --mail only apply together with --systemd.',
             'Without a unit, the port comes from the PORT environment variable or the site config (default 3000).');
     }
     if (opts.systemd) {
@@ -789,9 +795,10 @@ function underAny(p, roots) {
  * written into the file itself: whoever later finds it in /etc/sysctl.d/ should not have to guess why
  * it is there or what it costs.
  */
-function sysctlDropIn(start, { http = false } = {}) {
+function sysctlDropIn(start, { http = false, mail = false, ports = [] } = {}) {
     const lines = [
         `# WordJS: allow unprivileged processes to bind ports from ${start} up (written by create-wordjs --systemd).`,
+        ...ports.map((p) => `#   ${p.port}: ${p.why}`),
         '#',
         '# This is NOT a grant to WordJS alone. It lowers the privileged-port floor for EVERY unprivileged',
         `# process in this network namespace, so any local user or service may bind ports ${start}-1023 too, and`,
@@ -802,6 +809,9 @@ function sysctlDropIn(start, { http = false } = {}) {
     if (!http && start > 80) {
         lines.push(`# Let's Encrypt HTTP-01 (acme.http01Port: 80 in wordjs-config.json) needs this lowered to 80.`);
     }
+    if (!mail && start > 25) {
+        lines.push('# Receiving mail (the mail-server plugin, SMTP on port 25) needs this lowered to 25: re-run with --mail.');
+    }
     lines.push(
         '#',
         `# Install: sudo install -o root -g root -m 0644 ${SYSCTL_DROPIN_FILE} /etc/sysctl.d/ && sudo sysctl --system`,
@@ -821,8 +831,14 @@ function sysctlDropIn(start, { http = false } = {}) {
  *   configuredPort  the port the site's config already sets (gatewayPort), or null.
  *   acmeHttp01Port  acme.http01Port from the config, or null: monolith.js binds it beside an HTTPS
  *                   listener, so it counts toward the privileged-port floor.
+ *   mail            the site receives mail: the mail-server plugin listens for SMTP on 25.
+ *
+ * The floor goes as low as every port the site will bind, not only the ones configured today: the
+ * administrator turns on Let's Encrypt (HTTP-01 on 80) and installs the mail server from the panel,
+ * and neither may then need a file edited as root. An HTTPS site already on a port below 1024 counts
+ * 80 for that reason; a site on a high port gets no drop-in (it sits behind a proxy, or wants none).
  */
-function buildSystemdFiles({ installDir, nodePath, user = DEFAULT_SERVICE_USER, port = null, configuredPort = null, acmeHttp01Port = null, http = false }) {
+function buildSystemdFiles({ installDir, nodePath, user = DEFAULT_SERVICE_USER, port = null, configuredPort = null, acmeHttp01Port = null, http = false, mail = false }) {
     for (const [what, p] of [['site directory', installDir], ['node binary', nodePath]]) {
         if (!unitSafePath(p)) {
             const err = new Error(`The ${what} path "${p}" cannot go into a systemd unit as is: it must be absolute, without spaces, quotes, backslashes, "%" or "$".`);
@@ -836,10 +852,14 @@ function buildSystemdFiles({ installDir, nodePath, user = DEFAULT_SERVICE_USER,
     if (problem) { const err = new Error(problem.message); err.hint = problem.hint; throw err; }
 
     const publicPort = port || configuredPort || 3000;
-    const bound = [publicPort];
-    if (!http && acmeHttp01Port) bound.push(acmeHttp01Port);
-    const privileged = bound.filter((p) => p < PRIVILEGED_PORT_LIMIT);
-    const sysctlStart = privileged.length ? Math.min(...privileged) : null;
+    const bound = [{ port: publicPort, why: 'the site (its public port)' }];
+    if (!http && acmeHttp01Port) bound.push({ port: acmeHttp01Port, why: "Let's Encrypt HTTP-01 (acme.http01Port)" });
+    if (!http && publicPort < PRIVILEGED_PORT_LIMIT && !bound.some((b) => b.port === 80)) {
+        bound.push({ port: 80, why: "Let's Encrypt HTTP-01, when it is turned on in Admin -> Security" });
+    }
+    if (mail) bound.push({ port: 25, why: 'incoming mail (the mail-server plugin, SMTP)' });
+    const privileged = bound.filter((b) => b.port < PRIVILEGED_PORT_LIMIT).sort((a, b) => a.port - b.port);
+    const sysctlStart = privileged.length ? privileged[0].port : null;
 
     // Two hardening directives depend on WHERE things are, and each is dropped (with a warning) rather
     // than shipped in a shape that cannot start: ProtectHome= hides /home, /root and /run/user, which
@@ -915,7 +935,9 @@ function buildSystemdFiles({ installDir, nodePath, user = DEFAULT_SERVICE_USER,
 
     return {
         unit,
-        sysctl: sysctlStart ? { start: sysctlStart, content: sysctlDropIn(sysctlStart, { http }) } : null,
+        sysctl: sysctlStart
+            ? { start: sysctlStart, ports: privileged.map((b) => b.port), content: sysctlDropIn(sysctlStart, { http, mail, ports: privileged }) }
+            : null,
         publicPort,
         warnings,
     };
@@ -937,7 +959,7 @@ function systemdInstallSteps({ installDir, user = DEFAULT_SERVICE_USER, built, h
     // `install -o root -g root -m 0644` and not `cp`: root takes the staged file's CONTENT into a file it
     // creates itself, root-owned and not writable by anyone else, whatever the staged copy's mode was.
     if (built.sysctl) {
-        step(`Let it bind port ${built.publicPort} without a capability (read the trade-off in the file first):`,
+        step(`Let it bind ${built.sysctl.ports.length > 1 ? `ports ${built.sysctl.ports.join(', ')}` : `port ${built.sysctl.start}`} without a capability (read the trade-off in the file first):`,
             `sudo install -o root -g root -m 0644 ${staged(SYSCTL_DROPIN_FILE)} /etc/sysctl.d/${SYSCTL_DROPIN_FILE} && sudo sysctl --system`);
     } else if (upgrade) {
         // A site that moved to a high port (behind a proxy, say) no longer needs the floor lowered, and an
@@ -1046,12 +1068,14 @@ function emitSystemd(installDir, opts) {
         configuredPort: Number(appConfig.gatewayPort || gwConfig.gatewayPort) || null,
         acmeHttp01Port: Number(appConfig.acme && appConfig.acme.http01Port) || null,
         http: opts.http,
+        // An installed mail server (an upgrade) receives on 25 whether or not --mail was given.
+        mail: !!opts.mail || fs.existsSync(path.join(installDir, 'backend', 'plugins', 'mail-server')),
     });
     const stageDir = createSystemdStagingDir();
     const written = writeSystemdFiles(stageDir, built);
     console.log('');
     console.log(`   systemd unit staged: ${written.unitPath}`);
-    if (written.sysctlPath) console.log(`   sysctl drop-in for port ${built.publicPort}: ${written.sysctlPath}`);
+    if (written.sysctlPath) console.log(`   sysctl drop-in for ports from ${built.sysctl.start} up (${built.sysctl.ports.join(', ')}): ${written.sysctlPath}`);
     console.log('   (staged outside the site on purpose: the service account will own the site, and must not be able to edit what root installs)');
     for (const w of built.warnings) console.log(`   ⚠️  ${w}`);
     console.log('');

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "create-wordjs",
-    "version": "2.8.0",
+    "version": "2.10.0",
     "description": "Create a WordJS site with one command — the self-hosted CMS where third-party plugins run in an OS-isolated process with per-capability permission grants. SSR/SEO out of the box, SQLite by default, no PHP.",
     "license": "MIT",
     "author": "Jaime Martinez (https://github.com/jaimemartinez)",