Skip to content

docs: add cloud server install guide, platform support and a Chinese deployment guide - #163

Open
newexploreor wants to merge 5 commits into
mainfrom
docs/readme-cloud-install
Open

newexploreor wants to merge 5 commits into
mainfrom
docs/readme-cloud-install

Conversation

@newexploreor

@newexploreor newexploreor commented Nov 10, 2026 •

Copy link
Copy Markdown
Collaborator

What changed

New users deploying to a cloud server had no step-by-step path in the README, and two common problems were undocumented: Windows is not supported, and some mainland China cloud hosts clone from GitHub so slowly that conversation workspaces fail to open.

Both README.md and README.zh-CN.md (Quick start) now:

  • State platform support: macOS and Linux; Windows is not supported yet.
  • Add Install on a cloud server: server and disk recommendation, security group (22/8090, restrict 8090 to your IP until the admin exists), logging in (root password login is often disabled by providers), install commands, creating the administrator, and turning off self sign-up for team-only installs.
  • Add collapsible sections for HTTPS with a domain (Caddy + AGENTFLOW_SECURE_COOKIES=true) and upgrades and backups (git pull && ./start.sh, manual migrations/, a mysqldump command).
  • Note that some mainland China cloud hosts clone from GitHub slowly, link to the existing slow-network settings, and say that faster options (CNB, a mirror repository) are planned.
  • Add docs/deployment.zh-CN.md, a Chinese translation of the deployment guide with the same sections. The Chinese README and docs/local/usage.zh-CN.md previously linked to the English-only guide; their links and anchors now point to the Chinese guide, and both guides have a language switch.

Scope

  • Platform core / API / runner
  • Public adapter / deployment
  • Classic
  • Portable
  • Shared behavior contract
  • Installer / CLI
  • Documentation only

Compatibility

Documentation only; no behavior change.

Validation

python3 scripts/check-public.py   # passed
bash scripts/scan-secrets.sh      # not run: the downloaded gitleaks binary cannot execute on this macOS host; CI runs it

Checked against the code: the release workflow publishes linux/amd64,linux/arm64; the MySQL container exposes MYSQL_ROOT_PASSWORD and the database is loopforge; new installs write LOOPFORGE_IMAGE='' to .env, so git pull && ./start.sh moves to the newly pinned image; .env changes take effect by re-running ./start.sh; the English anchor docs/deployment.md#slow-networks-clone-and-image-build-limits exists, and every docs/deployment.zh-CN.md#… anchor in the Chinese README matches a heading slug generated by github-slugger (the slugger GitHub uses). The Chinese guide has the same 11 headings and 8 code blocks as the English one.

Safety

  • I did not include credentials, internal endpoints, production data, or organization-specific infrastructure.
  • I preserved user files and unrelated changes.
  • I updated generated Classic host bundles when applicable.
  • I documented third-party content and licensing changes when applicable.

Document supported platforms (macOS and Linux; Windows not yet), a
step-by-step cloud server install with HTTPS, upgrades and backups, and
a note on slow GitHub access from mainland China cloud hosts.
@Robert0622

Copy link
Copy Markdown
Collaborator

LoopForge PR Review — head a394f9e755b0f16e0301caa810ecd34c80e7391f
Verdict: ✅ Pass

  • Docs-only change (README.md, README.zh-CN.md): platform support note, a step-by-step cloud-server install guide, collapsible HTTPS/Caddy and upgrade/backup sections, and a mainland-China slow-clone note. No behavior change.
  • Checked out the head SHA in an isolated sandbox (no secrets/no prod access) and ran python3 scripts/check-public.py — passed ("Public content check passed").
  • Verified the referenced identifiers are accurate: AGENTFLOW_ALLOW_SIGNUP is a real env var read in internal/httpapi/auth_register.go; the docs/deployment.md#slow-networks-clone-and-image-build-limits anchor matches the existing ### Slow networks: clone and image build limits heading.
  • All 15 CI checks on this SHA are green (platform-required, e2e-required, e2e matrix, browser, validate, first-run, curl-install, secrets, tcmcp, core, opensource scan).
  • No blocking issues found.

The Chinese README and Local usage guide linked to the English-only
deployment guide. Add docs/deployment.zh-CN.md with the same sections,
add language switches, and point Chinese links and anchors to it.
@newexploreor newexploreor changed the title docs(readme): add cloud server install guide and platform support docs: add cloud server install guide, platform support and a Chinese deployment guide Nov 11, 2026
@Robert0622

Copy link
Copy Markdown
Collaborator

LoopForge PR Review — head bf1603ead05e090110a97a90364e58769eec4f8f

