{"id":15157166,"url":"https://github.com/puppetlabs/pupperware","last_synced_at":"2025-10-12T09:36:40.867Z","repository":{"id":33262913,"uuid":"143212675","full_name":"puppetlabs/pupperware","owner":"puppetlabs","description":"Container fun time lives here. ","archived":false,"fork":false,"pushed_at":"2023-03-10T11:33:54.000Z","size":1050,"stargazers_count":183,"open_issues_count":20,"forks_count":65,"subscribers_count":83,"default_branch":"main","last_synced_at":"2025-05-20T07:04:01.897Z","etag":null,"topics":["pupperware"],"latest_commit_sha":null,"homepage":null,"language":"Ruby","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"other","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/puppetlabs.png","metadata":{"files":{"readme":"README-windows.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":"CODEOWNERS","security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2018-08-01T21:58:21.000Z","updated_at":"2025-04-08T15:55:37.000Z","dependencies_parsed_at":"2024-09-22T05:32:46.781Z","dependency_job_id":"fe82df6a-ff21-4c30-8f4b-634568814038","html_url":"https://github.com/puppetlabs/pupperware","commit_stats":null,"previous_names":[],"tags_count":0,"template":false,"template_full_name":null,"purl":"pkg:github/puppetlabs/pupperware","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/puppetlabs%2Fpupperware","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/puppetlabs%2Fpupperware/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/puppetlabs%2Fpupperware/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/puppetlabs%2Fpupperware/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/puppetlabs","download_url":"https://codeload.github.com/puppetlabs/pupperware/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/puppetlabs%2Fpupperware/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":279010938,"owners_count":26084837,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","status":"online","status_checked_at":"2025-10-12T02:00:06.719Z","response_time":53,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["pupperware"],"created_at":"2024-09-26T20:00:30.732Z","updated_at":"2025-10-12T09:36:40.854Z","avatar_url":"https://github.com/puppetlabs.png","language":"Ruby","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Pupperware on Windows\n\nThe ecosystem surrounding Docker container support for Linux containers on Windows is currently in flux and in heavy active development. In addition to the constant forward momentum, there have been a number of confusing naming choices to the toolchains as components have made foundational underlying changes. As a result, large swaths of online documentation for these projects don't reflect the current state of these projects, or some of their technical details / limitations.\n\nThe Pupperware project is being tested against Windows 10 2004 build 19041 using WSL2 support, and as such has a few pre-requisites:\n\n* A build of Windows at least as new as Windows 10 2004, Build 194041.1 (Insider Slow Ring as of Apr 15 2020)\n* Docker Desktop Edge 2.2.3.0 with WSL2 enabled\n\n### A Brief History\n\nThere have been a number of iterations on the Docker toolchain to support running Linux containers on Windows.\n\n* MobyLinuxVM / Linux mode - initally a fat MobyLinux Hyper-V VM that allowed hosting Linux containers on Windows, which later became a lighter LinuxKit variant in [Docker for Windows 17.10](https://blog.docker.com/2017/11/docker-for-windows-17-11/). In this mode, Windows containers could not be run concurrently. Docker volumes in Linux used SMB / CIFS.\n* LCOW v1 - initial support for side-by-side Windows / Linux containers using a completely different architecture. Both the Docker server / daemon *and* the client run on Windows. The February 2018 [Docker for Windows Desktop 18.02 blog post](https://blog.docker.com/2018/02/docker-for-windows-18-02-with-windows-10-fall-creators-update/) covers the release. \"Linux mode\" was deprecated (but not quite removed). LCOW now interfaces with volumes using [9p](http://9p.cat-v.org/). Docker claimed that LCOW is the one path forward for running Linux Containers on Windows:\n\n\u003e As a Windows platform feature, LCOW represents a long term solution for Linux container support on Windows. When the platform features meet or exceed the existing functionality the existing Docker for Windows Linux container support will be retired.\n* LCOW v2 - as more container use cases cropped up, and issues presented themselves, Hyper-V APIs had to be revisioned. The POSIX APIs used in some containers (chmod, chattr, chown, flock) required very specific API versions - for instance, Postgres requires RS5 API (Windows 10 1809+ / Windows Server 2019+) [Moby Issue 33850 Comment](https://github.com/moby/moby/issues/33850#issuecomment-478192332) from Mar 29 2019 details LCOW will only support V2 HCS APIs which require RS4 / RS5 builds (Windows 10 1803+, Windows Server 2016 1803+, Windows Server 2019+)\n* WSL2 - LCOW is seemingly dead. With Microsoft now supporting Linux distros, running in a VM, inside of Windows, focus has switched once again. The current design runs a Docker daemon in a lightweight VM that the Windows Docker client communicates with. This removes at least 2 major features from LCOW - the ability to run side-by-side Windows and Linux containers, and Hyper-V isolation (between containers). However, many of the [bugs plaguing LCOW](https://docs.microsoft.com/en-us/virtualization/windowscontainers/deploy-containers/linux-containers) are no longer a problem *and* the system is much faster.\n\n### Setup\n\nThe following steps outline how to provision a host with the required support to run this project:\n\n* [Provision a Windows host with WSL2 support](#provision-a-windows-host-with-wsl2-support)\n* [Install the Docker Desktop Edge Release](#install-the-docker-desktop-edge-release)\n* [Validate the Install](#validate-the-install)\n\nAt the time of this writing, the Windows 10 2004 test host returns the following Docker versions:\n\n```\nClient: Docker Engine - Community\n Version:           19.03.8\n API version:       1.40\n Go version:        go1.12.17\n Git commit:        afacb8b\n Built:             Wed Mar 11 01:23:10 2020\n OS/Arch:           windows/amd64\n Experimental:      true\n\nServer: Docker Engine - Community\n Engine:\n  Version:          19.03.8\n  API version:      1.40 (minimum version 1.12)\n  Go version:       go1.12.17\n  Git commit:       afacb8b\n  Built:            Wed Mar 11 01:29:16 2020\n  OS/Arch:          linux/amd64\n  Experimental:     true\n containerd:\n  Version:          v1.2.13\n  GitCommit:        7ad184331fa3e55e52b890ea95e65ba581ae3429\n runc:\n  Version:          1.0.0-rc10\n  GitCommit:        dc9208a3303feef5b3839f4323d9beb36df0a9dd\n docker-init:\n  Version:          0.18.0\n  GitCommit:        fec3683\n```\n\n### Additional Reference\n\n* [docker-for-win](https://github.com/docker/for-win) - Public issue tracking for `Docker CE for Windows`\n\n## Provision a Windows host with WSL2 support\n\nAs mentioned, Windows 10 2004 build 19041.1 is necessary to support WSL2.\n\nIf the host is provisioned in Azure, the host must be a `v3` SKU to support nested virtualization, like `Standard_D4s_v3`. Other cloud providers or virtualized infrastructure will have similar requirements / configuration needed to enable nested virtualization.\n\n### Install Slow Ring\n\nFollow the [basic instructions](https://insider.windows.com/en-us/how-to-pc/) for joining the Insider Program and installing Slow Ring\n\n### Install WSL2\n\nThe latest directions are available [from Microsoft](https://docs.microsoft.com/en-us/windows/wsl/wsl2-install), but are essentially the following steps\n\n#### Enable Windows features\n\nWSL2 support requires enabling several features with the PowerShell command, and generally will require rebooting:\n\n```powershell\nPS\u003e $reboot = Enable-WindowsOptionalFeature -Online -FeatureName Microsoft-Hyper-V,Microsoft-Windows-Subsystem-Linux,VirtualMachinePlatform -All -NoRestart\n\n# WSL2 cannot run until the computer is restarted\nif ($reboot.RestartNeeded) { Restart-Computer }\n```\n\nNote that Hyper-V support is still currently necessary to be able to run the WSL2 distributions, though no Hyper-V virtual machine will be visible in any of the Microsoft management tools when running Linux containers.\n\n#### Upgrade the kernel\n\nThe [WSL2 Linux kernel](https://aka.ms/wsl2kernel) must also be [upgraded](https://docs.microsoft.com/en-us/windows/wsl/wsl2-kernel) to support the latest version of Windows:\n\n```powershell\nInvoke-WebRequest -Uri https://wslstorestorage.blob.core.windows.net/wslblob/wsl_update_x64.msi -OutFile $ENV:TEMP\\wsl_update_x64.msi -UseBasicParsing\nmsiexec /qn /i $ENV:TEMP\\wsl_update_x64.msi\n```\n\n#### Install a Linux distro\n\nInstall Ubuntu 18.04 into WSL2\n\n```powershell\nInvoke-WebRequest -Uri https://aka.ms/wsl-ubuntu-1804 -OutFile $ENV:TEMP\\wsl-ubuntu-1804.appx -UseBasicParsing\nAdd-AppxPackage $ENV:TEMP\\wsl-ubuntu-1804.appx\n```\n\nNOTE: The application must now be launched from the Start Menu to complete initialization. The system will prompt for a new user and password to be created. (For test instances the values `puppet` and `puppet` have been chosen). It's possible this can be scripted following [these instructions](https://superuser.com/a/1272559)\n\n#### Set Default WSL2 Version Distribution\n\nMake sure that WSL2 is the default and the previously installed distro is set to be the default:\n\n```\nwsl --set-default-version 2\nwsl --set-version Ubuntu-18.04 2\n```\n\n## Install the Docker Desktop Edge Release\n\nOn the provisioned host, the Docker Desktop Edge release most now be installed. For more information, see the [Docker documentation](https://docs.docker.com/docker-for-windows/wsl-tech-preview/)\n\nRun the following PowerShell script to:\n\n* Install Chocolatey package manager for Windows\n* Install the edge release of Docker Desktop with Chocolatey\n\n```powershell\n# set process execution policy\nSet-ExecutionPolicy Bypass -Scope Process -Force\n\n# install Chocolatey\niex ((New-Object System.Net.WebClient).DownloadString('https://chocolatey.org/install.ps1'))\n\nchoco install -y --pre docker-desktop\n```\n\nThe Docker installer will automatically detect WSL2 support and will configure the default distribution to run the Docker server.\n\n### Firewall exclusions\n\nDepending on how Docker is being used, there may be a couple of additional steps to making things work. For instance, running an Azure DevOps agent that uses Docker requires two additional system changes:\n\n* The `Network Service` account (or whichever account runs the agent) must be a member of the `docker-users` group.\n* Firewall exclusions must be added as inbound rules for `com.docker.backend` for application `C:\\program files\\docker\\docker\\resources\\com.docker.backend.exe`\n\n## Validate the install\n\nThe Docker service should now be running on boot and should now yield details about the WSL2 setup like\n\n```powershell\nPS\u003e docker info\n\nClient:\n Debug Mode: false\n Plugins:\n  app: Docker Application (Docker Inc., v0.8.0)\n  buildx: Build with BuildKit (Docker Inc., v0.3.1-tp-docker)\n  mutagen: Synchronize files with Docker Desktop (Docker Inc., testing)\n\nServer:\n Containers: 2\n  Running: 2\n  Paused: 0\n  Stopped: 0\n Images: 46\n Server Version: 19.03.8\n Storage Driver: overlay2\n  Backing Filesystem: \u003cunknown\u003e\n  Supports d_type: true\n  Native Overlay Diff: true\n Logging Driver: json-file\n Cgroup Driver: cgroupfs\n Plugins:\n  Volume: local\n  Network: bridge host ipvlan macvlan null overlay\n  Log: awslogs fluentd gcplogs gelf journald json-file local logentries splunk syslog\n Swarm: inactive\n Runtimes: runc\n Default Runtime: runc\n Init Binary: docker-init\n containerd version: 7ad184331fa3e55e52b890ea95e65ba581ae3429\n runc version: dc9208a3303feef5b3839f4323d9beb36df0a9dd\n init version: fec3683\n Security Options:\n  seccomp\n   Profile: default\n Kernel Version: 4.19.84-microsoft-standard\n Operating System: Docker Desktop\n OSType: linux\n Architecture: x86_64\n CPUs: 2\n Total Memory: 12.49GiB\n Name: docker-desktop\n ID: CU4P:YEJH:OG4G:UV2M:CQNR:FUNG:UXQI:FFX5:OGTY:YAW3:3LIT:3RJ3\n Docker Root Dir: /var/lib/docker\n Debug Mode: true\n  File Descriptors: 58\n  Goroutines: 65\n  System Time: 2020-04-15T17:36:28.4071887Z\n  EventsListeners: 3\n Registry: https://index.docker.io/v1/\n Labels:\n Experimental: true\n Insecure Registries:\n  127.0.0.0/8\n Live Restore Enabled: false\n Product License: Community Engine\n\nWARNING: bridge-nf-call-iptables is disabled\nWARNING: bridge-nf-call-ip6tables is disabled\n```\n\nDocker-compose should also provide information like:\n\n```\nPS\u003e docker-compose version\n\ndocker-compose version 1.26.0-rc3, build 46118bc5\ndocker-py version: 4.2.0\nCPython version: 3.7.4\nOpenSSL version: OpenSSL 1.1.1c  28 May 2019\n```\n\nWith all of the WSL2 setup verified, it should now be possible to launch a Linux container:\n\n```powershell\ndocker run --rm alpine uname\n```\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fpuppetlabs%2Fpupperware","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fpuppetlabs%2Fpupperware","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fpuppetlabs%2Fpupperware/lists"}