From 37abc7417629b1faa15a030808e0596093a3efe9 Mon Sep 17 00:00:00 2001 From: Abhay Goudannavar Date: Fri, 12 Jun 2026 14:49:25 +0000 Subject: [PATCH 1/2] docs: add WSL2 setup tutorial Add a tutorial describing how to set up and run urunc on WSL2, covering KVM verification, snapshotter configuration (overlayfs), and nerdctl/Docker usage. The blockfile snapshotter was tested and confirmed not to work on WSL2 (containerd skips it with 'no scratch file generator' error), so only overlayfs is recommended. Refs: #643 Signed-off-by: Abhay Goudannavar --- docs/tutorials/Running-urunc-on-wsl2.md | 94 +++++++++++++++++++++++++ docs/tutorials/index.md | 1 + 2 files changed, 95 insertions(+) create mode 100644 docs/tutorials/Running-urunc-on-wsl2.md diff --git a/docs/tutorials/Running-urunc-on-wsl2.md b/docs/tutorials/Running-urunc-on-wsl2.md new file mode 100644 index 000000000..cd1a964bf --- /dev/null +++ b/docs/tutorials/Running-urunc-on-wsl2.md @@ -0,0 +1,94 @@ +# Running `urunc` on WSL2 + +In this tutorial, we describe how to set up and run `urunc` on +**Windows Subsystem for Linux 2 (WSL2)**. + +## Prerequisites + +Before proceeding, make sure you have a working WSL2 instance with +Ubuntu installed. You can follow the official +[Microsoft WSL documentation](https://learn.microsoft.com/en-us/windows/wsl/install) +to set this up. + +### Verify KVM support + +Some of `urunc` supported monitors require KVM for +hardware-accelerated virtualization. On WSL2, KVM is available only if +nested virtualization is enabled on your Windows host. + +Verify that `/dev/kvm` exists: +```bash +ls -la /dev/kvm +``` + +If the device is missing, enable nested virtualization by creating or +editing the `.wslconfig` file at `%USERPROFILE%\.wslconfig` on your +Windows host: +```ini +[wsl2] +nestedVirtualization=true +``` + +Then restart WSL from PowerShell: +```powershell +wsl --shutdown +``` + +After restarting, verify KVM is available: +```bash +lsmod | grep kvm +``` + +You should see `kvm_intel` or `kvm_amd` in the output. + +## Install `urunc` + +Follow the standard [installation guide](../installation.md) to build +and install `urunc` and the containerd shim. + +## Snapshotter configuration + +The default WSL2 kernel does not load the `dm_thin_pool` kernel module, +which means the `devmapper` snapshotter will not work out of the box. + +Verify this by running: +```bash +lsmod | grep dm_thin +``` + +If the output is empty, you can use the `overlayfs` snapshotter instead, +which works without any additional configuration on WSL2. + +When running containers, use the `--snapshotter overlayfs` flag: +```bash +sudo nerdctl run --snapshotter overlayfs --runtime io.containerd.urunc.v2 ... +``` + +## Using `nerdctl` or Docker + +You can use either `nerdctl` or Docker to run containers with `urunc`. +An installation of Docker inside the WSL2 Ubuntu instance works fine. +Alternatively, you can use standalone `nerdctl` with a manually +configured containerd. + +To install `nerdctl`, follow the official +[nerdctl documentation](https://github.com/containerd/nerdctl#install). + +## Running a unikernel + +Once everything is set up, you can run a unikernel container. For +example, to run the Unikraft nginx image with QEMU: + +```bash +sudo nerdctl run --rm --snapshotter overlayfs \ + --runtime io.containerd.urunc.v2 \ + harbor.nbfc.io/nubificus/urunc/nginx-qemu-unikraft:latest +``` + +To verify the unikernel is running, check its IP address from the +`nerdctl` output and send a request: +```bash +curl http:// +``` + +You should see the default nginx welcome page. diff --git a/docs/tutorials/index.md b/docs/tutorials/index.md index 9f8ddfa86..329d89d85 100644 --- a/docs/tutorials/index.md +++ b/docs/tutorials/index.md @@ -8,3 +8,4 @@ In this section we include some end-to-end tutorials on deploying - [Running existing containers over Linux](../tutorials/existing-container-linux) - [Running vAccel-enabled Containers with `urunc`](../tutorials/Running-vaccel-with-urunc.md) - [Running `urunc` with kind](../tutorials/Running-urunc-with-kind) +- [Running `urunc` on WSL2](../tutorials/Running-urunc-on-wsl2.md) From c057df46d996beed1d9fdad2ec4f343c3bc167ee Mon Sep 17 00:00:00 2001 From: Abhay Goudannavar Date: Wed, 12 Aug 2026 18:25:30 +0000 Subject: [PATCH 2/2] fix(docs): use correct nginx-qemu-unikraft-initrd image The image nginx-qemu-unikraft:latest does not exist in the registry. Use nginx-qemu-unikraft-initrd:latest which is the correct image, consistent with the rest of the documentation and compatible with the overlayfs snapshotter on WSL2. --- docs/tutorials/Running-urunc-on-wsl2.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/tutorials/Running-urunc-on-wsl2.md b/docs/tutorials/Running-urunc-on-wsl2.md index cd1a964bf..2e1320432 100644 --- a/docs/tutorials/Running-urunc-on-wsl2.md +++ b/docs/tutorials/Running-urunc-on-wsl2.md @@ -82,7 +82,7 @@ example, to run the Unikraft nginx image with QEMU: ```bash sudo nerdctl run --rm --snapshotter overlayfs \ --runtime io.containerd.urunc.v2 \ - harbor.nbfc.io/nubificus/urunc/nginx-qemu-unikraft:latest + harbor.nbfc.io/nubificus/urunc/nginx-qemu-unikraft-initrd:latest ``` To verify the unikernel is running, check its IP address from the