diff --git a/docs/tutorials/Running-urunc-on-wsl2.md b/docs/tutorials/Running-urunc-on-wsl2.md new file mode 100644 index 00000000..0a736c66 --- /dev/null +++ b/docs/tutorials/Running-urunc-on-wsl2.md @@ -0,0 +1,98 @@ +# Running `urunc` on WSL2 + +In this tutorial, we describe how to set up and run `urunc` on +**Windows Subsystem for Linux 2 (WSL2)** using **QEMU** as the +underlying hypervisor. + +## 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 + +`urunc` requires 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 must use the `overlayfs` snapshotter +instead. This 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` instead of Docker + +On WSL2, **Docker Desktop** manages its own containerd instance, which +makes it difficult to register custom runtimes like `urunc`. We +recommend using standalone `nerdctl` with a manually configured +containerd instead. + +Install `nerdctl` and the required CNI plugins by following the official +[nerdctl documentation](https://github.com/containerd/nerdctl#install). + +Make sure the CNI plugins (`bridge`, `portmap`, etc.) are installed +under `/opt/cni/bin/`. + +## 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 b772e570..6056c8f1 100644 --- a/docs/tutorials/index.md +++ b/docs/tutorials/index.md @@ -6,4 +6,5 @@ In this section we include some end-to-end tutorials on deploying - [Knative integration](../tutorials/knative) - [Non root monitor execution](../tutorials/Non-root-monitor-execution) - [Running existing containers over Linux](../tutorials/existing-container-linux) -- [Running vAccel-enabled Containers with `urunc`](../tutorials/Running-vaccel-with-urunc.md) \ No newline at end of file +- [Running vAccel-enabled Containers with `urunc`](../tutorials/Running-vaccel-with-urunc.md) +- [Running `urunc` on WSL2](../tutorials/Running-urunc-on-wsl2.md) \ No newline at end of file