Skip to content

docs: replace stale WSL2 references with Hyper-V Linux VM for the serve path#78

Merged
luthermonson merged 1 commit into
mainfrom
docs/hyperv-update
May 25, 2026
Merged

docs: replace stale WSL2 references with Hyper-V Linux VM for the serve path#78
luthermonson merged 1 commit into
mainfrom
docs/hyperv-update

Conversation

@luthermonson
Copy link
Copy Markdown
Contributor

Why

The Linux-job dispatch worker on Windows moved from a WSL2 distro to a Hyper-V Linux VM (HCS via vmcompute.dll) at some point and the docs still described the WSL2 architecture. Spotted on https://ephemerd.ephpm.dev/guides/how-it-works/ — but the same stale framing was scattered across the architecture docs, CLI reference, and getting-started pages.

Motivation for the migration, captured in code:

// Unlike the previous WSL2 approach, this works from any Windows security context
// including LocalSystem (services), which WSL2 does not support.

pkg/vm/linuxvm_windows.go

That sentence is now in the docs too.

What's in vs. out of scope

Updated (the `serve` daemon path on Windows):

  • `docs/guides/how-it-works.md` — Windows section rewritten end-to-end (prose + Mermaid + Dual-Purpose Hosts table); plus same-page "One Image" and "Resource planning" tweaks.
  • `docs/architecture/windows-wsl-dispatch.md` — page title becomes Windows Hyper-V Dispatch, new Why a Hyper-V VM (not WSL2) section explains the LocalSystem motivation, and the lifecycle prose was rewritten (kernel + initrd + VHDX boot via HCS). Filename intentionally unchanged so existing inbound links and `{{< relref >}}` cross-references keep working; added a Hugo `aliases` entry for the old URL.
  • `docs/architecture/overview.md`, `embedded-containerd.md`, `macos-vms.md`, `multi-forge-providers.md`, `forgejo-gitea.md`, `pre-baked-rootfs.md`, `cri-passthrough.md`
  • `docs/getting-started/configuration.md`
  • `docs/cli/serve.md`
  • `docs/guides/providers.md`, `docs/guides/runner-images.md`
  • `docs/contributing/dev-setup.md`, `project-layout.md`

Intentionally NOT updated:

  • `docs/cli/run.md`, `doctor.md`, `uninstall.md` — these still mention WSL because `ephemerd run` (one-shot CLI invocation) is implemented by `pkg/vm/wslrun_windows.go` and genuinely uses a temporary WSL distro. Same for `doctor`'s WSL availability check and `uninstall`'s cleanup of `ephemerd-*` distros — both still relevant.
  • `docs/_archived/...` — explicitly archived, left as historical record.
  • `docs/arch/quickboot-image.md` — this is a forward-looking decision doc that already discusses Hyper-V as the target. Could use a status update but that's a separate edit.

Test plan

  • Hugo render check on touched pages (no broken `{{< relref >}}` links).
  • Old URL `/architecture/windows-wsl-dispatch/` still resolves via the new `aliases` frontmatter.
  • No code changes; `mage ci` not required.

Followups if you spot more drift: another wsl grep across docs/ surfaces some `run`-mode + cleanup mentions that I left in place because they're still correct — happy to revisit if the `run` command itself migrates to Hyper-V too.

…ve path

The Linux-job dispatch worker on Windows moved from a WSL2 distro to a
Hyper-V Linux VM (HCS via vmcompute.dll) some time back; the docs still
described the WSL2 architecture. The motivation, from the code comment
in pkg/vm/linuxvm_windows.go: WSL2 has no LocalSystem support, so the
installed Windows service couldn't manage WSL distros. Hyper-V Compute
Service has no such restriction.

This pass updates the user-facing pages and the architecture docs that
describe the `serve` daemon path. Specifically left alone:

  * docs/cli/run.md, doctor.md, uninstall.md still mention WSL because
    the `ephemerd run` one-shot CLI uses pkg/vm/wslrun_windows.go,
    which is genuinely a temporary WSL distro and hasn't migrated.
  * docs/_archived/ is intentionally archived and stays as-is.

Updates by file:

  docs/guides/how-it-works.md
    Windows section rewritten end-to-end (prose + Mermaid + Dual-Purpose
    Hosts table); same-page "One Image, Every Host" and "Resource
    planning" tweaks.

  docs/architecture/windows-wsl-dispatch.md
    Page title becomes "Windows Hyper-V Dispatch"; added aliases so the
    old URL keeps working. Filename intentionally unchanged to keep
    inbound links + the {{< relref >}} cross-references valid. Body
    rewritten — added "Why a Hyper-V VM (not WSL2)" section explaining
    the LocalSystem motivation. Old WSL-specific lifecycle replaced
    with the Hyper-V Compute Service / KernelDirect / VHDX flow.

  docs/architecture/overview.md
    Dual-purpose + build-matrix tables, plus the cross-link text.

  docs/architecture/embedded-containerd.md
    TCP-listener purpose + Windows-host-to-in-VM containerd note.

  docs/architecture/macos-vms.md
    "Unlike Windows WSL dispatch" → "Unlike Windows Hyper-V dispatch".

  docs/architecture/multi-forge-providers.md
    "WSL dispatch" → "Hyper-V Linux VM dispatch" in the
    provider-agnostic list.

  docs/architecture/forgejo-gitea.md
    Mermaid host subgraph label + lifecycle prose + Windows row in the
    container-runtime table.

  docs/architecture/pre-baked-rootfs.md
    Reframed: the rootfs is still pre-baked, but it goes into the
    Hyper-V VM initrd / Vz initrd. The temporary WSL distro `ephemerd
    run` creates still benefits from the same rootfs.

  docs/architecture/cri-passthrough.md
    Replaced "WSL-to-Windows" debugging tip with the in-VM equivalent
    (the WSL one-liner doesn't apply any more).

  docs/getting-started/configuration.md
    Resource-planning note + the "what does enabled: true do" sentence.

  docs/cli/serve.md
    --containerd-tcp-port / --containerd-only descriptions + the
    "wait for Linux dispatcher" startup step + the example command.

  docs/guides/providers.md, docs/guides/runner-images.md,
  docs/contributing/dev-setup.md, docs/contributing/project-layout.md
    One-line replacements.

No code changes. mage ci not required for docs-only changes; Hugo
render check passes locally on the touched pages.
@luthermonson luthermonson merged commit c2d0527 into main May 25, 2026
4 checks passed
@luthermonson luthermonson deleted the docs/hyperv-update branch May 25, 2026 22:04
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.

1 participant