Skip to content

Add documentation for --no-docker parameter requirements (#715) #783

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
NJX-njx wants to merge 1 commit into
base: main
Choose a base branch
from
+16 −1
Open

Add documentation for --no-docker parameter requirements (#715) #783

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
2 changes: 1 addition & 1 deletion docs/cli.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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. |
Copy link

Copilot AI Mar 3, 2026

Choose a reason for hiding this comment

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

The anchor in this link (#using---no-docker-on-remote-nodes) depends on how the docs site generates heading IDs for inline-code headings. To avoid a potentially broken link, consider either (a) making the target heading plain text (no backticks) so the slug is predictable, or (b) adding an explicit heading id on the target section and linking to that stable id.

Suggested change
| `--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. |
| `--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) for details. |

Copilot uses AI. Check for mistakes.
Copy link

Copilot AI Mar 3, 2026

Choose a reason for hiding this comment

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

For readability in this table cell, consider formatting the literal error text as code (e.g., command not found) and/or shortening the row by moving the longer explanation into the linked getting-started section. Very long table cells can make the markdown harder to maintain and review.

Suggested change
| `--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. |
| `--no-docker` | `False` | Run on host directly without Docker. See [Run SuperBench - Using --no-docker on Remote Nodes](getting-started/run-superbench.md#using---no-docker-on-remote-nodes) for details on using this option with remote nodes. |

Copilot uses AI. Check for mistakes.
| `--output-dir` | `None` | Path to output directory, outputs/{datetime} will be used if not specified. |
| `--private-key` | `None` | Path to private key if needed. |

Expand Down
15 changes: 15 additions & 0 deletions docs/getting-started/run-superbench.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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.
Copy link

Copilot AI Mar 3, 2026

Choose a reason for hiding this comment

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

"Option C" suggests running sb deploy and then extracting the container filesystem to run without containers. However, sb deploy itself relies on Docker on the target nodes (there is no --no-docker for deploy), so this option won’t be viable in the same environments where --no-docker is needed. Consider clarifying the prerequisite (Docker available at least for deployment/pulling) or removing this option to avoid contradicting the stated use cases.

Suggested change
- **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.
- **Option C (requires Docker on remote nodes):** If Docker is available on the remote nodes for deployment but you still want to execute benchmarks without containers, you can first use `sb deploy` to pull the image and prepare the container, then manually extract the container filesystem to the host and run subsequent `sb run --no-docker` commands against that host installation.

Copilot uses AI. Check for mistakes.

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`.
Copy link

Copilot AI Mar 3, 2026

Choose a reason for hiding this comment

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

The section label "Environment variables" is a bit misleading here: superbench.env.SB_MICRO_PATH is a SuperBench config key (used via --config-override) rather than an environment variable name. Consider rewording to clarify that users must set the SB_MICRO_PATH environment variable on each remote node (or set it via superbench.env.SB_MICRO_PATH in config overrides) so it matches the on-host installation path when using --no-docker.

Suggested change
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`.
3. **Environment configuration:** Ensure the `SB_MICRO_PATH` environment variable is set on each remote node so that it matches the on-host installation path of SuperBench micro-benchmark binaries when using `--no-docker`. Alternatively, you can set the config key `superbench.env.SB_MICRO_PATH` via `--config-override` so that SuperBench exports this environment variable for remote executions.

Copilot uses AI. Check for mistakes.

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`.
Loading