diff --git a/docs/cli.md b/docs/cli.md index 0a73e1f33..bc43351d9 100644 --- a/docs/cli.md +++ b/docs/cli.md @@ -375,7 +375,7 @@ sb run [--config-file] | `--host-list` `-l` | `None` | Comma separated host list. | | `--host-password` | `None` | Host password or key passphrase if needed. | | `--host-username` | `None` | Host username if needed. | -| `--no-docker` | `False` | Run on host directly without Docker. | +| `--no-docker` | `False` | Run on host directly without Docker. When using remote nodes, SuperBench (`sb` binary and dependencies) must be pre-installed on each target host; otherwise `command not found` will occur. See [Run SuperBench - Using --no-docker on Remote Nodes](getting-started/run-superbench.md#using---no-docker-on-remote-nodes) for details. | | `--output-dir` | `None` | Path to output directory, outputs/{datetime} will be used if not specified. | | `--private-key` | `None` | Path to private key if needed. | diff --git a/docs/getting-started/run-superbench.md b/docs/getting-started/run-superbench.md index 0a21752b9..ce26d0def 100644 --- a/docs/getting-started/run-superbench.md +++ b/docs/getting-started/run-superbench.md @@ -47,3 +47,18 @@ You can create a privileged container with `superbench/superbench` image, skip ` `sb run --no-docker -l localhost -c resnet.yaml`. ::: + +## Using `--no-docker` on Remote Nodes + +When running `sb run` with `--no-docker` on **remote nodes** (via `--host-file` or `--host-list`), the following requirements apply: + +1. **SuperBench must be pre-installed on each remote node.** The `sb` CLI binary and its dependencies must be available in the PATH on every target host. Running without Docker means Ansible will SSH into each node and execute `sb exec` directly; if `sb` is not installed, you will see `command not found` (exit code 127). + +2. **Deployment options:** + - **Option A:** Extract the contents of the `superbench/superbench` Docker image onto each node (e.g., copy binaries, Python environment, and micro-benchmark executables to a consistent path), then ensure `sb` is in PATH. + - **Option B:** Install SuperBench from source or pip on each node, and build/install the required micro-benchmark binaries (see `third_party/` and build instructions). + - **Option C:** Use `sb deploy` first to pull the image, then manually extract the container filesystem to the host if you need to run without containers. + +3. **Environment variables:** Set `superbench.env.SB_MICRO_PATH` (and other required env vars) to match the installation path on each node when using `--no-docker`. + +4. **Use case:** `--no-docker` is intended for environments where Docker-in-Docker or nested containers are not supported (e.g., certain Kubernetes setups, HPC clusters with restricted container runtimes). For standard deployments, prefer `sb deploy` + `sb run` without `--no-docker`.