# Set Up Loss Prevention on Windows 11 with WSL2 This guide takes a clean Windows 11 machine to a working Loss Prevention environment under WSL2. It is written for someone who has never used WSL before. Before `make benchmark`, also complete the [hardware metrics prerequisites](./wsl-hardware-metrics.md). Windows GPU counters, optional GPU power sensors, and native Windows Performance Counter Monitor (PCM) need separate host-side setup. Collection then starts and stops automatically with the benchmark; no separate collector command is needed during a run. See [WSL benchmark metrics](./wsl2-benchmark.md) for outputs and limitations. The Makefile detects WSL2 automatically from the Microsoft kernel; no flag is needed. Follow the steps **in order**. Several of them fail in confusing ways if done out of sequence — particularly the proxy configuration, which must come before any download. --- ## Contents 1. [Elevation and virtualization](#1-elevation-and-virtualization) 2. [Install WSL2 and Ubuntu 24.04](#2-install-wsl2-and-ubuntu-2404) 3. [Proxy configuration](#3-proxy-configuration) 4. [Base packages](#4-base-packages) 5. [Enable systemd](#5-enable-systemd) 6. [Install Docker Engine](#6-install-docker-engine) 7. [Docker daemon proxy](#7-docker-daemon-proxy) 8. [Docker build-time proxy](#8-docker-build-time-proxy) 9. [Memory and CPU tuning](#9-memory-and-cpu-tuning) 10. [Clone the repository](#10-clone-the-repository) 11. [GPU and NPU verification](#11-gpu-and-npu-verification) 12. [Smoke test](#12-smoke-test) 13. [Troubleshooting](#troubleshooting) --- ## Conventions Commands are labeled by where they run: | Label | Where | | --- | --- | | **PowerShell** | Windows PowerShell or Terminal, on the Windows side | | **Ubuntu** | Inside the WSL2 Ubuntu distribution | Getting these mixed up is the single most common early mistake. --- ## Values you must change for your site Most URLs in this guide are public upstream endpoints and are identical on every machine. A small number are **site-specific** and are the most likely reason the guide fails somewhere else. Every occurrence below is marked with a ⚙️ note. | Placeholder used here | What it is | How to find yours | | --- | --- | --- | | `http://proxy.example.com:PORT` | Example proxy URL; replace the host and port with your site's values | `netsh winhttp show proxy` or `ProxyServer` (Windows), `echo $HTTP_PROXY` (Ubuntu) | | `.example.com`, `192.0.2.0/24` | Reserved example values for the `NO_PROXY` internal domain and network range | Your own internal DNS suffix and network ranges | | PAC URL | Proxy auto-configuration file | `AutoConfigURL` (Windows), `echo $WSL_PAC_URL` (Ubuntu) | | `C:\Users\` | Windows profile path | Use `$env:USERPROFILE`, which resolves itself | **Discover everything at once.** In **PowerShell**: ```powershell netsh winhttp show proxy Get-ItemProperty "HKCU:\Software\Microsoft\Windows\CurrentVersion\Internet Settings" | Select-Object ProxyServer, AutoConfigURL ``` In **Ubuntu**, once a distribution exists: ```bash echo "$HTTP_PROXY" echo "$WSL_PAC_URL" ``` These are **constant everywhere** — never edit them: `api.github.com`, `download.docker.com`, `archive.ubuntu.com`, `github.com/intel-retail/loss-prevention`, `openvino/ubuntu24_dev`. The service names `rabbitmq`, `minio-service`, `rtsp-streamer`, `ovms-vlm`, and `model-downloader` in every `NO_PROXY` are Docker Compose service names from `src/docker-compose.yml` and must be kept as-is. --- ## 1. Elevation and virtualization WSL2 is a lightweight virtual machine. Getting it installed means satisfying three independent requirements, in this order: | Layer | What it is | How to enable | Reboot | | --- | --- | --- | --- | | **VT-x** | CPU feature, a firmware setting | BIOS/UEFI **only** | Yes, into BIOS | | **Windows features** | `VirtualMachinePlatform`, `Microsoft-Windows-Subsystem-Linux` | `dism` or `wsl --install` | Yes, normal reboot | | **WSL package** | the `wsl.exe` runtime itself | `wsl --install` download, or the MSI | No | These are **not** alternatives. `dism` cannot switch on VT-x, and enabling the Windows features while VT-x is off leaves you with a WSL that installs cleanly and then refuses to boot a distribution. ### 1a. Open an elevated PowerShell Everything in this section fails with `Error: 740 — Elevated permissions are required` from a normal shell. Select Windows **Start** menu, type `powershell`, right-click **Windows PowerShell**, and **Run as administrator**. Or from an existing window: ```powershell Start-Process powershell -Verb RunAs ``` To confirm it worked: ```powershell whoami /groups | findstr /i "High Mandatory" ``` The result must print a line containing `High Mandatory Level`. Nothing printed means the window is not elevated. > [!CAUTION] > **Remote machines:** an SSH session (MobaXterm, OpenSSH) **cannot elevate** — UAC needs > an interactive desktop to draw the consent dialog, and there is no CLI workaround. Use > **RDP**, which creates a real interactive session and supports UAC normally. If the > account is not listed by `net localgroup Administrators`, stop here. ### 1b. Point WinHTTP at the proxy An elevated shell uses the **machine's** WinHTTP proxy configuration, not your browser's, and by default that is empty. Skip this on a corporate network and the WSL downloader fails with `The certificate authority is invalid or incorrect`: ```powershell netsh winhttp import proxy source=ie netsh winhttp show proxy ``` If it still reports `Direct access (no proxy server)`, set it explicitly: ```powershell netsh winhttp set proxy proxy-server="http=proxy.example.com:PORT;https=proxy.example.com:PORT" bypass-list="*.example.com;localhost;127.0.0.1;" ``` > [!NOTE] > ⚙️ **Site-specific.** Replace `proxy.example.com:PORT` and the bypass list with your > own. Find them with: > > ```powershell > Get-ItemProperty "HKCU:\Software\Microsoft\Windows\CurrentVersion\Internet Settings" | > Select-Object ProxyServer, AutoConfigURL > ``` > > If only `AutoConfigURL` is set, open that PAC URL in a browser and read the proxy host > and port out of the JavaScript. Check the proxy actually reaches the download host before going further: ```powershell curl.exe -sS -o NUL -w "%{http_code}`n" -x http://proxy.example.com:PORT https://github.com ``` Replace the example host and `PORT` with the proxy host and port reported by your settings or PAC file. A `200` confirms the proxy reaches the destination; a `403` means it refuses that destination. ### 1c. Check firmware virtualization Run this to check virtualization: ```powershell systeminfo | findstr /i "Hyper-V" ``` | Output | Meaning | Action | | --- | --- | --- | | `A hypervisor has been detected.` | VT-x is on and a hypervisor is running | Continue to 1d | | A list ending `Virtualization Enabled In Firmware: No` | VT-x is off | Reboot into BIOS/UEFI, enable *Intel Virtualization Technology (VT-x)*, then resume here | If virtualization is off, you have to enable it in BIOS — there is no Windows command for it. ### 1d. Enable the Windows features and install the WSL package One command normally does both: ```powershell wsl.exe --install --no-distribution ``` On a corporate network this often fails at the **download** half with `The certificate authority is invalid or incorrect` or `Forbidden (403)`. The WSL downloader performs its own strict certificate validation and rejects the TLS-inspected chain, even when the corporate CA is trusted machine-wide. Retrying will not help. Split the two jobs instead. The Deployment Image Servicing and Management (DISM) tool enables the features and needs no network: ```powershell dism.exe /online /enable-feature /featurename:Microsoft-Windows-Subsystem-Linux /all /norestart dism.exe /online /enable-feature /featurename:VirtualMachinePlatform /all /norestart ``` Then fetch the package with `curl.exe`, which ships with Windows and validates against the Windows certificate store — the same store your browser uses, so the inspected chain is accepted: ```powershell $json = curl.exe -sS -x http://proxy.example.com:PORT https://api.github.com/repos/microsoft/WSL/releases/latest | ConvertFrom-Json $url = ($json.assets | Where-Object { $_.name -like '*x64.msi' }).browser_download_url $url curl.exe -L -x http://proxy.example.com:PORT -o "$env:TEMP\wsl.msi" $url (Get-Item "$env:TEMP\wsl.msi").Length msiexec /i "$env:TEMP\wsl.msi" /qn /norestart ``` Expect roughly a 100–150 MB download. A few kilobytes means you downloaded the proxy's block page rather than the installer. > [!NOTE] > ⚙️ **Site-specific.** Replace `http://proxy.example.com:PORT` with the proxy URL > confirmed in [step 1b](#1b-point-winhttp-at-the-proxy). The `api.github.com` URL is > universal, and the MSI URL is deliberately *not* hardcoded: the API query resolves the > current version's `browser_download_url`, so it stays correct as WSL releases change. Do not > replace it with a literal filename. > > --- > > `winget install --id Microsoft.WSL` is a third option. It uses yet another HTTP stack > and sometimes succeeds where both others fail. ### 1e. Reboot The feature changes do not take effect until you do: ```powershell shutdown /r /t 0 ``` ### 1f. Verify In an **elevated** shell (this query also needs it): ```powershell dism /online /get-featureinfo /featurename:VirtualMachinePlatform ``` Expected: `State : Enabled`. Then ask WSL itself: ```powershell wsl --version wsl --status ``` | `wsl --status` output | Meaning | Action | | --- | --- | --- | | `Default Version: 2` | Step 1 complete | Go to step 2 | | `The Windows Subsystem for Linux is not installed` | The [step 1d](#1d-enable-the-windows-features-and-install-the-wsl-package) download half did not succeed | Install the MSI | | `WSL2 is unable to start since virtualization is not enabled on this machine` | The **package** is installed but the **Windows features** are not | Run the command below, then reboot | | `WSL2 is not supported with your current machine configuration` | VT-x is off in firmware | See [step 1c](#1c-check-firmware-virtualization), enable in BIOS | The third row is the common one after installing via MSI. `wsl.exe` is now present and reporting on its own environment. Its full message is: ```text WSL1 is not supported with your current machine configuration. Please enable the "Windows Subsystem for Linux" optional component to use WSL1. WSL2 is unable to start since virtualization is not enabled on this machine. Please ensure the "Virtual Machine Platform" optional component is enabled and virtualization is turned on in your computer's firmware settings. ``` Because the package is already local, this command no longer needs to download anything — it only flips the two optional components, so it succeeds even on a network where 1d failed: ```powershell wsl.exe --install --no-distribution shutdown /r /t 0 ``` Re-run `wsl --status` after the reboot. It should now report `Default Version: 2`. --- ## 2. Install WSL2 and Ubuntu 24.04 **PowerShell:** ```powershell wsl --set-default-version 2 wsl --list --online wsl --install -d Ubuntu-24.04 ``` The installer prompts for a **Linux username and password**. These are independent of your Windows account. Remember the password — it is your `sudo` password. Record your version baseline: ```powershell wsl --version wsl -l -v ``` Example output: ```text WSL version: 2.7.12.0 Kernel version: 6.18.33.2-2 WSLg version: 1.0.73.2 Direct3D version: 1.611.1-81528511 Windows version: 10.0.26200.9168 ``` **Ubuntu** — confirm the distribution launched and identifies itself: ```bash lsb_release -a uname -r ``` Expected: `Ubuntu 24.04 LTS` (codename `noble`). > [!IMPORTANT] > Do **not** run `apt update` or `apt upgrade` yet. On a corporate network those will > partially fail in ways that are hard to interpret. Configure the proxy first — the > system update is the last part of step 3. Type `exit` to return to PowerShell. --- ## 3. Proxy configuration **Do this before anything else that touches the network.** On a corporate network, skipping it produces misleading failures much later. ### Why this trips people up On some networks, plain HTTP may work directly while HTTPS is blocked. Ubuntu's own package repositories may use plain HTTP, so `sudo apt update` can appear to succeed: ```text Hit:1 http://archive.ubuntu.com/ubuntu noble InRelease <-- HTTP repository succeeds Err:6 https://download.docker.com/linux/ubuntu noble InRelease <-- HTTPS repository times out Could not connect to download.docker.com:443, connection timed out ``` **A successful `apt update` does not prove your network is configured.** If you are not behind a proxy, skip to [step 4](#4-base-packages). ### 3a. Windows side — `.wslconfig` By default WSL2 uses NAT, and corporate endpoint-security agents frequently drop that traffic. Mirrored networking makes WSL share the Windows network stack directly. > [!NOTE] > **Mirrored networking requires WSL 2.0.0+ and Windows build 22621+.** > Check with `wsl --version` and `[System.Environment]::OSVersion.Version` if unsure. > On older builds, omit `networkingMode`, `dnsTunneling`, and `firewall`, and set the > proxy manually in step 3b. Create or edit `C:\Users\\.wslconfig`: ```ini [wsl2] networkingMode=mirrored dnsTunneling=true autoProxy=true firewall=true ``` > [!NOTE] > ⚙️ **Machine-specific path.** Rather than typing your username, let PowerShell resolve > it — this writes the same file on any machine: > > ```powershell > @" > [wsl2] > networkingMode=mirrored > dnsTunneling=true > autoProxy=true > firewall=true > "@ | Set-Content -Path "$env:USERPROFILE\.wslconfig" -Encoding ASCII > > Get-Content "$env:USERPROFILE\.wslconfig" > ``` > > On a remote machine this must be the profile of the account **running WSL**, not the > one you connect from. **PowerShell** — apply: ```powershell wsl --shutdown ``` **Ubuntu** — verify. The address should now match your Windows IPv4, not `172.x.x.x`: ```bash ip addr show eth0 | grep 'inet ' ``` ### 3b. Ubuntu shell — `~/.bashrc` `autoProxy=true` injects `HTTP_PROXY` but **not** `HTTPS_PROXY`. Tools like `curl` read `HTTPS_PROXY` for TLS connections, so without it they connect directly to port 443 and hang. Mirror the value: ```bash cat >> ~/.bashrc <<'EOF' # WSL autoProxy sets HTTP_PROXY but not HTTPS_PROXY - mirror it if [ -n "$HTTP_PROXY" ]; then export HTTPS_PROXY="${HTTPS_PROXY:-$HTTP_PROXY}" export http_proxy="$HTTP_PROXY" export https_proxy="$HTTPS_PROXY" export NO_PROXY="localhost,127.0.0.1,::1,.example.com,192.0.2.0/24,rabbitmq,minio-service,rtsp-streamer,ovms-vlm,model-downloader" export no_proxy="$NO_PROXY" fi EOF source ~/.bashrc ``` Verify: ```bash env | grep -i proxy curl -sI --max-time 15 https://download.docker.com/linux/ubuntu/gpg | head -1 ``` The `curl` must return `HTTP/1.1 200` or `HTTP/2 200`. A hang means HTTPS is still going direct. > [!NOTE] > Find your proxy URL from `echo $HTTP_PROXY`, or inspect the PAC file WSL exposes as > `$WSL_PAC_URL`. On Windows, `netsh winhttp show proxy` and the Internet Settings > `ProxyServer` and `AutoConfigURL` values show the configured proxy or PAC URL. If only > a PAC URL is available, inspect its script to find the proxy host and port. > > --- > > ⚙️ **Site-specific.** The `NO_PROXY` list above mixes two kinds of entry. Replace > `.example.com` and `192.0.2.0/24` with your own internal domain and network ranges. > Keep `rabbitmq`, `minio-service`, `rtsp-streamer`, `ovms-vlm`, and `model-downloader` — > those are Compose service names from `src/docker-compose.yml`, identical on every > machine, and routing them through a proxy breaks inter-container traffic. > Check your current values with: > > ```bash > echo "$HTTP_PROXY" > echo "$WSL_PAC_URL" > ``` ### 3c. apt — its own configuration file **`apt` does not read shell environment variables.** It needs its own file. This is separate from step 3b and both are required: ```bash sudo tee /etc/apt/apt.conf.d/95proxies > /dev/null <<'EOF' Acquire::http::Proxy "http://proxy.example.com:PORT"; Acquire::https::Proxy "http://proxy.example.com:PORT"; EOF ``` > [!NOTE] > ⚙️ **Site-specific.** Substitute your own proxy. Because the heredoc is quoted > (`<<'EOF'`), `$HTTP_PROXY` would be written literally rather than expanded — so if you > want it filled in from the environment, drop the quotes: > > ```bash > sudo tee /etc/apt/apt.conf.d/95proxies > /dev/null < Acquire::http::Proxy "$HTTP_PROXY"; > Acquire::https::Proxy "$HTTPS_PROXY"; > EOF > ``` > > Always `cat` the file afterwards to confirm real values landed, not empty strings. ### 3d. Force IPv4 WSL2 has no IPv6 route, so every apt download wastes around 30 seconds failing over eight IPv6 addresses before trying IPv4. Force IPv4 with: ```bash sudo tee /etc/apt/apt.conf.d/99force-ipv4 > /dev/null <<'EOF' Acquire::ForceIPv4 "true"; EOF ``` Verify both files: ```bash cat /etc/apt/apt.conf.d/95proxies /etc/apt/apt.conf.d/99force-ipv4 ``` ### 3e. Update the base system Only now is it safe to run this — every download path is configured: ```bash sudo apt update sudo apt upgrade -y ``` `apt update` must complete with **no `Err:` lines**. Warnings about missing repositories you have not added yet are fine; connection timeouts are not. ### The four proxy contexts Proxy settings live in four unrelated places. Configuring one tells you nothing about the others: | Context | Consumer | Location | Step | | --- | --- | --- | --- | | Shell | `curl`, `git`, `pip`, `wget` | `~/.bashrc` | [step 3b](#3b-ubuntu-shell--bashrc) | | apt | `sudo apt` | `/etc/apt/apt.conf.d/95proxies` | [step 3c](#3c-apt--its-own-configuration-file) | | Daemon | `docker pull` | `/etc/systemd/system/docker.service.d/proxy.conf` | [step 7](#7-docker-daemon-proxy) | | Build | `docker build` RUN steps | `~/.docker/config.json` | [step 8](#8-docker-build-time-proxy) | Steps 7 and 8 come later because those paths do not exist until Docker is installed. > [!CAUTION] > `sudo` strips proxy environment variables. Use `sudo -E` for any command that needs > network access. --- ## 4. Base packages ```bash sudo apt install -y \ build-essential make git curl wget unzip \ jq python3 python3-pip python3-venv \ ca-certificates gnupg lsb-release x11-xserver-utils ``` | Package | Used by | | --- | --- | | `make` | every workflow command (`make run-lp`, `make benchmark`) | | `jq` | `model-downloader.sh` and `check-device-env` parse `configs/*.json` | | `python3` + `venv` | `download-video.py`, configuration validators, benchmark scripts | | `curl` / `wget` | model and video downloads | | `git` | the repository and the `performance-tools` submodule | | `x11-xserver-utils` | `xhost`, required by `make run-render-mode` for X11 display access | Verify: ```bash make --version && jq --version && python3 --version && git --version ``` --- ## 5. Enable systemd Docker Engine runs as a systemd service. WSL2 does not enable systemd by default, so enable it in `/etc/wsl.conf`: ```bash sudo tee /etc/wsl.conf > /dev/null <<'EOF' [boot] systemd=true [interop] appendWindowsPath=true EOF ``` **PowerShell** — a full shutdown is required; closing the terminal is not enough: ```powershell wsl --shutdown ``` Reopen **Ubuntu** and verify: ```bash ps -p 1 -o comm= systemctl list-units --type=service | head ``` `ps -p 1 -o comm=` must print `systemd`. If you see `System has not been booted with systemd`, the shutdown did not take effect. --- ## 6. Install Docker Engine ### Why Docker Engine and not Docker Desktop Docker Desktop runs its daemon in a **separate hidden distribution** (`docker-desktop`), not in your Ubuntu. For the GPU work in step 11 you will bind-mount `/usr/lib/wsl/lib` and pass `--device=/dev/dxg`; cross-distribution path translation makes failures much harder to diagnose. With Docker Engine installed inside Ubuntu-24.04, the daemon sees exactly the same devices and filesystem you do. > [!CAUTION] > Do not install both. Two daemons will conflict. ### Add Docker's GPG key ```bash sudo install -m 0755 -d /etc/apt/keyrings sudo -E curl -fsSL https://download.docker.com/linux/ubuntu/gpg \ -o /etc/apt/keyrings/docker.asc sudo chmod a+r /etc/apt/keyrings/docker.asc ``` **Verify before continuing.** A timed-out `curl` leaves an empty file, and the resulting apt error is misleading: ```bash head -1 /etc/apt/keyrings/docker.asc ``` Must print `-----BEGIN PGP PUBLIC KEY BLOCK-----`. ### Add the repository and install ```bash echo "deb [arch=$(dpkg --print-architecture) signed-by=/etc/apt/keyrings/docker.asc] \ https://download.docker.com/linux/ubuntu $(. /etc/os-release && echo $VERSION_CODENAME) stable" \ | sudo tee /etc/apt/sources.list.d/docker.list > /dev/null sudo apt update sudo apt install -y docker-ce docker-ce-cli containerd.io \ docker-buildx-plugin docker-compose-plugin ``` ### Enable non-root access ```bash sudo usermod -aG docker $USER sudo systemctl enable --now docker ``` Group membership is only read at login. **PowerShell:** ```powershell wsl --shutdown ``` Reopen **Ubuntu** and confirm the group and the service. These are local checks and need no network: ```bash id -nG | tr ' ' '\n' | grep docker systemctl is-active docker ``` Expect `docker` and `active`. If the group is missing, the shutdown did not take effect. > [!CAUTION] > Do not work around permission errors with `sudo docker`. Running as root creates > root-owned files in `models/` and `results/`, which breaks later steps. The full end-to-end check comes at the end of step 8 — `docker run hello-world` has to pull an image, which cannot work until the daemon proxy is configured. --- ## 7. Docker daemon proxy Required for `docker pull`. The daemon is a system service and does not inherit your shell environment: ```bash sudo mkdir -p /etc/systemd/system/docker.service.d sudo tee /etc/systemd/system/docker.service.d/proxy.conf > /dev/null <<'EOF' [Service] Environment="HTTP_PROXY=http://proxy.example.com:PORT" Environment="HTTPS_PROXY=http://proxy.example.com:PORT" Environment="NO_PROXY=localhost,127.0.0.1,.example.com,rabbitmq,minio-service,rtsp-streamer,ovms-vlm,model-downloader" EOF sudo systemctl daemon-reload sudo systemctl restart docker ``` > [!NOTE] > ⚙️ **Site-specific.** Replace `http://proxy.example.com:PORT` and the `.example.com` > entry with your own; > keep the Compose service names. Confirm the values you are about to write first with > `echo "$HTTP_PROXY"`. Verify: ```bash docker info | grep -i proxy ``` You should see `HTTP Proxy`, `HTTPS Proxy`, and `No Proxy` lines. If they are absent, the drop-in did not load. --- ## 8. Docker build-time proxy Each `RUN` instruction in a Dockerfile executes in a throwaway container with a clean environment. It does not inherit your shell's proxy settings. The Makefile and Compose file already pass `HTTP_PROXY`/`HTTPS_PROXY` as build arguments for the project's own images, but coverage has gaps: - With `WSL2=false REGISTRY=false`, `make build-benchmark` delegates to the `performance-tools` submodule's Makefile, which is outside this repository's proxy plumbing. On WSL2, it instead uses the Windows Python executable configured by `WINDOWS_PYTHON` in the root Makefile and installs its Python dependencies; Windows Python needs its own working network/proxy configuration. Docker proxy settings do not configure Windows pip. - Only `rtsp-streamer` passes the lowercase `http_proxy`/`https_proxy` variants; `curl` reads lowercase `http_proxy` **only**, so `RUN curl http://...` in the other images would bypass the proxy. - `NO_PROXY` is not passed as a build argument anywhere. Setting the CLI-level configuration covers all of these uniformly: ```bash mkdir -p ~/.docker cat > ~/.docker/config.json <<'EOF' { "proxies": { "default": { "httpProxy": "http://proxy.example.com:PORT", "httpsProxy": "http://proxy.example.com:PORT", "noProxy": "localhost,127.0.0.1,.example.com,rabbitmq,minio-service,rtsp-streamer,ovms-vlm,model-downloader" } } } EOF ``` > [!NOTE] > ⚙️ **Site-specific.** Same substitution as [step 7](#7-docker-daemon-proxy) — proxy host, > port, and `.example.com`. > This file is JSON, so a trailing comma or an unescaped value breaks every `docker` > command, not just builds. Validate it after writing: > > ```bash > jq . ~/.docker/config.json > ``` ### Verify Docker end to end Only now can Docker actually reach a registry. Run these in order: ```bash id -nG | tr ' ' '\n' | grep docker docker run hello-world docker compose version docker buildx version ``` `docker run hello-world` is the real test — it pulls from Docker Hub, so it exercises the daemon proxy from step 7. A hang or `TLS handshake timeout` means that drop-in is wrong or did not load; re-check `docker info | grep -i proxy`. `docker compose version` must report **v2.24.4 or newer** — the Makefile uses `docker compose` (space, not hyphen) throughout, and `src/docker-compose-wsl2.yml` relies on the `include` top-level element and the `!override` merge tag, which earlier v2 releases reject. If your version is older, upgrade `docker-compose-plugin` from the Docker apt repository configured in [step 6](#6-install-docker-engine). --- ## 9. Memory and CPU tuning The Vision Language Model (VLM) workload loads a 7B parameter model. Defaults are not sufficient. Edit `C:\Users\\.wslconfig` on the **Windows** side, merging with the networking settings from step 3a: ```ini [wsl2] memory=48GB processors=12 swap=16GB networkingMode=mirrored dnsTunneling=true autoProxy=true firewall=true ``` > [!NOTE] > `localhostForwarding` is unnecessary when `networkingMode=mirrored` is set. > > --- > > ⚙️ **Machine-specific.** Use `$env:USERPROFILE\.wslconfig` for the path. The > `memory`, `processors`, and `swap` values must suit *your* hardware: check with > `Get-CimInstance Win32_ComputerSystem | Select TotalPhysicalMemory` and > `$env:NUMBER_OF_PROCESSORS`, then leave headroom for Windows — roughly 75% of RAM and > total cores is a safe ceiling. **PowerShell:** ```powershell wsl --shutdown ``` **Ubuntu** — verify: ```bash free -h nproc df -h / ``` The repository plus models needs roughly **300 GB**. `df -h /` reports free space inside the WSL filesystem, not free space on the Windows drive storing its virtual disk. Check that host drive separately in **PowerShell** (for example, `Get-PSDrive C` if the distribution is stored on `C:`). Both the WSL filesystem and its Windows host drive need sufficient space. --- ## 10. Clone the repository ```bash cd ~ git clone https://github.com/intel-retail/loss-prevention.git cd loss-prevention git submodule update --init --recursive ``` > [!IMPORTANT] > > 1. **Never clone into `/mnt/c/...`.** Windows drives are reached through a slow > translation layer. Always use `~`, which is the native Linux filesystem. > 2. **The submodule is mandatory.** `performance-tools/` holds every benchmark script. Verify the submodule checked out: ```bash ls performance-tools/benchmark-scripts | head ``` You should see `benchmark.py` and `format_avc_mp4.sh`. An empty directory means the submodule did not initialize. Record your baseline: ```bash git rev-parse --short HEAD git submodule status ``` ### Optional: repository-scoped environment The Makefile reads an optional `.env` file. Proxy variables do **not** need to go here — `make` already imports them from your shell environment. Use `.env` only for values that should not be global, such as secrets and optional WSL2 host configuration: ```bash # .env (do not commit) HUGGINGFACE_TOKEN=hf_xxxxxxxx ``` The Makefile detects WSL2 automatically and selects `src/docker-compose-wsl2.yml` instead of the native `src/docker-compose.yml`. The WSL2 Compose file replaces native Linux `/dev/dri` device mappings with WSL2's `/dev/dxg` and mounts the WSL graphics libraries and driver helper libraries. OpenCL configuration and userspace runtimes come from the container images, not host OpenCL bind mounts. CPU workloads remain CPU workloads because the device is selected by the workload JSON. --- ## 11. GPU and NPU verification This is the decisive check for the whole adaptation of Loss Prevention to WSL2. ### Windows drivers and container userspace runtimes WSL GPU access uses the Windows graphics driver and `/dev/dxg`, not a native Linux GPU kernel driver. WSL exposes graphics libraries under `/usr/lib/wsl/lib` and driver helpers under `/usr/lib/wsl/drivers`. Keep the Windows graphics driver up to date; do not install a native Linux kernel driver to replace it. OpenCL and Level Zero userspace runtimes are separate from that kernel driver. The container images must provide compatible runtimes and ICD configuration. The WSL Compose override retains the image's `/etc/OpenCL` and `/usr/lib/x86_64-linux-gnu/intel-opencl` contents instead of mounting host copies over them. These host directories are not prerequisites and should not be created just to satisfy Docker mounts. Host userspace packages do not provision container runtimes. For `lp-pipeline-runner`, the WSL startup wrapper prepends both WSL library directories to the image's existing `LD_LIBRARY_PATH` before running the normal pipeline script. The other GPU services also include the WSL library paths. GPU enumeration in the actual deployment images remains a required host check; Compose parsing alone does not establish runtime compatibility. If the Windows-provided WSL libraries or `/dev/dxg` are missing, update the Intel graphics driver on Windows, then run `wsl --shutdown`. If the device exists but OpenVINO™ Toolkit (OpenVINO™) cannot enumerate a GPU, inspect the container's runtime and ICD files. > [!NOTE] > NPU workloads remain unsupported by this WSL setup. ### 11a. Host device check ```bash ls -l /dev/dxg ls -l /usr/lib/wsl/lib/ ls -l /usr/lib/wsl/drivers/ ls /dev/dri 2>&1 ls /dev/accel 2>&1 ``` Expected results: | Path | Expected | Meaning | | --- | --- | --- | | `/dev/dxg` | **exists** | the WSL GPU device — replaces `/dev/dri` | | `/usr/lib/wsl/lib/` | populated | WSL graphics bridge libraries such as `libd3d12.so` and `libdxcore.so`; not a substitute for the container's OpenCL runtime | | `/usr/lib/wsl/drivers/` | populated | WSL GPU driver helpers such as `libwsl_compute_helper.so` | | `/dev/dri` | **absent** | expected; this is why the Compose device mappings need changing | | `/dev/accel` | likely absent | the NPU finding | If `/dev/dxg` is missing, stop here and update the Windows graphics driver. ### 11b. OpenVINO™ device enumeration ```bash docker run --rm \ --device=/dev/dxg \ -v /usr/lib/wsl/lib:/usr/lib/wsl/lib:ro \ -v /usr/lib/wsl/drivers:/usr/lib/wsl/drivers:ro \ intel/dlstreamer:2026.2.0-ubuntu24 \ bash -lc '. /opt/intel/openvino/setupvars.sh 2>/dev/null || true; \ export LD_LIBRARY_PATH=/usr/lib/wsl/lib:/usr/lib/wsl/drivers:/usr/lib/openvino-2026.2.0${LD_LIBRARY_PATH:+:$LD_LIBRARY_PATH}; \ python3 -c "import openvino as ov; print(ov.Core().available_devices)"' ``` **Want:** `['CPU', 'GPU']` If only `['CPU']` appears, do not run GPU workloads. Inspect the plugin and driver runtime with: ```bash docker run --rm \ --device=/dev/dxg \ -v /usr/lib/wsl/lib:/usr/lib/wsl/lib:ro \ -v /usr/lib/wsl/drivers:/usr/lib/wsl/drivers:ro \ intel/dlstreamer:2026.2.0-ubuntu24 \ bash -lc 'export LD_LIBRARY_PATH=/usr/lib/wsl/lib:/usr/lib/wsl/drivers:/usr/lib/openvino-2026.2.0${LD_LIBRARY_PATH:+:$LD_LIBRARY_PATH}; \ ldd /usr/lib/openvino-2026.2.0/libopenvino_intel_gpu_plugin.so | grep "not found" || true; \ python3 -c "import openvino as ov; print(ov.Core().available_devices)"' ``` ### 11c. NPU ```bash ls /dev/accel 2>&1 lsmod | grep -i vpu ``` If `NPU` does not appear in the OpenVINO™ device list, that is the expected result on current WSL2 builds, not a mistake on your part. Intel NPU passthrough uses a different mechanism from GPU passthrough and may not be available for your driver and kernel combination. A documented "not supported" is a valid outcome. ### 11d. Record the baseline ```bash { echo "=== /dev/dxg ===" ; ls -l /dev/dxg 2>&1 echo "=== /dev/dri ===" ; ls -l /dev/dri 2>&1 echo "=== /dev/accel ===" ; ls -l /dev/accel 2>&1 echo "=== /usr/lib/wsl/lib ==="; ls /usr/lib/wsl/lib/ echo "=== kernel ===" ; uname -r } | tee ~/wsl-accel-baseline.txt ``` --- ## 12. Smoke test Run in order, stopping at the first failure: ```bash cd ~/loss-prevention # 1. Docker works docker run hello-world # 2. The Makefile parses and resolves variables make -n run-lp | head -20 # 3. Config validators work (proves python3 and jq are fine) make validate-all-configs # 4. What devices does the repo think you have? make check-device-env # 5. Sample videos - small download, fast feedback make download-sample-videos ``` ### Optional: render mode WSLg can display the annotated stream for CPU workloads. `xhost` is provided by `x11-xserver-utils`, which is installed in [step 4](#4-base-packages). Confirm that WSLg set a display: ```bash echo "$DISPLAY" xhost +local:docker ``` Run the CPU object-detection workload with rendering enabled: ```bash RENDER_MODE=1 DISPLAY=:0 make run-lp \ CAMERA_STREAM=camera_to_workload_asc_object_detection.json \ WORKLOAD_DIST=workload_to_pipeline_asc_object_detection_cpu.json ``` When testing a change to `src/gst-pipeline-generator.py`, use `REGISTRY=false` so Docker rebuilds `lp-pipeline-runner` from the current checkout. The registry image does not contain uncommitted or newly pulled local source changes: ```bash make down-lp REGISTRY=false RENDER_MODE=1 DISPLAY=:0 make run-lp \ CAMERA_STREAM=camera_to_workload_asc_object_detection.json \ WORKLOAD_DIST=workload_to_pipeline_asc_object_detection_cpu.json ``` For the WSLg display path, the generated pipeline must include `videoconvert` before the automatic video sink. Verify it in the running container: ```bash docker compose -f src/docker-compose-wsl2.yml exec lp-pipeline-runner \ grep -n 'gvawatermark.*videoconvert.*ximagesink' \ /home/pipeline-server/pipelines/pipeline.sh ``` --- ## Troubleshooting ### MinIO restarts after the image update: backend write permission denied After switching from the previous MinIO image to the Chainguard image, an existing data volume may still be owned by the previous container user. `make run-lp` can then fail with `dependency failed to start: container src-minio-service-1 is unhealthy`. The MinIO logs identify this case with: ```text Error: unable to rename (/data/.minio.sys/tmp -> /data/.minio.sys/tmp-old/...) file access denied FATAL Unable to initialize backend: Unable to write to the backend ``` This is a storage-permissions failure, not a `/dev/tcp` health-check failure. MinIO exits because it cannot write to `/data`, and its restart policy restarts the container. Changing the health check will not fix that startup error. The same issue can occur on native Linux; it depends on volume ownership, not WSL2 detection. Run the following commands in **Ubuntu**, on the affected machine. The examples use the default container name `src-minio-service-1` and volume `src_minio_data`. If your Compose project uses another name, substitute the actual names. 1. Confirm the error, the mounted volume, and the image's runtime UID/GID: ```bash docker logs --tail 100 src-minio-service-1 docker inspect src-minio-service-1 --format 'User={{.Config.User}} Mounts={{json .Mounts}}' MINIO_IMAGE=$(docker inspect src-minio-service-1 --format '{{.Image}}') docker run --rm --network none --entrypoint /bin/sh "$MINIO_IMAGE" -c 'id' ``` For the pinned Chainguard image, the verified values are `User=65532`, `uid=65532(nonroot) gid=65532(nonroot)`, and the named volume mounted at `/data` is `src_minio_data` with `RW=true`. The temporary container used for `id` does not mount your data. Do not use the repair command unchanged if these values differ; use the actual volume name and the UID/GID that the service runs as. 2. Stop MinIO before modifying its storage. Back up the volume first if it contains important data: ```bash docker stop src-minio-service-1 ``` 3. Repair ownership and owner permissions without deleting stored data: ```bash docker run --rm --user 0:0 --network none \ --mount type=volume,source=src_minio_data,target=/data \ alpine:3.22 \ sh -c 'chown -R 65532:65532 /data && chmod -R u+rwX /data' ``` Docker may need to pull `alpine:3.22`; its daemon proxy must already be configured. Root is used only in this temporary repair container. MinIO continues to run as non-root. Stop here if the repair command fails. 4. Start MinIO and inspect recent startup logs: ```bash docker start src-minio-service-1 docker logs --since 1m --tail 50 src-minio-service-1 ``` Allow approximately 30 seconds for the health check, then inspect its result: ```bash docker inspect src-minio-service-1 --format '{{json .State.Health}}' ``` Once it reports `healthy`, rerun your original `make run-lp` command to start the services that were blocked by MinIO. If it remains unhealthy, inspect the new server logs and health-check output before making further changes. This is a **one-time repair for the affected volume**, not a step required on every run. Ownership persists across container restarts, recreation, and normal Compose `down`/`up` operations. Restored data with different ownership or a future runtime UID change may require another migration. Keep the current health check unchanged; do not use `down -v`, delete the volume, apply `chmod 777`, or permanently run MinIO as root to resolve this error.