create-wordjs 2.9.0 → 2.11.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 vX.Y.Z`) 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). |
@@ -78,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 vX.Y.Z --yes                  # a given release
+npx create-wordjs@latest upgrade /srv/wordjs --zip ./wordjs-vX.Y.Z.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)
 
@@ -148,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).
@@ -169,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-vX.Y.Z.zip` — add
+  `--sha256 <hex>` with the value from `wordjs-vX.Y.Z.zip.sha256` to have it verified.
 - **Existing directories**: the target directory must not exist (or must be empty) — the tool
   refuses to overwrite anything.
 
@@ -193,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

@@ -64,7 +64,7 @@ Options:
   --zip <path-or-url>   Use a local release ZIP (or a direct https:// ZIP URL) instead of asking GitHub.
   --sha256 <hex>        Require the ZIP to have this SHA-256 (pin a checksum for --zip; also checked
                         on top of the release's own .sha256 asset).
-  --version <tag>       Install/upgrade to a specific release tag (e.g. v2.1.0) instead of the latest.
+  --version <tag>       Install/upgrade to a specific release tag (e.g. vX.Y.Z) instead of the latest.
   --http                Serve plain HTTP instead of self-signed HTTPS (sets WORDJS_HTTP=1). (create)
   --no-start            Scaffold + install dependencies only; don't start the server.
   --yes, -y             Skip the confirmation prompt (required when upgrading non-interactively).
@@ -95,7 +95,7 @@ Options:
 
 Examples:
   npx create-wordjs@latest my-site
-  npx create-wordjs@latest my-site --version v2.1.0
+  npx create-wordjs@latest my-site --version vX.Y.Z
   npx create-wordjs@latest upgrade                     # from inside your site directory
   npx create-wordjs@latest upgrade ./my-site --yes
   npx create-wordjs@latest /srv/wordjs --systemd --port 443
@@ -148,7 +148,7 @@ function parseArgs(argv) {
             if (!hex) fail(`--sha256 must be a 64-character hex SHA-256, got "${v}".`);
             opts.sha256 = hex;
         }
-        else if (a === '--version') { opts.version = argv[++i] || fail('--version needs a value (a release tag, e.g. v2.1.0).'); }
+        else if (a === '--version') { opts.version = argv[++i] || fail('--version needs a value (a release tag, e.g. vX.Y.Z).'); }
         else if (a === '--http') opts.http = true;
         else if (a === '--no-start') opts.start = false;
         else if (a === '--yes' || a === '-y') opts.yes = true;

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "create-wordjs",
-    "version": "2.9.0",
+    "version": "2.11.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)",