create-apollo-monorepo 0.7.0 → 0.9.0

package/index.mjs

@@ -26,6 +26,7 @@ const BACKEND_REPO_URL = "https://github.com/5Lab-Group-Co-Ltd/apollo-cms.git";
 const BACKEND_BRANCH = "main";
 const BACKEND_PATH = "apps/backend";
 const FRONTEND_PATH = "apps/frontend";
+const PROXY_PATH = "apps/proxy";
 const MIN_NODE_MAJOR = 20;
 
 const COLORS = {
@@ -355,13 +356,42 @@ function writeRootPackageJson(targetDir, dirName) {
       // dist/server.mjs on next request.
       dev:
         "pnpm predev:setup && concurrently -k -n FE,BE,PL -c blue,magenta,yellow \"pnpm --filter ./apps/frontend dev\" \"pnpm --filter ./apps/backend exec next dev\" \"pnpm cms-plugins:dev\"",
+      // Optional single-origin dev: same as `pnpm dev` but adds a Node.js
+      // reverse proxy on :3030 that fronts FE :3001 + BE :3000. Use it when
+      // you want one URL, shared cookies, and no CORS — without nginx.
+      "dev:rp":
+        "pnpm predev:setup && concurrently -k -n FE,BE,PL,PX -c blue,magenta,yellow,cyan \"pnpm --filter ./apps/frontend dev\" \"pnpm --filter ./apps/backend exec next dev\" \"pnpm cms-plugins:dev\" \"pnpm dev:proxy\"",
+      "dev:proxy": "node apps/proxy/server.mjs",
       "dev:frontend": "pnpm --filter ./apps/frontend dev",
       "dev:backend":
         "pnpm predev:setup && pnpm --filter ./apps/backend exec next dev",
       "dev:cron": "pnpm --filter ./apps/backend exec bun scripts/dev-cron.ts",
       // Build pipeline: cms-plugins → apollo-cms's own plugins → backend → frontend.
+      // `prebuild` runs first (npm/pnpm convention) and fails fast if the
+      // backend's required env vars are missing.
+      prebuild: "node scripts/check-env.mjs",
       build:
         "pnpm cms-plugins:build && pnpm --filter ./apps/backend exec bun run plugins:build && pnpm --filter ./apps/backend build && pnpm --filter ./apps/frontend build",
+      "build:backend":
+        "pnpm cms-plugins:build && pnpm --filter ./apps/backend exec bun run plugins:build && pnpm --filter ./apps/backend build",
+      "build:frontend": "pnpm --filter ./apps/frontend build",
+      // Production start. Runs FE :3001 + BE :3000 in parallel via
+      // \`next start\`. Run \`pnpm backend:upgrade\` BEFORE this — start does
+      // NOT run migrations on boot (zero-downtime restart safety).
+      start:
+        "concurrently -k -n FE,BE -c blue,magenta \"pnpm --filter ./apps/frontend start\" \"pnpm --filter ./apps/backend exec next start\"",
+      // Single-origin production: FE + BE + Node reverse proxy on :3030.
+      "start:rp":
+        "concurrently -k -n FE,BE,PX -c blue,magenta,cyan \"pnpm --filter ./apps/frontend start\" \"pnpm --filter ./apps/backend exec next start\" \"pnpm start:proxy\"",
+      "start:proxy": "NODE_ENV=production node apps/proxy/server.mjs",
+      "start:frontend": "pnpm --filter ./apps/frontend start",
+      "start:backend": "pnpm --filter ./apps/backend exec next start",
+      // Self-hosted scheduler fallback. Vercel deploys use Vercel Cron via
+      // apps/backend/vercel.json — skip this on Vercel. For Docker / VPS
+      // you can either run \`pnpm start:cron\` alongside \`pnpm start\` (PM2
+      // handles this via ecosystem.config.cjs), or use system cron / k8s
+      // CronJob to hit /api/cron with CRON_SECRET.
+      "start:cron": "pnpm --filter ./apps/backend exec bun scripts/dev-cron.ts",
       "cms-plugins:build":
         "pnpm --filter './apps/cms-plugins/*' --parallel --if-present build",
       "cms-plugins:dev":
@@ -487,6 +517,312 @@ server {
   writeFileSync(resolve(targetDir, "nginx.conf.sample"), conf);
 }
 
+// Optional Node.js reverse proxy. Mirrors nginx.conf.sample routing rules
+// but runs in-process — opt in via `pnpm dev:rp`. Zero deps, ~80 LOC.
+function writeProxyApp(targetDir, dirName, adminPrefix) {
+  const dir = resolve(targetDir, PROXY_PATH);
+  mkdirSync(dir, { recursive: true });
+
+  const prefix = adminPrefix || "/admin";
+  const server = `// ${dirName} — single-origin reverse proxy (zero deps).
+// Mirrors ../../nginx.conf.sample. Run via \`pnpm dev:rp\` from the repo root.
+//
+// Routes (in order):
+//   ${prefix}, ${prefix}/*, /uploads/*, /monitoring          → backend
+//   /api/editing-presence/*                                  → backend (SSE)
+//   /api/{auth,v1,cron,email,health,mcp,admin,...}/*         → backend
+//   /__proxy/health                                          → 200 OK (proxy itself)
+//   everything else                                          → frontend
+//
+// Production note: this proxy doesn't terminate TLS. For HTTPS, sit behind a
+// load balancer (Caddy, Cloudflare, ALB) or use \`nginx.conf.sample\` instead.
+
+import http from "node:http";
+import net from "node:net";
+
+const PORT = Number(process.env.PORT ?? 3030);
+const BACKEND = parseTarget(process.env.BACKEND ?? "http://127.0.0.1:3000");
+const FRONTEND = parseTarget(process.env.FRONTEND ?? "http://127.0.0.1:3001");
+
+const ADMIN_PREFIX = process.env.ADMIN_PREFIX ?? "${prefix}";
+// Pipe-separated list of /api/<segment> paths that route to the backend.
+const BACKEND_API_SEGMENTS = (
+  process.env.BACKEND_API_PATHS ??
+  "auth|v1|cron|email|health|mcp|admin|editing-presence"
+).trim();
+const BACKEND_API = new RegExp(\`^/api/(\${BACKEND_API_SEGMENTS})(/|$)\`);
+
+// 50MB matches nginx.conf.sample's client_max_body_size and Next.js's
+// Server Actions body limit. Override via MAX_BODY_BYTES (0 = unlimited).
+const MAX_BODY_BYTES = Number(process.env.MAX_BODY_BYTES ?? 50 * 1024 * 1024);
+const UPSTREAM_TIMEOUT_MS = Number(process.env.UPSTREAM_TIMEOUT_MS ?? 60_000);
+// When false (default), strip incoming X-Forwarded-* before adding our own —
+// prevents header spoofing when the proxy faces the public internet directly.
+// Set TRUST_PROXY=1 only when behind another trusted reverse proxy (CDN, LB).
+const TRUST_PROXY = process.env.TRUST_PROXY === "1";
+
+// Hop-by-hop headers (RFC 7230 §6.1) — must not be forwarded.
+const HOP_BY_HOP = new Set([
+  "connection",
+  "keep-alive",
+  "proxy-authenticate",
+  "proxy-authorization",
+  "te",
+  "trailer",
+  "transfer-encoding",
+  "upgrade",
+]);
+
+// Reuse TCP connections to upstreams — eliminates ~1ms per request.
+const backendAgent = new http.Agent({ keepAlive: true });
+const frontendAgent = new http.Agent({ keepAlive: true });
+
+function pickUpstream(url) {
+  if (url === ADMIN_PREFIX || url.startsWith(\`\${ADMIN_PREFIX}/\`))
+    return { ...BACKEND, agent: backendAgent };
+  if (url.startsWith("/uploads/")) return { ...BACKEND, agent: backendAgent };
+  if (url === "/monitoring") return { ...BACKEND, agent: backendAgent };
+  if (BACKEND_API.test(url)) return { ...BACKEND, agent: backendAgent };
+  return { ...FRONTEND, agent: frontendAgent };
+}
+
+function sanitizeHeaders(req, clientIp) {
+  const out = {};
+  for (const [k, v] of Object.entries(req.headers)) {
+    const lower = k.toLowerCase();
+    if (HOP_BY_HOP.has(lower)) continue;
+    // Strip client-supplied X-Forwarded-* unless TRUST_PROXY is set.
+    if (!TRUST_PROXY && lower.startsWith("x-forwarded-")) continue;
+    out[k] = v;
+  }
+  // Always set X-Forwarded-* with our own values (append client IP).
+  const existingFor = TRUST_PROXY ? req.headers["x-forwarded-for"] : undefined;
+  out["x-forwarded-for"] = existingFor ? \`\${existingFor}, \${clientIp}\` : clientIp;
+  out["x-forwarded-proto"] = TRUST_PROXY
+    ? req.headers["x-forwarded-proto"] ?? "http"
+    : "http";
+  out["x-forwarded-host"] = TRUST_PROXY
+    ? req.headers["x-forwarded-host"] ?? req.headers.host ?? ""
+    : req.headers.host ?? "";
+  return out;
+}
+
+function logError(scope, err, extra) {
+  const ts = new Date().toISOString();
+  const detail = extra ? \` \${JSON.stringify(extra)}\` : "";
+  console.error(\`[\${ts}] proxy:\${scope} \${err.code ?? ""} \${err.message}\${detail}\`);
+}
+
+const server = http.createServer((req, res) => {
+  // Health check (proxy itself, never forwarded).
+  if (req.url === "/__proxy/health") {
+    res.writeHead(200, { "content-type": "application/json" });
+    res.end(JSON.stringify({ status: "ok", uptime: process.uptime() }));
+    return;
+  }
+
+  // Enforce body size limit (DoS protection).
+  if (MAX_BODY_BYTES > 0) {
+    const declared = Number(req.headers["content-length"] ?? 0);
+    if (declared > MAX_BODY_BYTES) {
+      res.writeHead(413, { "content-type": "text/plain" });
+      res.end("Payload Too Large");
+      return;
+    }
+    let received = 0;
+    req.on("data", (chunk) => {
+      received += chunk.length;
+      if (received > MAX_BODY_BYTES) {
+        req.destroy(new Error("Body exceeded MAX_BODY_BYTES"));
+      }
+    });
+  }
+
+  const upstream = pickUpstream(req.url);
+  const proxyReq = http.request(
+    {
+      host: upstream.host,
+      port: upstream.port,
+      method: req.method,
+      path: req.url,
+      headers: sanitizeHeaders(req, req.socket.remoteAddress ?? ""),
+      agent: upstream.agent,
+      timeout: UPSTREAM_TIMEOUT_MS,
+    },
+    (proxyRes) => {
+      // Strip hop-by-hop headers from upstream response too.
+      const safe = {};
+      for (const [k, v] of Object.entries(proxyRes.headers)) {
+        if (!HOP_BY_HOP.has(k.toLowerCase())) safe[k] = v;
+      }
+      res.writeHead(proxyRes.statusCode ?? 502, safe);
+      proxyRes.pipe(res);
+    },
+  );
+  proxyReq.on("timeout", () => {
+    logError("upstream-timeout", new Error("upstream timeout"), { url: req.url });
+    proxyReq.destroy(new Error("Upstream timeout"));
+  });
+  proxyReq.on("error", (err) => {
+    logError("upstream", err, { url: req.url });
+    if (!res.headersSent) {
+      res.writeHead(502, { "content-type": "text/plain" });
+      res.end("Bad Gateway");
+    }
+    if (!req.destroyed) req.destroy();
+  });
+  req.on("error", (err) => {
+    logError("client", err, { url: req.url });
+    if (!proxyReq.destroyed) proxyReq.destroy();
+  });
+  req.pipe(proxyReq);
+});
+
+// WebSocket / HTTP upgrade passthrough — required for Next.js HMR.
+server.on("upgrade", (req, clientSocket, head) => {
+  const upstream = pickUpstream(req.url);
+  const upstreamSocket = net.connect(upstream.port, upstream.host, () => {
+    const headers = sanitizeHeaders(req, req.socket.remoteAddress ?? "");
+    // Re-add Connection: Upgrade & Upgrade headers stripped by sanitizeHeaders.
+    headers["connection"] = "Upgrade";
+    if (req.headers.upgrade) headers["upgrade"] = req.headers.upgrade;
+    const headerLines = [];
+    for (const [k, v] of Object.entries(headers)) {
+      const values = Array.isArray(v) ? v : [v];
+      for (const single of values) {
+        const str = String(single);
+        // Defense-in-depth: reject CRLF in header values (header injection).
+        if (/[\\r\\n]/.test(str)) continue;
+        headerLines.push(\`\${k}: \${str}\`);
+      }
+    }
+    upstreamSocket.write(
+      \`\${req.method} \${req.url} HTTP/\${req.httpVersion}\\r\\n\` +
+        headerLines.join("\\r\\n") +
+        "\\r\\n\\r\\n",
+    );
+    if (head?.length) upstreamSocket.write(head);
+    upstreamSocket.pipe(clientSocket);
+    clientSocket.pipe(upstreamSocket);
+  });
+  upstreamSocket.on("error", (err) => {
+    logError("ws-upstream", err, { url: req.url });
+    clientSocket.destroy();
+  });
+  clientSocket.on("error", (err) => {
+    logError("ws-client", err, { url: req.url });
+    upstreamSocket.destroy();
+  });
+});
+
+server.listen(PORT, () => {
+  console.log(\`apollo-proxy → http://localhost:\${PORT}\`);
+  console.log(\`  \${ADMIN_PREFIX}/*, /uploads/*, /api/*  → \${BACKEND.host}:\${BACKEND.port}\`);
+  console.log(\`  /*  → \${FRONTEND.host}:\${FRONTEND.port}\`);
+  console.log(\`  TRUST_PROXY=\${TRUST_PROXY}  MAX_BODY_BYTES=\${MAX_BODY_BYTES}  UPSTREAM_TIMEOUT_MS=\${UPSTREAM_TIMEOUT_MS}\`);
+});
+
+// Graceful shutdown — let in-flight requests finish, then exit.
+let shuttingDown = false;
+function shutdown(signal) {
+  if (shuttingDown) return;
+  shuttingDown = true;
+  console.log(\`\\napollo-proxy: \${signal} received, draining...\`);
+  server.close(() => {
+    backendAgent.destroy();
+    frontendAgent.destroy();
+    process.exit(0);
+  });
+  // Hard exit after 10s if connections refuse to drain.
+  setTimeout(() => process.exit(1), 10_000).unref();
+}
+process.on("SIGTERM", () => shutdown("SIGTERM"));
+process.on("SIGINT", () => shutdown("SIGINT"));
+
+function parseTarget(input) {
+  const url = new URL(input.startsWith(":") ? \`http://127.0.0.1\${input}\` : input);
+  return { host: url.hostname, port: Number(url.port || 80) };
+}
+`;
+  writeFileSync(resolve(dir, "server.mjs"), server);
+
+  const pkg = {
+    name: `@${dirName}/proxy`,
+    private: true,
+    version: "0.0.0",
+    description: "Optional Node.js reverse proxy fronting frontend + backend on a single origin",
+    type: "module",
+    main: "server.mjs",
+    scripts: {
+      start: "node server.mjs",
+    },
+    engines: { node: ">=20" },
+  };
+  writeFileSync(resolve(dir, "package.json"), JSON.stringify(pkg, null, 2) + "\n");
+
+  const readme = `# @${dirName}/proxy
+
+Optional single-origin reverse proxy. Routes \`${prefix}/*\`, \`/api/*\`, and
+\`/uploads/*\` to the backend; everything else to the frontend. Zero deps.
+
+## When to use
+
+- You want **one URL** for FE + BE locally (shared cookies, no CORS).
+- You don't want to install nginx for local dev.
+
+## Usage
+
+From the repo root:
+
+\`\`\`bash
+pnpm dev:rp        # runs FE :3001 + BE :3000 + plugins watcher + proxy :3030
+\`\`\`
+
+Then open http://localhost:3030.
+
+For best results, set \`NEXT_PUBLIC_SITE_URL=http://localhost:3030\` in your
+\`.env.local\` so Better Auth, OAuth callbacks, and email links all use the
+single-origin URL.
+
+## Configuration
+
+| Env var               | Default                          | Notes                                                          |
+| --------------------- | -------------------------------- | -------------------------------------------------------------- |
+| \`PORT\`                | \`3030\`                            | Public port                                                    |
+| \`BACKEND\`             | \`http://127.0.0.1:3000\`           | apps/backend dev server                                        |
+| \`FRONTEND\`            | \`http://127.0.0.1:3001\`           | apps/frontend dev server                                       |
+| \`ADMIN_PREFIX\`        | \`${prefix}\`                          | Backend admin path prefix                                      |
+| \`BACKEND_API_PATHS\`   | \`auth\\|v1\\|cron\\|email\\|health\\|mcp\\|admin\\|editing-presence\` | Pipe-separated /api/* segments routed to backend |
+| \`MAX_BODY_BYTES\`      | \`52428800\` (50MB)                 | Reject larger bodies. \`0\` = unlimited                          |
+| \`UPSTREAM_TIMEOUT_MS\` | \`60000\`                           | Request timeout to upstream                                    |
+| \`TRUST_PROXY\`         | \`0\`                               | Set \`1\` only if behind another trusted proxy (CDN/LB)          |
+
+## Health check
+
+\`GET /__proxy/health\` returns \`{"status":"ok","uptime":<seconds>}\`. Use it for
+liveness probes; the path is reserved by the proxy and never forwarded.
+
+## Better Auth interaction
+
+Apollo CMS's Better Auth derives the request origin from \`x-forwarded-host\` /
+\`x-forwarded-proto\`. This proxy sets both correctly, so \`trustedOrigins\` keeps
+working through the proxy. The recent fix in \`src/lib/auth/server.ts\` ensures
+the actual request origin (e.g. \`localhost:3030\`) is added to trusted origins
+even when \`NEXT_PUBLIC_SITE_URL\` points elsewhere.
+
+## Production
+
+This proxy doesn't terminate TLS. For HTTPS, either:
+
+- Sit it behind a TLS-terminating load balancer (Caddy, Cloudflare, ALB), **or**
+- Use \`nginx.conf.sample\` at the repo root instead — nginx handles TLS, gzip,
+  and large-scale traffic better.
+
+The Node proxy is intended for dev and small self-hosted deploys.
+`;
+  writeFileSync(resolve(dir, "README.md"), readme);
+}
+
 function writeRootGitignore(targetDir) {
   const ignore = [
     "node_modules",
@@ -931,6 +1267,122 @@ console.log(\`Run: pnpm install && pnpm cms-plugins:build && pnpm dev:backend\`)
   writeFileSync(resolve(scriptsDir, "new-cms-plugin.mjs"), script);
 }
 
+// Pre-build env check. Fails the build before \`next build\` runs if backend
+// required vars are missing, so users don't sit through a 30s build only to
+// hit a runtime error on first request.
+function writeCheckEnvScript(targetDir) {
+  const scriptsDir = resolve(targetDir, "scripts");
+  mkdirSync(scriptsDir, { recursive: true });
+  const script = `#!/usr/bin/env node
+// Pre-build sanity check. Reads apps/backend/.env.local and verifies that
+// required vars are present and non-empty. Skipped when SKIP_ENV_CHECK=1.
+//
+// In CI/Vercel where envs come from the platform (not files), set
+// SKIP_ENV_CHECK=1 and rely on the platform's own validation.
+
+import { existsSync, readFileSync } from "node:fs";
+import { dirname, resolve } from "node:path";
+import { fileURLToPath } from "node:url";
+
+if (process.env.SKIP_ENV_CHECK === "1") process.exit(0);
+
+const REQUIRED = ["DATABASE_URL", "APOLLO_SECRET", "NEXT_PUBLIC_DEFAULT_LOCALE"];
+
+const __dirname = dirname(fileURLToPath(import.meta.url));
+const envPath = resolve(__dirname, "../apps/backend/.env.local");
+
+if (!existsSync(envPath)) {
+  // Allow build to proceed if env vars are coming from process.env directly.
+  const fromProcess = REQUIRED.every((k) => process.env[k]);
+  if (fromProcess) process.exit(0);
+  console.error(
+    \`✗ Missing apps/backend/.env.local and required vars not in process.env.\\n  Required: \${REQUIRED.join(", ")}\\n  Hint: re-run the installer or copy apps/backend/.env.local.example\`,
+  );
+  process.exit(1);
+}
+
+const env = Object.fromEntries(
+  readFileSync(envPath, "utf-8")
+    .split("\\n")
+    .filter((line) => line && !line.startsWith("#"))
+    .map((line) => {
+      const i = line.indexOf("=");
+      return i === -1 ? [line, ""] : [line.slice(0, i).trim(), line.slice(i + 1).trim()];
+    }),
+);
+
+const missing = REQUIRED.filter((k) => !env[k] && !process.env[k]);
+if (missing.length) {
+  console.error(\`✗ Missing required env vars: \${missing.join(", ")}\\n  Edit apps/backend/.env.local or set them in process.env.\`);
+  process.exit(1);
+}
+console.log("✓ env check passed");
+`;
+  writeFileSync(resolve(scriptsDir, "check-env.mjs"), script);
+}
+
+// PM2 ecosystem config — production process supervision for self-hosted deploys.
+// Includes FE, BE, optional proxy, and optional cron in fork mode (no clustering
+// since Next.js handles that internally and the proxy is single-threaded by design).
+function writePm2Config(targetDir, dirName, adminPrefix) {
+  const singleOrigin = !!adminPrefix;
+  const config = `// PM2 ecosystem config for ${dirName}.
+// Usage:
+//   pnpm install
+//   pnpm backend:upgrade
+//   pnpm build
+//   pm2 start ecosystem.config.cjs                    # FE + BE
+//   pm2 start ecosystem.config.cjs --only proxy       # add reverse proxy
+//   pm2 start ecosystem.config.cjs --only cron        # self-hosted cron fallback
+//   pm2 save && pm2 startup                           # persist across reboots
+
+module.exports = {
+  apps: [
+    {
+      name: "frontend",
+      cwd: "./apps/frontend",
+      script: "node_modules/next/dist/bin/next",
+      args: "start",
+      env: { NODE_ENV: "production", PORT: 3001 },
+      max_memory_restart: "1G",
+      autorestart: true,
+    },
+    {
+      name: "backend",
+      cwd: "./apps/backend",
+      script: "node_modules/next/dist/bin/next",
+      args: "start",
+      env: { NODE_ENV: "production", PORT: 3000 },
+      max_memory_restart: "1G",
+      autorestart: true,
+    },
+    {
+      name: "proxy",
+      script: "./apps/proxy/server.mjs",
+      env: {
+        NODE_ENV: "production",
+        PORT: 3030,
+        BACKEND: "http://127.0.0.1:3000",
+        FRONTEND: "http://127.0.0.1:3001",
+        ${singleOrigin ? `ADMIN_PREFIX: "${adminPrefix}",` : ""}
+      },
+      max_memory_restart: "256M",
+      autorestart: true,
+    },
+    {
+      name: "cron",
+      cwd: "./apps/backend",
+      script: "scripts/dev-cron.ts",
+      interpreter: "bun",
+      env: { NODE_ENV: "production" },
+      autorestart: true,
+    },
+  ],
+};
+`;
+  writeFileSync(resolve(targetDir, "ecosystem.config.cjs"), config);
+}
+
 function writeReadme(targetDir, dirName, frontendName, adminPrefix) {
   const singleOrigin = !!adminPrefix;
 
@@ -951,12 +1403,17 @@ paths to the backend so /_next/* doesn't collide:
 The frontend MUST NOT define routes at \`/admin\`, \`/api/auth\`, \`/api/v1\`, etc.
 If you need your own API, namespace it under \`/api/internal/*\` or similar.
 
-### Reverse proxy (nginx)
+### Reverse proxy
+
+Two options ship out of the box:
 
-A reference \`nginx.conf.sample\` ships at the repo root with the same routing
-baked in (frontend on :3001, backend on :3000). Use it when fronting both apps
-behind a single TLS-terminating proxy outside Vercel — drop in your domain and
-SSL certs.
+- **\`apps/proxy\`** (Node.js, zero deps) — opt in with \`pnpm dev:rp\`. Runs FE,
+  BE, plugins watcher, and a reverse proxy on **:3030** so everything sits on
+  one origin (shared cookies, no CORS). Best for local dev and small self-hosted
+  deploys. Configure via \`PORT\`, \`BACKEND\`, \`FRONTEND\`, \`ADMIN_PREFIX\`.
+- **\`nginx.conf.sample\`** (production) — same routing baked in (frontend on
+  :3001, backend on :3000). Use it when fronting both apps behind a single
+  TLS-terminating proxy outside Vercel — drop in your domain and SSL certs.
 
 To **disable** single-origin and run the backend on its own subdomain,
 delete \`APOLLO_ASSET_PREFIX\` from \`apps/backend/.env.local\` and remove the
@@ -1007,8 +1464,14 @@ ${dirName}/
 pnpm install
 pnpm backend:setup       # push schema + seed apollo-cms
 pnpm dev                 # runs frontend (3001) + backend (3000) in parallel
+# or:
+pnpm dev:rp              # same + reverse proxy on :3030 (single-origin, shared cookies)
 \`\`\`
 
+When using \`pnpm dev:rp\`, set \`NEXT_PUBLIC_SITE_URL=http://localhost:3030\`
+in your \`.env.local\` so Better Auth, OAuth callbacks, and email links use
+the unified origin.
+
 ${originSection}
 ## Custom plugins
 
@@ -1067,6 +1530,53 @@ Do **not** edit files inside \`apps/backend\`. Open issues / PRs in the
 Shared dev env lives in the root \`.env.local\`. The backend reads its own
 \`apps/backend/.env.local\` (already populated by the installer).
 
+## Deploy (self-hosted)
+
+Standard sequence on a VPS / Docker host / bare metal:
+
+\`\`\`bash
+pnpm install
+pnpm backend:upgrade   # db push + replay data migrations + seed (run ONCE per release)
+pnpm build             # builds plugins → backend → frontend
+pnpm start             # FE :3001 + BE :3000  — or:
+pnpm start:rp          # adds Node reverse proxy on :3030 (single origin)
+\`\`\`
+
+\`pnpm start\` does **not** run migrations on boot — that lets you restart
+processes without re-running \`drizzle-kit push\` every time. Always run
+\`pnpm backend:upgrade\` once per release before \`pnpm start\`.
+
+| Script              | What it does                                                        |
+| ------------------- | ------------------------------------------------------------------- |
+| \`pnpm build\`        | Full pipeline: cms-plugins → backend plugins → backend → frontend   |
+| \`pnpm start\`        | FE + BE (parallel \`next start\`)                                     |
+| \`pnpm start:rp\`     | FE + BE + reverse proxy on :3030                                    |
+| \`pnpm start:proxy\`  | Reverse proxy alone (already running FE/BE separately)              |
+| \`pnpm start:cron\`   | Self-hosted cron fallback — only if not using Vercel Cron / k8s     |
+
+### PM2 (recommended for VPS)
+
+The installer scaffolds \`ecosystem.config.cjs\`. To supervise everything:
+
+\`\`\`bash
+pm2 start ecosystem.config.cjs                  # FE + BE + proxy + cron (all four)
+pm2 start ecosystem.config.cjs --only frontend,backend   # just the two apps
+pm2 save && pm2 startup                         # persist across reboots
+pm2 logs                                        # tail all processes
+pm2 reload all                                  # zero-downtime restart
+\`\`\`
+
+The proxy and cron processes can be omitted with \`--only\` if you front the
+apps with nginx/Caddy or use platform cron (system cron, k8s CronJob).
+
+### Docker / k8s
+
+For containerized deploys:
+- Bake the build into the image (\`pnpm install && pnpm build\`)
+- Set entrypoint to \`pnpm start\` or \`pnpm start:rp\`
+- Run \`pnpm backend:upgrade\` as a separate init container / Job before app pods start
+- Use platform-native cron (k8s CronJob hitting \`/api/cron\` with \`CRON_SECRET\`) instead of \`pnpm start:cron\`
+
 ## Deploy on Vercel
 
 Two Vercel projects, one repo. Each project picks up its own Root Directory.
@@ -1182,10 +1692,13 @@ async function main() {
   writeRootEnv(targetDir, { dbUrl, siteUrl, locale, authSecret, cronSecret, adminPrefix, backendInternalUrl });
   writeReadme(targetDir, dirName, frontendName, adminPrefix);
   if (adminPrefix) writeNginxSample(targetDir, adminPrefix);
+  writeProxyApp(targetDir, dirName, adminPrefix);
+  writeCheckEnvScript(targetDir);
+  writePm2Config(targetDir, dirName, adminPrefix);
   success(
     `package.json, pnpm-workspace.yaml, .gitignore, .env.local, README.md${
       adminPrefix ? ", nginx.conf.sample" : ""
-    }`,
+    }, apps/proxy, ecosystem.config.cjs, scripts/check-env.mjs`,
   );
 
   // ── Step 4: git init ──

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "create-apollo-monorepo",
-  "version": "0.7.0",
+  "version": "0.9.0",
   "description": "Scaffold a monorepo with a frontend app and Apollo CMS as a git submodule backend (single-origin via Next.js rewrites + assetPrefix)",
   "bin": {
     "create-apollo-monorepo": "index.mjs"