From e188d5fe798783d6d41d6d7804bc7579bc6aa28c Mon Sep 17 00:00:00 2001 From: Wayland Yang Date: Thu, 21 May 2026 13:52:45 +0800 Subject: [PATCH] docs: feature \`forkd doctor\` / \`from-image\` / \`bench\` in Quick start MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit The 3 CLI commands shipped 2026-05-21 (#134, #135, #136) collapse the new-user setup from 4 hand-pasted commands to a single \`forkd doctor\` + \`forkd from-image\` flow. Surface this prominently in Quick start so visitors landing from a Twitter / blog link see the modern story. - README.md: new \"Confirm your host is ready\" subsection leads with \`forkd doctor\`. New \"From a Docker image (one command)\" subsection shows \`forkd from-image python:3.12-slim --tag py-numpy\`. New \"Probe your install's latency\" subsection shows \`forkd bench\` with example output. - README-zh.md: parallel sections in Chinese. The original Hub-pull, from-source, and multi-child-fork-out sections are unchanged — those audiences still need them. New subsections come first since they're the most-likely user path. No code changes. Co-Authored-By: Claude Opus 4.7 (1M context) --- README-zh.md | 45 +++++++++++++++++++++++++++++++++++++++++++++ README.md | 43 ++++++++++++++++++++++++++++++++++++++++++- 2 files changed, 87 insertions(+), 1 deletion(-) diff --git a/README-zh.md b/README-zh.md index 9cd9699..ffcbe25 100644 --- a/README-zh.md +++ b/README-zh.md @@ -312,6 +312,51 @@ N=100 实测 CoW 开销是 **每个 child 0.12 MiB**(详见 [bench/](./bench/)), 要求:x86_64 Linux,带 KVM,Ubuntu 22.04 或更新。 +### 一. 确认主机环境就绪 + +```bash +pip install forkd +sudo bash scripts/setup-host.sh # KVM + tap 设备,一次性 +sudo bash scripts/netns-setup.sh 3 # 每子 VM 的网络 namespace +forkd doctor # 一键检查上面这些是否到位 +``` + +`forkd doctor` 跑 10 项检查(KVM、tap、netns、firecracker 二进制、 +内核镜像、daemon...),不通过的项目附带修复提示。任何东西觉得不对 +就先跑它。 + +### 二. 从 Docker 镜像起步(一条命令) + +`forkd from-image` 把 Docker pull → ext4 → 启动 + 暖启动 → pause → +注册 tag 串成一条命令,输出是一个你可以立刻 fork 的 tag: + +```bash +sudo -E forkd from-image python:3.12-slim \ + --tag py-numpy \ + --extra python3-numpy +# 第一次 2-3 分钟(Docker pull + ext4 + warmup),之后走缓存。 + +sudo -E forkd fork --tag py-numpy -n 5 --per-child-netns +``` + +### 三. 探测你装的 forkd 实际有多快 + +```bash +forkd bench --tag py-numpy --n 5 +# forkd bench against snapshot py-numpy +# spawn (n=1) 61 ms +# exec round-trip 22 ms +# branch (diff=true) 287 ms pause_ms=234 ... +# fanout (n=5) 65 ms 13ms/child +# cleanup 136 ms +# ----- +# total 571 ms +``` + +screenshot 友好,跑一遍能知道 v0.3 在你机器上是不是真有那个速度。 + +### 四. 从源码构建你自己的暖启动父 VM + ```bash # 1. 主机准备:KVM、Firecracker、Rust、KSM、大页、tap 设备。 sudo bash scripts/setup-host.sh diff --git a/README.md b/README.md index ea0ef47..eb64b2e 100644 --- a/README.md +++ b/README.md @@ -319,13 +319,22 @@ Measured CoW overhead at N=100 is **0.12 MiB / child** on top of the parent ([be Requires: x86_64 Linux with KVM, Ubuntu 22.04 or newer. -### Fastest path — pull a pre-built snapshot from the Hub +### Confirm your host is ready ```bash pip install forkd sudo bash scripts/setup-host.sh # KVM + tap device, one-time sudo bash scripts/netns-setup.sh 3 # per-child network namespaces +forkd doctor # green-lights everything above +``` + +`forkd doctor` runs 10 checks (KVM, tap, netns, firecracker binary, +kernel image, daemon, ...) and emits fix hints for each failure. +Run this first whenever something feels off. + +### Fastest path — pull a pre-built snapshot from the Hub +```bash # 14.5 MiB pack (a Python 3.12 + LangGraph-ready snapshot) → 15s download. forkd pull deeplethe/langgraph-react @@ -336,6 +345,38 @@ sudo -E forkd fork --tag langgraph -n 3 --per-child-netns See [`docs/HUB.md`](./docs/HUB.md) for the registry model + how to publish your own snapshot pack. +### From a Docker image (one command) + +`forkd from-image` wraps Docker pull → ext4 → boot + warmup → pause → +register tag into a single verb. The output is a tag you can +immediately fork from: + +```bash +sudo -E forkd from-image python:3.12-slim \ + --tag py-numpy \ + --extra python3-numpy +# 2-3 min the first time (Docker pull + ext4 + warmup); cached after that. + +sudo -E forkd fork --tag py-numpy -n 5 --per-child-netns +``` + +### Probe your install's latency + +```bash +forkd bench --tag py-numpy --n 5 +# forkd bench against snapshot py-numpy +# spawn (n=1) 61 ms sb-...-0027 +# exec round-trip 22 ms exit=0 +# branch (diff=true) 287 ms pause_ms=234 diff_physical_bytes=393216 +# fanout (n=5) 65 ms 13ms/child +# cleanup 136 ms +# ----- +# total 571 ms +``` + +Run this against any snapshot to see how forkd actually performs on +your hardware. Screenshot-friendly output. + ### From-source path — build your own warmed parent ```bash