From 159b044713860793fcaa3621b684a8e4afec2274 Mon Sep 17 00:00:00 2001
From: Hyu <chenhyudada@gmail.com>
Date: Tue, 15 Sep 2026 21:11:59 +0800
Subject: [PATCH] docs: add concise beta Docker and uvx deployment instructions
 (#132)

Co-authored-by: dadachann <185672915+dadachann@users.noreply.github.com>
---
 en/deploy/langbot/docker.mdx          |  9 ++++++
 en/deploy/langbot/package.mdx         |  8 +++++
 ja/deploy/langbot/docker.mdx          |  9 ++++++
 ja/deploy/langbot/package.mdx         |  8 +++++
 tests/fumapress-static-build.test.mjs | 26 +++++++++++++++++
 tests/test_beta_deployment.py         | 42 +++++++++++++++++++++++++++
 tests/test_docker_deployment_flow.py  |  4 +--
 zh/deploy/langbot/docker.mdx          |  9 ++++++
 zh/deploy/langbot/package.mdx         |  8 +++++
 9 files changed, 121 insertions(+), 2 deletions(-)
 create mode 100644 tests/test_beta_deployment.py

diff --git a/en/deploy/langbot/docker.mdx b/en/deploy/langbot/docker.mdx
index 1e41a1c83..b13b8ba08 100644
--- a/en/deploy/langbot/docker.mdx
+++ b/en/deploy/langbot/docker.mdx
@@ -50,3 +50,12 @@ The first startup downloads the container images. On Windows / macOS, keep Docke
 - **Server installation**: open `http://YOUR_SERVER_IP:5300` and make sure the firewall allows your device to access this port.
 
 Follow the on-screen initialization steps, then add a [model](/en/usage/models/readme) and a [bot](/en/usage/platforms/readme).
+
+## Beta releases (optional)
+
+To try a beta instead of the stable setup above, download the [dev/4.11.x Compose file](https://raw.githubusercontent.com/langbot-app/LangBot/dev/4.11.x/docker/docker-compose.yaml) as `compose.yaml` in a separate writable directory. Manually change **every** `rockchin/langbot` image to `rockchin/langbot:beta`: Core (`langbot`), plugin runtime (`langbot_plugin_runtime`), and Box (`langbot_box`, when present). The `beta` tag is updated with every beta release. From that directory, start or update with:
+
+```bash
+docker compose --profile all pull
+docker compose --profile all up -d
+```
diff --git a/en/deploy/langbot/package.mdx b/en/deploy/langbot/package.mdx
index 9d2ea5e88..6d8e063f3 100644
--- a/en/deploy/langbot/package.mdx
+++ b/en/deploy/langbot/package.mdx
@@ -15,6 +15,14 @@ uvx langbot@latest
 
 This will set the current directory as the working directory, and you can access `http://localhost:5300` to start using it.
 
+## Beta releases (optional)
+
+To try Beta 3 instead, use the command below. `--prerelease=allow` also permits prereleases of dependencies; `--refresh` refreshes cached package data.
+
+```bash
+uvx --prerelease=allow --refresh langbot==4.11.0b3
+```
+
 ## Optional SeekDB support
 
 The default installation uses Chroma and does not include the SeekDB Python
diff --git a/ja/deploy/langbot/docker.mdx b/ja/deploy/langbot/docker.mdx
index 9d7740a20..964799c7c 100644
--- a/ja/deploy/langbot/docker.mdx
+++ b/ja/deploy/langbot/docker.mdx
@@ -50,3 +50,12 @@ docker compose --profile all up -d
 - **サーバーにインストールした場合**：`http://サーバーのIP:5300` を開きます。ファイアウォールで自分の端末からこのポートへのアクセスを許可してください。
 
 画面の案内に従って初期設定を完了し、[モデル](/ja/usage/models/readme)と[ボット](/ja/usage/platforms/readme)を追加してください。
+
+## Beta 版（任意）
+
+上記の安定版の代わりに Beta を試す場合は、[dev/4.11.x の Compose ファイル](https://raw.githubusercontent.com/langbot-app/LangBot/dev/4.11.x/docker/docker-compose.yaml)を別の書き込み可能なディレクトリに `compose.yaml` として保存します。**すべての** `rockchin/langbot` イメージを手動で `rockchin/langbot:beta` に変更してください。対象は Core（`langbot`）、プラグインランタイム（`langbot_plugin_runtime`）、Box（`langbot_box` がある場合）です。`beta` タグは Beta リリースごとに更新されます。そのディレクトリで次を実行して起動・更新します：
+
+```bash
+docker compose --profile all pull
+docker compose --profile all up -d
+```
diff --git a/ja/deploy/langbot/package.mdx b/ja/deploy/langbot/package.mdx
index 0eed12bbe..d7f4a6f09 100644
--- a/ja/deploy/langbot/package.mdx
+++ b/ja/deploy/langbot/package.mdx
@@ -15,6 +15,14 @@ uvx langbot@latest
 
 これにより現在のディレクトリが作業ディレクトリとして設定され、`http://localhost:5300`にアクセスして使用を開始できます。
 
+## Beta 版（任意）
+
+Beta 3 を試す場合は、代わりに次のコマンドを使います。`--prerelease=allow` は依存パッケージのプレリリースも許可し、`--refresh` はキャッシュされたパッケージ情報を更新します。
+
+```bash
+uvx --prerelease=allow --refresh langbot==4.11.0b3
+```
+
 ## オプションの SeekDB サポート
 
 デフォルトのインストールでは Chroma を使用し、SeekDB の Python SDK とネイティブコンポーネントは含まれません。SeekDB をベクトルストアとして使用する場合、または組み込み埋め込みモデルを使用する場合だけ `seekdb` extra を指定します：
diff --git a/tests/fumapress-static-build.test.mjs b/tests/fumapress-static-build.test.mjs
index b2254c36e..6f46f0495 100644
--- a/tests/fumapress-static-build.test.mjs
+++ b/tests/fumapress-static-build.test.mjs
@@ -467,3 +467,29 @@ test("static search stays within Cloudflare Pages' 25 MiB file limit", async ()
   const search = await stat(path.join(publicRoot, "api/search"));
   assert.ok(search.size <= 25 * 1024 * 1024, `search artifact is ${search.size} bytes`);
 });
+
+
+test("beta deployment instructions render in all six localized deployment pages", async () => {
+  const composeUrl = "https://raw.githubusercontent.com/langbot-app/LangBot/dev/4.11.x/docker/docker-compose.yaml";
+  for (const locale of ["en", "zh", "ja"]) {
+    for (const page of ["docker", "package"]) {
+      const html = await readFile(path.join(publicRoot, locale, "deploy/langbot", page, "index.html"), "utf8");
+      const article = html.match(/<article\b[^>]*>([\s\S]*?)<\/article>/)?.[1];
+      assert.ok(article, `${locale}/${page} has a rendered article`);
+      const text = article.replace(/<[^>]+>/g, "");
+      const commands = [...article.matchAll(/<pre\b[^>]*>([\s\S]*?)<\/pre>/g)]
+        .map((match) => match[1].replace(/<[^>]+>/g, ""));
+      if (page === "docker") {
+        assert.ok(article.includes(`href="${composeUrl}"`));
+        for (const literal of ["compose.yaml", "rockchin/langbot:beta", "langbot", "langbot_plugin_runtime", "langbot_box"]) {
+          assert.ok(article.includes(`<code>${literal}</code>`), `${locale}/${page}: ${literal}`);
+        }
+        assert.ok(commands.includes("docker compose --profile all pull\ndocker compose --profile all up -d"));
+      } else {
+        assert.ok(commands.includes("uvx langbot@latest"));
+        assert.ok(commands.includes("uvx --prerelease=allow --refresh langbot==4.11.0b3"));
+      }
+      assert.ok(text.includes("Beta"), `${locale}/${page} keeps the opt-in heading`);
+    }
+  }
+});
diff --git a/tests/test_beta_deployment.py b/tests/test_beta_deployment.py
new file mode 100644
index 000000000..eb8826465
--- /dev/null
+++ b/tests/test_beta_deployment.py
@@ -0,0 +1,42 @@
+"""Keep beta deployment opt-in and consistent across maintained locales."""
+import re
+import unittest
+from pathlib import Path
+
+ROOT = Path(__file__).resolve().parents[1]
+LOCALES = ("zh", "en", "ja")
+COMPOSE_URL = "https://raw.githubusercontent.com/langbot-app/LangBot/dev/4.11.x/docker/docker-compose.yaml"
+BETA_UVX = "uvx --prerelease=allow --refresh langbot==4.11.0b3"
+
+
+class BetaDeploymentTests(unittest.TestCase):
+    def test_docker_beta_covers_all_shared_image_services(self):
+        for locale in LOCALES:
+            with self.subTest(locale=locale):
+                text = (ROOT / locale / "deploy/langbot/docker.mdx").read_text()
+                stable, beta = re.split(r"^## Beta[^\n]*\n", text, maxsplit=1, flags=re.MULTILINE)
+                self.assertIn("git clone https://github.com/langbot-app/LangBot\ncd LangBot/docker", stable)
+                self.assertNotIn("dev/4.11.x", stable)
+                self.assertNotIn("rockchin/langbot:beta", stable)
+                self.assertIn(COMPOSE_URL, beta)
+                self.assertIn("`compose.yaml`", beta)
+                self.assertIn("`rockchin/langbot:beta`", beta)
+                for service in ("langbot", "langbot_plugin_runtime", "langbot_box"):
+                    self.assertIn(f"`{service}`", beta)
+                self.assertIn("docker compose --profile all pull\ndocker compose --profile all up -d", beta)
+                self.assertLess(beta.index(COMPOSE_URL), beta.index("`rockchin/langbot:beta`"))
+                self.assertLess(beta.index("`rockchin/langbot:beta`"), beta.index("docker compose --profile all pull"))
+
+    def test_uvx_beta_allows_transitive_prereleases_and_refreshes(self):
+        for locale in LOCALES:
+            with self.subTest(locale=locale):
+                text = (ROOT / locale / "deploy/langbot/package.mdx").read_text()
+                self.assertIn("```bash\nuvx langbot@latest\n```", text)
+                self.assertIn(f"```bash\n{BETA_UVX}\n```", text)
+                self.assertIn("`--prerelease=allow`", text)
+                self.assertIn("`--refresh`", text)
+                self.assertEqual(text.count(BETA_UVX), 1)
+
+
+if __name__ == "__main__":
+    unittest.main()
diff --git a/tests/test_docker_deployment_flow.py b/tests/test_docker_deployment_flow.py
index 44ed6213a..07f1a290d 100644
--- a/tests/test_docker_deployment_flow.py
+++ b/tests/test_docker_deployment_flow.py
@@ -10,7 +10,7 @@ class DockerDeploymentFlowTests(unittest.TestCase):
     def test_all_locales_follow_one_setup_path(self):
         for locale in ("zh", "en", "ja"):
             with self.subTest(locale=locale):
-                text = (ROOT / locale / "deploy/langbot/docker.mdx").read_text()
+                text = (ROOT / locale / "deploy/langbot/docker.mdx").read_text().split("\n## Beta", 1)[0]
                 headings = re.findall(r"^## (\d+)\. .+$", text, re.MULTILINE)
                 self.assertEqual(headings, ["1", "2", "3", "4"])
                 download = "git clone https://github.com/langbot-app/LangBot\ncd LangBot/docker"
@@ -29,7 +29,7 @@ class DockerDeploymentFlowTests(unittest.TestCase):
     def test_common_commands_are_editable_and_not_linux_only(self):
         for locale in ("zh", "en", "ja"):
             with self.subTest(locale=locale):
-                text = (ROOT / locale / "deploy/langbot/docker.mdx").read_text()
+                text = (ROOT / locale / "deploy/langbot/docker.mdx").read_text().split("\n## Beta", 1)[0]
                 for platform in ("Windows", "macOS", "Linux", "PowerShell", "Docker Desktop"):
                     self.assertIn(platform, text)
                 commands = re.findall(r"```bash\n(.*?)\n```", text, re.DOTALL)
diff --git a/zh/deploy/langbot/docker.mdx b/zh/deploy/langbot/docker.mdx
index be5178f1c..5d624ab65 100644
--- a/zh/deploy/langbot/docker.mdx
+++ b/zh/deploy/langbot/docker.mdx
@@ -50,3 +50,12 @@ docker compose --profile all up -d
 - **服务器部署**：打开 `http://你的服务器IP:5300`，确保防火墙允许你的设备访问该端口。
 
 按照页面提示完成初始化，再添加[模型](/zh/usage/models/readme)和[机器人](/zh/usage/platforms/readme)。
+
+## Beta 版本（可选）
+
+如需试用 Beta 而非上述稳定版，请将 [dev/4.11.x 的 Compose 文件](https://raw.githubusercontent.com/langbot-app/LangBot/dev/4.11.x/docker/docker-compose.yaml)下载为 `compose.yaml`，保存到单独的可写目录。手动将**所有** `rockchin/langbot` 镜像改为 `rockchin/langbot:beta`：包括 Core（`langbot`）、插件运行时（`langbot_plugin_runtime`）和 Box（`langbot_box`，若存在）。每次发布 Beta 都会更新 `beta` 标签。在该目录执行以下命令启动或更新：
+
+```bash
+docker compose --profile all pull
+docker compose --profile all up -d
+```
diff --git a/zh/deploy/langbot/package.mdx b/zh/deploy/langbot/package.mdx
index 118e549ef..71fa0be6c 100644
--- a/zh/deploy/langbot/package.mdx
+++ b/zh/deploy/langbot/package.mdx
@@ -15,6 +15,14 @@ uvx langbot@latest
 
 这将把该目录作为工作目录，访问 `http://localhost:5300` 即可开始使用。
 
+## Beta 版本（可选）
+
+如需试用 Beta 3，改用以下命令。`--prerelease=allow` 同时允许依赖包的预发布版本，`--refresh` 刷新缓存的包数据。
+
+```bash
+uvx --prerelease=allow --refresh langbot==4.11.0b3
+```
+
 ## 可选的 SeekDB 支持
 
 默认安装使用 Chroma，不包含 SeekDB 的 Python SDK 和原生组件。只有在需要将