orionplace-react 0.2.1 → 0.3.0

package/README.md

@@ -9,6 +9,8 @@ setup CLI and the full storefront source, so every page and component in your
 project is yours to change.
 
 - **Setup CLI:** `init`, `set backend`, `add frontend`, `set mimic` and `update`.
+- **Server install:** `install` builds the storefront on your Linux server and
+  runs it as a system service behind nginx with HTTPS.
 - **API gateway:** the browser calls `/api/...` on your own domain; the server
   forwards it to your marketplace backend with cookies bound to the storefront.
 - **Typed store:** one Application Load request fills it before the first render.
@@ -19,8 +21,8 @@ project is yours to change.
 
 **Contents:** [Quick start](#quick-start-from-zero) ·
 [Existing project](#existing-nextjs-16-project) · [Components](#components) ·
-[Commands](#commands) · [Android app](#android-app) ·
-[Update](#update-an-existing-project)
+[Commands](#commands) · [Server install](#install-on-your-server) ·
+[Android app](#android-app) · [Update](#update-an-existing-project)
 
 Requires Node.js 20.9+ and a Node server deployment. Static export and edge-only
 hosting are not supported by this filesystem-based integration; only the Android
@@ -314,6 +316,7 @@ npx orionplace-react add frontend shop.example.com
 npx orionplace-react add frontend www.shop.example.com
 npx orionplace-react remove frontend www.shop.example.com
 npx orionplace-react set mimic shop.example.com
+sudo npx orionplace-react install
 npx orionplace-react help
 ```
 
@@ -330,8 +333,38 @@ npm run orionplace:update
 ```
 
 `npm set` belongs to npm's own configuration system; use the commands above.
-These commands configure local integration files. They do not provision a backend,
-change your account, create DNS records, configure TLS, or deploy a VPS.
+The setup commands configure local integration files. They do not provision a
+backend, change your account or create DNS records. `install` deploys the
+storefront on your server; see [Install on your server](#install-on-your-server).
+
+## Install on your server
+
+Prepare a Linux server once with the OrionMarketplace server script: it installs
+Node.js, nginx and certbot and adds the `orionplace` command
+([server guide](https://orionmarket.place/en/sandbox/install)).
+
+```bash
+curl -fsSLo orionplace.sh https://orionmarket.place/downloads/orionplace.sh
+sudo sh orionplace.sh setup
+```
+
+Then create the storefront in `/srv/orionplace` and install it:
+
+```bash
+cd /srv/orionplace
+sudo npx --yes orionplace-react init shop
+cd shop
+sudo npm install
+sudo npx orionplace-react install
+```
+
+`install` asks for your backend and storefront domain when they are missing,
+builds the project, runs it as the system service `orionplace-shop` on a free
+local port and connects each storefront domain with nginx and a Let's Encrypt
+certificate. Run it again after code or package updates; the service keeps its
+port. Options: `--name <service>`, `--port <port>`, `--user <user>`,
+`--no-domains`, `--yes`, `--dry-run`. Full guide:
+[Install a storefront](https://orionmarket.place/en/sandbox/install/storefront?framework=react).
 
 ## Generated files
 

package/bin/orionplace-react.mjs

@@ -1,6 +1,7 @@
 #!/usr/bin/env node
 import { setupProject } from '../src/setup.mjs';
 import { updateProject } from '../src/update.mjs';
+import { installService } from '../src/install.mjs';
 import { readFile } from 'node:fs/promises';
 import { resolve } from 'node:path';
 import { createInterface } from 'node:readline/promises';
@@ -29,8 +30,16 @@ Commands for an existing project (run from its root):
   npx orionplace-react set mimic <existing-frontend.example.com>
   npx orionplace-react set frontend <shop.example.com>
 
+On your Linux server (run from the project root):
+  sudo npx orionplace-react install
+  Builds the storefront, installs it as a system service (systemd or OpenRC)
+  and, when the orionplace server tool is set up, connects its domains with
+  nginx and HTTPS. Run it again after changes or an update to rebuild and restart.
+  Server tool: https://orionmarket.place/downloads/orionplace.sh
+
 Options: --cwd <directory>  --dry-run  --help  --version
 Update option: --local (apply this CLI version instead of fetching the latest release)
+Install options: --name <service>  --port <port>  --user <user>  --no-domains  --yes
 
 Update downloads the latest release, refreshes unedited source, and installs dependencies.
 It preserves edited source, domain mappings and MIMIC. --dry-run leaves project files unchanged.
@@ -53,10 +62,16 @@ try {
     let cwd          = process.cwd();
     let dryRun       = false;
     let local        = false;
+    const install    = { domains: true, yes: false };
     for (let index = 0; index < argv.length; index++) {
       if (argv[index] === '--dry-run') dryRun = true;
       else if (argv[index] === '--local') local = true;
-      else if (argv[index] === '--cwd') {
+      else if (argv[index] === '--no-domains') install.domains = false;
+      else if (argv[index] === '--yes' || argv[index] === '-y') install.yes = true;
+      else if (['--name', '--port', '--user'].includes(argv[index])) {
+        if (!argv[index + 1]) throw new Error(`${argv[index]} needs a value`);
+        install[argv[index].slice(2)] = argv[++index];
+      } else if (argv[index] === '--cwd') {
         if (!argv[index + 1]) throw new Error('--cwd needs a directory');
         cwd = resolve(argv[++index]);
       } else if (argv[index].startsWith('--')) throw new Error(`Unknown option: ${argv[index]}`);
@@ -64,8 +79,28 @@ try {
     }
     const [command, target] = positional;
     if (local && command !== 'update') throw new Error('--local is only supported by update.');
+    if (command !== 'install' && (install.name || install.port || install.user || !install.domains || install.yes)) {
+      throw new Error('--name, --port, --user, --no-domains and --yes are install options.');
+    }
     let result;
-    if (command === 'init' && positional.length <= 2) {
+    if (command === 'install' && positional.length === 1) {
+      const done = await installService({ cwd, dryRun, ...install });
+      if (done.dryRun) {
+        console.log(`Planned service orionplace-${done.name} on 127.0.0.1:${done.port} as ${done.user}`);
+        console.log(`Domains: ${done.frontends.join(', ') || 'none yet'} -> ${done.backend || 'no backend yet'}`);
+        console.log(`\n${done.unitPath}:\n${done.unit}`);
+      } else {
+        console.log(`\nInstalled orionplace-${done.name} (port ${done.port}, user ${done.user}).`);
+        for (const domain of done.frontends) {
+          if (!done.connected) console.log(`  - ${domain}: not connected to nginx (see above)`);
+          else if (done.failed.includes(domain)) console.log(`  ✗ ${domain}: not connected (see above)`);
+          else console.log(`  ✓ https://${domain}`);
+        }
+        if (done.failed.length) console.log('Fix the problems above, then run: sudo orionplace domain add <domain>');
+        console.log(`Manage it with: orionplace app status ${done.name} | orionplace app logs ${done.name}`);
+        console.log('After code changes or npx orionplace-react update, run sudo npx orionplace-react install again.');
+      }
+    } else if (command === 'init' && positional.length <= 2) {
       result = await setupProject({ cwd: target ? resolve(cwd, target) : cwd, dryRun });
     } else if (command === 'update' && positional.length === 1) {
       result = await updateProject({ cwd, dryRun, local });

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "orionplace-react",
-  "version": "0.2.1",
+  "version": "0.3.0",
   "description": "Next.js 16 storefront for your Orionplace marketplace: setup CLI, server API gateway, typed store and ready-made catalog, cart, checkout and account components in English and Russian, plus an Android app build.",
   "type": "module",
   "license": "MIT",

package/src/install.mjs

@@ -0,0 +1,355 @@
+// Installs the built storefront as a system service on a Linux server and
+// connects its domains through the "orionplace" server tool
+// (https://orionmarket.place/downloads/orionplace.sh) when that tool is set up.
+import { spawn } from 'node:child_process';
+import { mkdir, readFile, readdir, rename, stat, writeFile } from 'node:fs/promises';
+import { existsSync } from 'node:fs';
+import { request } from 'node:http';
+import { createServer } from 'node:net';
+import { basename, dirname, join, resolve } from 'node:path';
+import { createInterface } from 'node:readline/promises';
+import { setupProject } from './setup.mjs';
+
+export const framework = {
+  id:          'react',
+  title:       'Next.js',
+  dependency:  'next',
+  output:      '.next/BUILD_ID',
+  start:       port => ['node_modules/next/dist/bin/next', 'start', '--hostname', '127.0.0.1', '--port', String(port)],
+  environment: {},
+};
+
+export const defaultPaths = {
+  etc:     process.env.ORIONPLACE_ETC || '/etc/orionplace',
+  systemd: '/etc/systemd/system',
+  openrc:  '/etc/init.d',
+  logs:    '/var/log/orionplace',
+  srv:     '/srv/orionplace',
+  tool:    ['/usr/local/bin/orionplace', '/usr/bin/orionplace'],
+};
+
+const SERVICE_USER = 'orionplace';
+
+// run(command, args, { cwd, capture, env }) -> { code, output }
+export function runCommand(command, args, { cwd, capture = false, env = process.env } = {}) {
+  return new Promise((done, reject) => {
+    const child  = spawn(command, args, { cwd, env, stdio: capture ? ['ignore', 'pipe', 'pipe'] : 'inherit' });
+    let output   = '';
+    if (capture) {
+      child.stdout.on('data', chunk => { output += chunk; });
+      child.stderr.on('data', chunk => { output += chunk; });
+    }
+    child.once('error', reject);
+    child.once('exit', code => done({ code: code ?? 1, output }));
+  });
+}
+
+function parseConf(text) {
+  const values = {};
+  for (const line of text.split('\n')) {
+    const match = /^([A-Z_]+)=(.*)$/.exec(line);
+    if (match) values[match[1]] = match[2];
+  }
+  return values;
+}
+
+export async function readApps(paths = defaultPaths) {
+  const directory = join(paths.etc, 'apps');
+  let names       = [];
+  try { names = (await readdir(directory)).filter(name => name.endsWith('.conf')); }
+  catch (error) { if (error.code !== 'ENOENT') throw error; }
+  const apps      = [];
+  for (const name of names) apps.push(parseConf(await readFile(join(directory, name), 'utf8')));
+  return apps;
+}
+
+export function serviceName(value) {
+  const name = value.toLowerCase().replace(/[^a-z0-9-]+/g, '-').replace(/^-+|-+$/g, '').slice(0, 40);
+  if (!/^[a-z0-9][a-z0-9-]*$/.test(name)) throw new Error('Choose a service name with letters, digits and dashes: --name shop');
+  return name;
+}
+
+function portIsFree(port) {
+  return new Promise(done => {
+    const server = createServer();
+    server.once('error', () => done(false));
+    server.listen({ port, host: '127.0.0.1', exclusive: true }, () => server.close(() => done(true)));
+  });
+}
+
+export async function choosePort(apps, wanted, isFree = portIsFree) {
+  const taken = new Set(apps.map(app => Number(app.PORT)));
+  if (wanted) {
+    if (!Number.isInteger(wanted) || wanted < 1024 || wanted > 65535) throw new Error('Use a port between 1024 and 65535.');
+    return wanted;
+  }
+  for (let port = 3000; port < 4000; port++) {
+    if (!taken.has(port) && await isFree(port)) return port;
+  }
+  throw new Error('No free port between 3000 and 3999. Choose one with --port.');
+}
+
+async function passwdEntry(user) {
+  const text = await readFile('/etc/passwd', 'utf8');
+  for (const line of text.split('\n')) {
+    const [name, , uid, gid, , home] = line.split(':');
+    if (name === user) return { name, uid: Number(uid), gid: Number(gid), home };
+  }
+  return null;
+}
+
+async function userByUid(uid) {
+  const text = await readFile('/etc/passwd', 'utf8');
+  for (const line of text.split('\n')) {
+    const [name, , id, gid, , home] = line.split(':');
+    if (Number(id) === uid && name) return { name, uid, gid: Number(gid), home };
+  }
+  return null;
+}
+
+// Every parent folder must let the service user through.
+async function checkReachable(root, account) {
+  let cursor = dirname(root);
+  while (true) {
+    const info = await stat(cursor);
+    const open = info.uid === account.uid ? info.mode & 0o100 : info.gid === account.gid ? info.mode & 0o010 : info.mode & 0o001;
+    if (!open) {
+      throw new Error(`The folder ${cursor} is closed to the service user ${account.name}. Move the storefront to ${defaultPaths.srv}/ (for example ${defaultPaths.srv}/${basename(root)}) and run install there.`);
+    }
+    if (cursor === dirname(cursor)) return;
+    cursor = dirname(cursor);
+  }
+}
+
+async function writeAtomic(path, content, mode = 0o644) {
+  await mkdir(dirname(path), { recursive: true });
+  const temporary = `${path}.orionplace-${process.pid}.tmp`;
+  await writeFile(temporary, content, { mode });
+  await rename(temporary, path);
+}
+
+export function systemdUnit({ name, root, user, group, port, node, env }) {
+  const environment = Object.entries({ NODE_ENV: 'production', HOST: '127.0.0.1', PORT: String(port), SITEMAPS_DIR: join(root, 'sitemaps'), ...env })
+    .map(([key, value]) => `Environment=${key}=${value}`).join('\n');
+  const args        = [...(existsSync(join(root, '.env')) ? ['--env-file=.env'] : []), ...framework.start(port)];
+  return `# Installed by "orionplace-${framework.id} install". Run it again after changes;
+# manage with: orionplace app status|logs|restart ${name}
+[Unit]
+Description=OrionMarketplace storefront ${name} (${framework.title})
+After=network-online.target
+Wants=network-online.target
+
+[Service]
+Type=simple
+User=${user}
+Group=${group}
+WorkingDirectory=${root}
+${environment}
+ExecStart=${node} ${args.join(' ')}
+Restart=on-failure
+RestartSec=3
+LimitNOFILE=65535
+NoNewPrivileges=true
+PrivateTmp=true
+ProtectSystem=full
+
+[Install]
+WantedBy=multi-user.target
+`;
+}
+
+export function openrcScript({ name, root, user, group, port, node, env, logs }) {
+  const environment = Object.entries({ NODE_ENV: 'production', HOST: '127.0.0.1', PORT: String(port), SITEMAPS_DIR: join(root, 'sitemaps'), ...env })
+    .map(([key, value]) => `export ${key}="${value}"`).join('\n');
+  const args        = [...(existsSync(join(root, '.env')) ? ['--env-file=.env'] : []), ...framework.start(port)];
+  return `#!/sbin/openrc-run
+# Installed by "orionplace-${framework.id} install". Run it again after changes;
+# manage with: orionplace app status|logs|restart ${name}
+name="orionplace-${name}"
+description="OrionMarketplace storefront ${name} (${framework.title})"
+supervisor=supervise-daemon
+respawn_delay=3
+command="${node}"
+command_args="${args.join(' ')}"
+command_user="${user}:${group}"
+directory="${root}"
+output_log="${logs}/${name}.log"
+error_log="${logs}/${name}.log"
+${environment}
+
+depend() {
+  need net
+  after firewall
+}
+
+start_pre() {
+  checkpath --directory --owner ${user}:${group} --mode 0755 ${logs}
+}
+`;
+}
+
+async function prompt(question) {
+  const terminal = createInterface({ input: process.stdin, output: process.stdout });
+  try { return (await terminal.question(question)).trim(); }
+  finally { terminal.close(); }
+}
+
+function log(message) { console.log(message); }
+
+// /usr/local/bin/node from the server tool follows Node.js updates; the
+// versioned path of the running binary would not.
+function stableNode() {
+  return ['/usr/local/bin/node', '/usr/bin/node'].find(path => existsSync(path)) || process.execPath;
+}
+
+// Fills in the backend and first storefront domain when the project has none.
+async function ensureDomains(root, { yes }) {
+  const read     = async () => JSON.parse(await readFile(join(root, 'orionplace/settings.json'), 'utf8'));
+  let settings   = await read();
+  const ask      = process.stdin.isTTY && !yes;
+  if (!settings.backend) {
+    if (!ask) throw new Error(`Set the personal backend first: npx orionplace-${framework.id} set backend my-shop.orionplace.app`);
+    log('Your personal backend is shown in your orionmarket.place profile, for example my-shop.orionplace.app.');
+    await setupProject({ cwd: root, field: 'backend', value: await prompt('Personal backend domain: ') });
+    settings = await read();
+  }
+  if (!settings.frontends?.length) {
+    if (!ask) throw new Error(`Add the storefront domain first: npx orionplace-${framework.id} add frontend shop.example.com`);
+    await setupProject({ cwd: root, action: 'add', field: 'frontend', value: await prompt('Storefront domain (for example shop.example.com): ') });
+    settings = await read();
+  }
+  return settings;
+}
+
+// The storefront's home page as the public domain sees it -> HTTP status, 0 when down.
+function homeStatus(port, host) {
+  return new Promise(done => {
+    const call = request({ host: '127.0.0.1', port, path: '/', headers: { host }, timeout: 15000 }, response => {
+      response.resume();
+      done(response.statusCode);
+    });
+    call.once('timeout', () => call.destroy());
+    call.once('error', () => done(0));
+    call.end();
+  });
+}
+
+async function waitForHttp(port, host, seconds = 90) {
+  const until = Date.now() + seconds * 1000;
+  while (Date.now() < until) {
+    const status = await homeStatus(port, host);
+    if (status) return status;
+    await new Promise(done => setTimeout(done, 1000));
+  }
+  return 0;
+}
+
+export async function installService({
+  cwd = process.cwd(), name, port, user, build = true, domains = true, yes = false, dryRun = false,
+  paths = defaultPaths, run = runCommand, uid = process.getuid?.(), isFree = portIsFree,
+  systemd = existsSync('/run/systemd/system'), node = stableNode(),
+} = {}) {
+  if (process.platform !== 'linux') throw new Error('install sets up a Linux server service. Run it on your VPS.');
+  if (uid !== 0 && !dryRun) throw new Error(`install needs root: sudo npx orionplace-${framework.id} install`);
+  const root     = resolve(cwd);
+  if (!/^\/[A-Za-z0-9._/@+-]+$/.test(root)) throw new Error(`Use a storefront folder path without spaces or special characters (for example ${paths.srv}/shop), not ${root}.`);
+  let pkg;
+  try { pkg = JSON.parse(await readFile(join(root, 'package.json'), 'utf8')); }
+  catch { throw new Error(`Run install in your storefront folder (created with: npx orionplace-${framework.id} init).`); }
+  if (!{ ...pkg.devDependencies, ...pkg.dependencies }[framework.dependency] || !existsSync(join(root, 'orionplace/settings.json'))) {
+    throw new Error(`This folder is not an Orionplace ${framework.title} storefront. Run install in the folder created with: npx orionplace-${framework.id} init`);
+  }
+  const openrc   = !systemd && existsSync('/sbin/openrc-run');
+  if (!systemd && !openrc && !dryRun) throw new Error('Neither systemd nor OpenRC was found; start the storefront with your own process manager (see orionplace/README.md, Deploy on your VPS).');
+
+  const settings = dryRun ? JSON.parse(await readFile(join(root, 'orionplace/settings.json'), 'utf8')) : await ensureDomains(root, { yes });
+  const apps     = await readApps(paths);
+  const previous = apps.find(app => app.DIR === root);
+  const service  = serviceName(name || previous?.NAME || basename(root));
+  if (apps.some(app => app.NAME === service && app.DIR !== root)) {
+    throw new Error(`Another storefront already uses the name ${service} (${apps.find(app => app.NAME === service).DIR}). Choose one with --name.`);
+  }
+  const chosen   = await choosePort(apps.filter(app => app.DIR !== root), port ? Number(port) : Number(previous?.PORT) || 0, isFree);
+
+  // The service runs as the folder's owner, or as "orionplace" for root-owned folders.
+  const owner    = await stat(root);
+  let account    = user ? await passwdEntry(user) : owner.uid === 0 ? await passwdEntry(SERVICE_USER) : await userByUid(owner.uid);
+  if (user && !account) throw new Error(`No system user ${user}.`);
+  if (!account && !dryRun) {
+    if (existsSync('/usr/sbin/useradd') || existsSync('/sbin/useradd')) {
+      await run('useradd', ['--system', '--home-dir', paths.srv, '--shell', '/sbin/nologin', '--user-group', SERVICE_USER], { capture: true });
+    } else {
+      await run('addgroup', ['-S', SERVICE_USER], { capture: true });
+      await run('adduser', ['-S', '-D', '-H', '-h', paths.srv, '-s', '/sbin/nologin', '-G', SERVICE_USER, SERVICE_USER], { capture: true });
+    }
+    account = await passwdEntry(SERVICE_USER);
+    if (!account) throw new Error(`Could not create the system user ${SERVICE_USER}.`);
+  }
+  account      ||= { name: SERVICE_USER, uid: -1, gid: -1 };
+  const group    = account.gid >= 0 ? (await readFile('/etc/group', 'utf8')).split('\n').map(line => line.split(':'))
+    .find(([, , gid]) => Number(gid) === account.gid)?.[0] || account.name : account.name;
+  if (account.uid >= 0) await checkReachable(root, account);
+
+  const values   = { name: service, root, user: account.name, group, port: chosen, node, env: framework.environment, logs: paths.logs };
+  const unitPath = systemd ? join(paths.systemd, `orionplace-${service}.service`) : join(paths.openrc, `orionplace-${service}`);
+  const unit     = systemd ? systemdUnit(values) : openrcScript(values);
+  const conf     = [
+    `# Managed by orionplace-${framework.id} install. Use "orionplace app" commands to change it.`,
+    `NAME=${service}`, `FRAMEWORK=${framework.id}`, `DIR=${root}`, `PORT=${chosen}`,
+    `USER=${account.name}`, `NODE=${node}`, `SERVICE=orionplace-${service}`, '',
+  ].join('\n');
+  if (dryRun) {
+    return { dryRun, name: service, port: chosen, user: account.name, unitPath, unit, conf, frontends: settings.frontends || [], backend: settings.backend };
+  }
+
+  log(`\n==> Building the ${framework.title} storefront ${service}`);
+  // The website build; ORIONPLACE_APP_ORIGIN would make the Android app build.
+  const buildEnv = { ...process.env };
+  delete buildEnv.ORIONPLACE_APP_ORIGIN;
+  if (!existsSync(join(root, 'node_modules', framework.dependency))) {
+    const installed = await run('npm', ['install', '--no-audit', '--no-fund'], { cwd: root, env: buildEnv });
+    if (installed.code) throw new Error('npm install failed; see the messages above.');
+  }
+  if (build || !existsSync(join(root, framework.output))) {
+    const built = await run('npm', ['run', 'build'], { cwd: root, env: buildEnv });
+    if (built.code) throw new Error('The build failed; see the messages above. The running service (if any) was not changed.');
+  }
+  if (!existsSync(join(root, framework.output))) throw new Error(`The build did not produce ${framework.output}.`);
+  const owned    = await run('chown', ['-R', `${account.uid}:${account.gid}`, root], { capture: true });
+  if (owned.code) throw new Error(`Could not give ${root} to ${account.name}:\n${owned.output}`);
+
+  log(`\n==> Installing the service orionplace-${service} on port ${chosen}`);
+  await writeAtomic(unitPath, unit, systemd ? 0o644 : 0o755);
+  await writeAtomic(join(paths.etc, 'apps', `${service}.conf`), conf);
+  const steps    = systemd
+    ? [['systemctl', ['daemon-reload']], ['systemctl', ['enable', `orionplace-${service}`]], ['systemctl', ['restart', `orionplace-${service}`]]]
+    : [['rc-update', ['add', `orionplace-${service}`, 'default']], ['rc-service', [`orionplace-${service}`, 'restart']]];
+  for (const [command, args] of steps) {
+    const result = await run(command, args, { capture: true });
+    if (result.code) throw new Error(`${command} ${args.join(' ')} failed:\n${result.output}`);
+  }
+  const status   = await waitForHttp(chosen, settings.frontends[0]);
+  if (!status) {
+    const logs = systemd
+      ? await run('journalctl', ['-u', `orionplace-${service}`, '-n', '40', '--no-pager'], { capture: true })
+      : await run('tail', ['-n', '40', join(paths.logs, `${service}.log`)], { capture: true });
+    throw new Error(`The storefront did not start on port ${chosen}. Last log lines:\n${logs.output}`);
+  }
+  log(`  ✓ orionplace-${service} answers on 127.0.0.1:${chosen} (HTTP ${status})`);
+
+  const tool     = paths.tool.find(path => existsSync(path));
+  const failed   = [];
+  if (domains && tool) {
+    for (const domain of settings.frontends) {
+      log(`\n==> Connecting ${domain}`);
+      const backend = settings.backend.replace(/^https:\/\//, '').replace(/\/api$/, '');
+      const result  = await run(tool, ['domain', 'add', domain, '--app', service, '--backend', backend, '--yes']);
+      if (result.code) failed.push(domain);
+    }
+  } else if (domains) {
+    log('\nThe orionplace server tool is not set up, so nginx and HTTPS were not configured. Prepare the server:');
+    log('  curl -fsSLo orionplace.sh https://orionmarket.place/downloads/orionplace.sh && sudo sh orionplace.sh setup');
+    log(`Then run this install again. Or proxy your HTTPS site to http://127.0.0.1:${chosen} as orionplace/README.md describes.`);
+  }
+  return { name: service, port: chosen, user: account.name, unitPath, frontends: settings.frontends, failed, connected: domains && Boolean(tool) };
+}

package/src/project-readme.mjs

@@ -346,6 +346,13 @@ If installation fails after source generation, run \`npm install\` and retry.
 
 ## Deploy on your VPS
 
+The quickest way: prepare the server with the OrionMarketplace server script,
+then run \`sudo npx orionplace-react install\` in this folder. It builds the
+project, runs it as a system service and connects your domains with nginx and
+HTTPS. Steps: [Install a storefront](https://orionmarket.place/en/sandbox/install/storefront?framework=react).
+
+To set the server up yourself instead:
+
 This integration needs a Node.js server and its domain configuration files.
 It does not support static export or edge-only hosting. Deploy the build,
 dependencies, \`sitemaps\`, and your environment configuration together; use an