Merge pull request #235 from objectstack-ai/copilot/evaluate-vercel-deployment

Author: hotlong

DEPLOYMENT.md

@@ -0,0 +1,192 @@
+# Deployment Guide
+
+## Overview
+
+ObjectOS can run in two modes:
+
+| Mode | Command | Description |
+|---|---|---|
+| **Self-hosted** | `pnpm start` | Single Node.js process serving API + static assets |
+| **Vercel** | Push to Git | Serverless function (API) + CDN (static assets) |
+
+---
+
+## Build Outputs (dist folders)
+
+| Output | Path | Contents |
+|---|---|---|
+| Admin Console (SPA) | `apps/web/dist` | Vite build — HTML/JS/CSS |
+| Documentation (static) | `apps/site/out` | Next.js static export — HTML/CSS |
+| Server Plugins | `packages/*/dist` | tsup bundles — ESM + CJS |
+
+Run `pnpm build` (Turborepo) to build everything. Build order is managed
+automatically via workspace dependency graph.
+
+---
+
+## Self-Hosted Deployment (`pnpm start`)
+
+### How it works
+
+```
+pnpm start
+  └─ pnpm objectstack:serve
+       └─ objectstack serve --port 5320
+            └─ Hono + @hono/node-server
+```
+
+`objectstack serve` boots the ObjectStack Kernel:
+
+1. Reads `objectstack.config.ts` for plugin list and metadata patterns
+2. Loads all plugins (Auth, RBAC, Workflow, Automation, etc.)
+3. Starts the Hono HTTP server on the configured port
+4. Mounts static directories for the Admin Console and docs
+
+### URL Routing
+
+| URL Pattern | Served By |
+|---|---|
+| `/api/v1/*` | Hono API routes (plugins register handlers) |
+| `/console/*` | `apps/web/dist` — Vite SPA (static mount, SPA fallback) |
+| `/docs/*` | `apps/site/out` — Next.js static HTML (static mount) |
+
+### Production Steps
+
+```bash
+# 1. Install dependencies
+pnpm install
+
+# 2. Build everything (packages + apps)
+pnpm build
+
+# 3. Start single-process server
+pnpm start
+# → http://localhost:5320/api/v1/health
+# → http://localhost:5320/console/
+# → http://localhost:5320/docs/
+```
+
+### Docker
+
+```bash
+docker compose up -d
+# → http://localhost:5320
+```
+
+See `Dockerfile` for multi-stage build and `docker-compose.yml` for
+PostgreSQL + Redis services.
+
+### Environment Variables
+
+| Variable | Default | Description |
+|---|---|---|
+| `PORT` | `5320` | Server listen port |
+| `LOG_LEVEL` | `info` | Pino log level |
+| `CORS_ORIGINS` | `http://localhost:5321,http://localhost:5320` | Comma-separated allowed origins |
+| `NODE_ENV` | — | Set to `production` for production |
+
+---
+
+## Vercel Deployment
+
+### Architecture
+
+On Vercel, the single-process server is split into two parts:
+
+```
+Vercel CDN (Edge)               Vercel Serverless (Node.js)
+┌──────────────────────┐        ┌───────────────────────────┐
+│  apps/web/dist       │        │  api/index.ts             │
+│  ├── index.html      │        │  └─ bootstraps Kernel     │
+│  ├── assets/         │        │     └─ Hono app           │
+│  └── docs/           │        │        └─ /api/v1/*       │
+│      └── (site/out)  │        │                           │
+└──────────────────────┘        └───────────────────────────┘
+```
+
+- **Static assets** (`apps/web/dist` + `apps/site/out`) are served by
+  Vercel's global CDN.
+- **API** (`api/index.ts`) runs as a Vercel Serverless Function that
+  bootstraps the ObjectStack Kernel on cold-start, then handles requests
+  via the Hono adapter (`@hono/node-server/vercel`).
+
+### Files
+
+| File | Purpose |
+|---|---|
+| `vercel.json` | Build command, output directory, rewrites, function config |
+| `api/index.ts` | Serverless function — kernel bootstrap + Hono handler |
+| `apps/web/vite.config.ts` | Sets `base: '/'` when `VERCEL` env is detected |
+
+### Build Flow
+
+```
+pnpm run build:vercel
+  └─ turbo run build          # Builds packages → apps (dependency order)
+       ├─ packages/*/dist     # Server plugins (tsup)
+       ├─ apps/web/dist       # Admin Console (Vite)
+       └─ apps/site/out       # Docs (Next.js static export)
+  └─ cp -r apps/site/out apps/web/dist/docs   # Combine into single output
+```
+
+Output directory: **`apps/web/dist`** (includes `docs/` subfolder)
+
+### URL Routing on Vercel
+
+| URL Pattern | Destination | Type |
+|---|---|---|
+| `/api/v1/*` | `api/index.ts` serverless function | Rewrite |
+| `/docs/*` | Static files from `apps/web/dist/docs/` | CDN |
+| `/*` (other) | `index.html` (SPA fallback) | Rewrite |
+
+### Vercel Setup
+
+1. **Import the repository** in the Vercel dashboard
+2. **Framework Preset**: Other (not Next.js — this is a monorepo)
+3. Vercel auto-detects `vercel.json` and applies the configuration
+4. Push to the connected branch to trigger a deployment
+
+### Key Differences from Self-Hosted
+
+| Aspect | Self-Hosted (`pnpm start`) | Vercel |
+|---|---|---|
+| API runtime | Long-running Node.js process | Serverless function (cold-start) |
+| Static assets | Served by Hono static mounts | Served by Vercel CDN (Edge) |
+| SPA base path | `/console/` | `/` (root) |
+| Docs path | `/docs/` (static mount) | `/docs/` (CDN subfolder) |
+| WebSocket | Supported (`@objectos/realtime`) | Not supported (Vercel limitation) |
+| Background Jobs | In-process queues | Limited by function timeout (30s) |
+
+### Limitations on Vercel
+
+- **No WebSocket support** — `@objectos/realtime` requires a persistent
+  connection. Use a separate WebSocket provider (e.g., Ably, Pusher) or
+  self-host for realtime features.
+- **Cold-start latency** — The kernel bootstraps on first request to a
+  serverless function instance. Subsequent requests reuse the warm instance.
+- **Function timeout** — Default 30 seconds (`maxDuration` in `vercel.json`).
+  Long-running workflows or jobs should use external queues.
+- **No filesystem persistence** — Use external databases (PostgreSQL, MongoDB)
+  instead of SQLite. The default `InMemoryDriver` works for demos but data
+  is lost on cold-start.
+
+---
+
+## Summary: Where is `dist`?
+
+```
+objectos/
+├── apps/
+│   ├── web/
+│   │   └── dist/          ← Admin Console (Vite SPA)
+│   │       ├── index.html
+│   │       ├── assets/
+│   │       └── docs/      ← (Vercel only: copied from apps/site/out)
+│   └── site/
+│       └── out/           ← Documentation (Next.js static export)
+└── packages/
+    ├── audit/dist/        ← @objectos/audit plugin
+    ├── workflow/dist/     ← @objectos/workflow plugin
+    ├── ...                ← (all other packages)
+    └── ui/dist/           ← @objectos/ui plugin
+```

