Add WSL2 setup guide — urunc works on WSL2 but is completely undocumented [Docs]

[abhaygoudannavar]

Description

WSL2 is how most Windows developers run Linux tooling, and urunc actually works perfectly on WSL2 with KVM — but there is currently zero mention of WSL2 anywhere in the documentation.

While setting up urunc on WSL2, I went through the entire process and hit multiple undocumented blockers. After resolving them, I confirmed urunc runs unikernels successfully on WSL2 with KVM support. The docs should highlight this rather than leave users guessing.

A dedicated wsl2-setup.md (or a section in the existing installation docs) would cover:

• KVM verification on WSL2: How to confirm /dev/kvm is available (ls -la /dev/kvm) and enable nested virtualization if needed.
• Why to use nerdctl instead of Docker on WSL2: Docker Desktop on WSL2 adds its own containerd layer, making it harder to register custom runtimes. nerdctl + standalone containerd is the cleaner path.
• nerdctl + CNI plugins installation: Steps to install nerdctl and the required CNI plugins (bridge, portmap, etc.) since they don't come bundled.
• Using overlayfs instead of devmapper: The default WSL2 kernel does not load the dm_thin_pool module, so --snapshotter devmapper fails silently. overlayfs works out of the box.
• The working final command: A copy-paste-ready command that actually works on WSL2.

This is a positive story for the project — urunc works on WSL2, which expands the potential contributor base to Windows developers. The docs should reflect that.

System info

• Urunc version: main (HEAD)
• Arch: x86_64 (WSL2 on Windows 11, kernel 5.15+)
• VMM: QEMU / Firecracker
• Unikernel: Unikraft (nginx)

Steps to reproduce

1. Be a Windows developer using WSL2.
2. Follow the existing installation docs at https://urunc.io/getting-started/installation/.
3. Attempt to run the quick start command.
4. Hit dead ends at: Docker daemon configuration, devmapper unavailability, and nerdctl flag differences.
5. No documentation exists to guide you past any of these blockers.

[cmainas]

Hello @abhaygoudannavar ,

indeed that would be useful to explain how urunc can work over WSL2. However, all the steps you describe are part of the installation page. I think this sounds more like a tutorial rather than an installation guide. Maybe a better place for such document should be under tutorials.

[abhaygoudannavar]

Hi @cmainas,
You're right, framing it as a tutorial makes much more sense since it covers an end-to-end environment setup rather than just core installation.
I would love to write this tutorial and submit a PR to add it to the site. Should I add the new markdown file under the docs/content/tutorials/ directory (or wherever the tutorials are currently structured), or is there a specific format you prefer for new tutorials.

[cmainas]

You can check 1c9c720 and have as a reference. However, please simply point to the respective steps in the installation guide rather than copy paste the same snippets. It is hard to update the same snippet in various parts of the docs. I am still unsure on how such a tutorial would be though.

[abhaygoudannavar]

@cmainas
Understood completely, I agree with avoiding documentation drift. I will only use hyperlinks pointing back to the main Installation Guide for the standard steps rather than duplicating any commands.

To give you an idea of how the tutorial would look, here is the brief outline I have in mind :

1. Prerequisites & KVM: How to verify nested virtualization and KVM are enabled in the WSL2 kernel (lsmod | grep kvm).
2. Docker vs Nerdctl on Windows: A brief explanation of why standard Docker Desktop on WSL2 interferes with custom runtimes, and why standalone nerdctl is the required path.
3. Core Installation: A direct link pointing users to the urunc [Installation Guide] to perform the standard setup.

I'll check out commit 1c9c720 for the structural reference and put together a draft PR so you can see exactly how it reads.