docs: third-party developer onboarding and self-hosted deployment guides#2899
Merged
Conversation
… guides Evaluated the docs from an external (npm-consumer) developer's perspective: the getting-started section had no hands-on scaffold-to-API tutorial that doesn't assume an AI agent or the monorepo, and the deployment section had no self-hosting guide (only Vercel as a concrete target). - getting-started/your-first-project: scaffold via create-objectstack, generated layout and package surface, dev server, REST calls, manual model edits, validate gate, artifact build - deployment/self-hosting: systemd, Docker (multi-stage), Docker Compose with Postgres, required secrets (OS_AUTH_SECRET/OS_SECRET_KEY), health and readiness probes, reverse-proxy wiring, multi-node notes - create-objectstack README: replace stale template list (minimal-api/full-stack/plugin) with the real registry (blank + remote todo/compliance/content/contracts/procurement) and document --skip-skills and the identity-rewrite behavior - nav meta.json + cross-links from section indexes Co-Authored-By: Claude Fable 5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01Em3ky9uu6zw2cYzVhqCij2
|
The latest updates on your projects. Learn more about Vercel for GitHub.
|
github-actions
Bot
added
documentation
Contributor
📓 Docs Drift CheckThis PR changes 1 package(s): 5 hand-written doc(s) reference the affected code and may need an implementation-accuracy re-verification:
|
Co-Authored-By: Claude Fable 5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01Em3ky9uu6zw2cYzVhqCij2
…le grammar) Co-Authored-By: Claude Fable 5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01Em3ky9uu6zw2cYzVhqCij2
os-zhuang
marked this pull request as ready for review
July 14, 2026 06:36
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
2 participants
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
背景
从第三方开发者（通过 npm 使用框架、不 clone monorepo 的外部用户）的视角评估了 https://docs.objectstack.ai/docs 的现有文档，发现两个结构性缺口：
quick-start实际是"读懂元数据"（Anatomy），build-with-claude-code是 AI 优先路径，手动路径只以速览形式埋在 CLI 参考页里；也没有任何地方说明一个独立项目依赖哪些 npm 包。OS_SECRET_KEY/OS_AUTH_SECRET等容器化必设项散落在各页，健康检查端点（/api/v1/health、/api/v1/ready）未在部署文档中出现。变更
新增文档
content/docs/getting-started/your-first-project.mdx— 面向外部开发者的动手教程：npm create objectstack脚手架（含真实模板表：blank+ 远程todo/compliance/content/contracts/procurement）、生成的项目结构与依赖包说明、os dev --ui、curl 调用生成的 REST API（/api/v1/data/<object>）、手动扩展模型 +os validate门禁、os build产物。所有命令与行为均对照packages/create-objectstack/src/index.ts与 CLI 实现核实。content/docs/deployment/self-hosting.mdx— 自托管指南：必设四项（OS_DATABASE_URL/OS_AUTH_SECRET/OS_SECRET_KEY/OS_PORT）、systemd 裸机部署、多阶段 Dockerfile、Docker Compose + Postgres、liveness/readiness 探针、反向代理与OS_AUTH_URL/OS_TRUSTED_ORIGINS同步、多节点OS_CLUSTER_DRIVER注意事项，收尾链接到 Production Readiness 清单。修正
packages/create-objectstack/README.md— 原 README 列出的模板（minimal-api/full-stack/plugin）与实现不符；改为真实模板注册表，补充--skip-skills选项与身份重写（namespace 前缀替换、AGENTS.md 生成）行为说明。导航与交叉链接
meta.json加入新页面；getting-started/index.mdx与deployment/index.mdx增加指向新页的链接。验证
create-objectstack模板注册表与重写逻辑、os start的 flag/env 解析与默认 SQLite 路径（<home>/data/objectstack.db）、RESTbasePath + /v1拼接、/api/v1/health与/api/v1/ready路由、OS_AUTH_SECRET的 canonical 名称（AUTH_SECRET为兼容别名）。🤖 Generated with Claude Code
https://claude.ai/code/session_01Em3ky9uu6zw2cYzVhqCij2
Generated by Claude Code