README.md

@@ -214,20 +214,27 @@ with API proxy to ObjectStack at `:5320`.
 ### Production
 
 ```bash
-# Build frontend assets
-pnpm web:build
-pnpm site:build
+# Build all packages and apps
+pnpm build
 
 # Start single-process server
 # Serves API + /console (SPA) + /docs (static)
 pnpm start
 ```
 
+### Deploy to Vercel
+
+The project includes `vercel.json` and `api/index.ts` for Vercel deployment.
+Static assets are served from CDN; the API runs as a serverless function.
+
+See [Deployment Guide](./DEPLOYMENT.md) for full details.
+
 ---
 
 ## Documentation
 
 - [Architecture Guide](./ARCHITECTURE.md)
+- [Deployment Guide](./DEPLOYMENT.md)
 - [Development Plan](./DEVELOPMENT_PLAN.md)
 - [Contributing Guide](./CONTRIBUTING.md)
 

package.json

@@ -20,6 +20,7 @@
     "dev:all": "concurrently -n api,web,site -c blue,green,yellow \"pnpm objectstack:serve\" \"pnpm web:dev\" \"pnpm site:dev\"",
     "start": "pnpm objectstack:serve",
     "build": "turbo run build",
+    "build:vercel": "turbo run build && cp -r apps/site/out apps/web/dist/docs",
     "test": "turbo run test --concurrency=3",
     "lint": "turbo run lint",
     "clean": "turbo run clean",

vercel.json

@@ -1,16 +1,17 @@
 {
   "$schema": "https://openapi.vercel.sh/vercel.json",
-  "buildCommand": "pnpm run build",
+  "buildCommand": "pnpm run build:vercel",
   "outputDirectory": "apps/web/dist",
   "installCommand": "pnpm install --no-frozen-lockfile",
   "framework": null,
+  "cleanUrls": true,
   "functions": {
     "api/**/*.ts": {
       "maxDuration": 30
     }
   },
   "rewrites": [
     { "source": "/api/v1/(.*)", "destination": "/api" },
-    { "source": "/((?!api/).*)", "destination": "/index.html" }
+    { "source": "/((?!api/|docs/).*)", "destination": "/index.html" }
   ]
 }