Verdict: ✅ Pass

  • Re-review: head moved from a394f9e755b0f16e0301caa810ecd34c80e7391f (previously Pass) to bf1603ead05e090110a97a90364e58769eec4f8f. Diffed the two versions directly: this increment adds the new docs/deployment.zh-CN.md (Chinese translation of the deployment guide, 150 lines) plus a reciprocal "English | 简体中文" language switcher in docs/deployment.md, and repoints every docs/deployment.md reference in README.zh-CN.md and docs/local/usage.zh-CN.md to the new Chinese file (including anchored links). No code or English README changes on top of the previously reviewed version.
  • Checked out the head SHA in an isolated sandbox (no secrets/no prod access) and verified the new/changed links resolve: docs/deployment.zh-CN.md exists, and all three anchored references in README.zh-CN.md match actual headings in the new file — #worker-与执行机器 → ## Worker 与执行机器, #账号 → ## 账号 (used twice), #慢网络下的克隆与镜像构建限制 → ### 慢网络下的克隆与镜像构建限制.
  • Ran python3 scripts/check-public.py → passed ("Public content check passed").
  • All 16 CI checks on this SHA are green (platform-required, e2e-required, e2e matrix × 4, e2e-browser, browser, first-run, validate × 2, curl-install, secrets, tcmcp, core, opensource scan).
  • Docs-only change, no behavior impact. No blocking issues found.

cocofhu and others added 3 commits November 13, 2026 20:50
Take main's Quick start, executor table and remote-host notes, and keep
only this branch's macOS/Linux support statement, so the docs do not
regress the executor credentials table.

Co-Authored-By: Claude Code <noreply@anthropic.com>
Merging main took main's README wholesale and dropped the cloud-server
install chapter added by this PR. Re-add it after the GitLab/SSH
paragraph, keeping main's Quick start, executor table and Go version
lines as the review asked.

Co-Authored-By: Claude Code <noreply@anthropic.com>
Upgrade by checking out a release tag and running ./start.sh pull instead
of git pull, which fails on a tag checkout and can drift from the pinned
image on main. Point README.zh-CN and the Local usage guide back to the
English deployment guide until the Chinese translation is synced, and mark
the translation as out of date.

Co-Authored-By: Claude Code <noreply@anthropic.com>
@Robert0622

Copy link
Copy Markdown
Collaborator

LoopForge PR Review - head 33f22b969569662d85c403215a64a3401d05e880

Verdict: Pass

  • Re-review: head moved from bf1603ead05e090110a97a90364e58769eec4f8f (previously Pass) to 33f22b969569662d85c403215a64a3401d05e880. Two new real commits, verified directly:
    • c9339ba: restores the "Install on a cloud server" section (README.md / README.zh-CN.md, +130 lines) that an earlier merge from main had dropped.
    • 33f22b9: rewrites the upgrade steps to check out a release tag + run ./start.sh pull instead of git pull (which fails on a detached-HEAD tag checkout and can drift from the pinned image on main), and repoints the Chinese docs' stale anchors back to the English deployment guide with an out-of-date notice.
  • Checked out the head SHA in an isolated, credential-free sandbox and confirmed the claims are accurate: ./start.sh does have a pull subcommand (lines 41-51); docs/deployment.md does have the #container-installation (line 24) and #which-migrations-an-upgrade-needs (line 144) anchors the new links point to; python3 scripts/check-public.py passes on this head ("Public content check passed").
  • GitHub CI: 16/16 required checks green on this head.
  • No blocking issues found.

@Yanami-2K Yanami-2K left a comment

Copy link
Copy Markdown
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

云服务器安装步骤本身很有价值,但以下几点需要先处理:

  1. 中文部署指南是已知过时的版本 docs/deployment.zh-CN.md 开头自己写了“本译文基于较早版本的英文指南,尚未同步…当前镜像版本、升级步骤、MIRROR、Git SSH、升级需要哪些迁移”,但本 PR 同时把 README.zh-CN.md 和 docs/local/usage.zh-CN.md 原本指向英文指南的链接改到了这份译文。中文用户会拿到缺步骤的说明。这也和 PR 描述里“中文指南与英文指南有相同的 11 个标题和 8 个代码块”不一致。建议二选一:把译文完整同步到当前英文版;或者本 PR 先不改链接、不加译文。
  2. 升级文档与 #188 重叠 README.md/README.zh-CN.md 新增的“升级与备份”折叠段,和 #188 写进两份 README 及 docs/deployment.md 的升级说明是同一主题、同一位置。请等 #188 合入后 rebase,升级步骤只保留一份,其他地方链接过去,避免两处描述不一致。另外,PR 描述写的升级方式是 git pull && ./start.sh,但 README 内容要求“不要用 git pull”,请同步更新描述。
  3. 与其他打开的 PR 冲突 第 74 行“Runs on macOS and Linux; Windows is not supported for server deployment yet”:
    • #200(同一作者)在同一段 Quick start 开头插入“为什么部署到云端”,两个 PR 会产生文本冲突。建议把 #200 的内容合进本 PR 的“Install on a cloud server”小节,保留本 PR、关闭 #200。
    • #172 在同一位置增加了“Windows users can use Docker Desktop and the PowerShell launchers”,和本 PR 的“Windows 暂不支持”直接矛盾。请和 #172 对齐措辞,比如“服务端部署推荐 Linux;Windows 见 docs/windows.md”,具体取决于哪个先合入。

注:README.md、README.zh-CN.md、docs/deployment.zh-CN.md 的 patch 被截断,英文 README 的 HTTPS/备份段和译文后半部分没有看全。

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

3 participants