{"id":48469561,"url":"https://github.com/csidirop/windowsdockersetup","last_synced_at":"2026-04-07T06:02:11.550Z","repository":{"id":348269392,"uuid":"1197143494","full_name":"csidirop/WindowsDockerSetup","owner":"csidirop","description":null,"archived":false,"fork":false,"pushed_at":"2026-03-31T13:10:28.000Z","size":23,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-03-31T14:40:21.720Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":null,"language":"PowerShell","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"gpl-3.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/csidirop.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2026-03-31T11:09:50.000Z","updated_at":"2026-03-31T13:10:32.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/csidirop/WindowsDockerSetup","commit_stats":null,"previous_names":["csidirop/windowsdockersetup"],"tags_count":null,"template":false,"template_full_name":null,"purl":"pkg:github/csidirop/WindowsDockerSetup","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/csidirop%2FWindowsDockerSetup","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/csidirop%2FWindowsDockerSetup/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/csidirop%2FWindowsDockerSetup/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/csidirop%2FWindowsDockerSetup/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/csidirop","download_url":"https://codeload.github.com/csidirop/WindowsDockerSetup/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/csidirop%2FWindowsDockerSetup/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":31501903,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-04-07T03:10:19.677Z","status":"ssl_error","status_checked_at":"2026-04-07T03:10:13.982Z","response_time":105,"last_error":"SSL_connect returned=1 errno=0 peeraddr=140.82.121.5:443 state=error: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"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":[],"created_at":"2026-04-07T06:02:09.444Z","updated_at":"2026-04-07T06:02:11.513Z","avatar_url":"https://github.com/csidirop.png","language":"PowerShell","funding_links":[],"categories":[],"sub_categories":[],"readme":"# WSL Docker Wrapper Setup\n\nThis repository provides a PowerShell setup script for running **Docker Engine inside Ubuntu on WSL 2** while exposing a near-native `docker` command on Windows.\n\nIt does **not** install Docker Desktop.\n\n## What the script does\n\nThe setup script:\n\n- checks whether `wsl.exe` is available\n- checks whether the target WSL distro exists\n- converts the distro to **WSL 2** if needed\n- verifies that the distro is ready for non-interactive use\n- checks whether Docker Engine is already installed inside WSL\n- installs Docker Engine and the Compose plugin inside Ubuntu if missing\n- adds the default Linux user to the `docker` group\n- writes PowerShell wrapper functions so `docker ...` works from Windows\n- optionally writes `docker.cmd` and `docker-compose.cmd` shims for `cmd.exe`, IDE terminals, and tools that expect `docker` on `PATH`\n\nThe wrappers auto-start `dockerd` inside WSL on demand, without requiring `systemd`, and the Windows shim waits for the daemon to become ready before forwarding the Docker command.\n\n## Requirements\n\n- Windows with **WSL** installed\n- An **Ubuntu** WSL distro, or another distro name passed via `-Distro`\n- Internet access for package installation inside WSL\n\n## Default behavior\n\nBy default, the script assumes:\n\n- distro name: `Ubuntu`\n- cmd shims: enabled\n- Docker install: only performed if Docker is not already present\n\n## Parameters\n\n### `-Distro \u003cstring\u003e`\nTarget WSL distro name.\n\nExample:\n\n```powershell\npowershell -ExecutionPolicy Bypass -File .\\setup-wsl-docker-wrapper.ps1 -Distro \"Ubuntu-24.04\"\n```\n\n### `-CreateCmdShim`\nCreates `docker.cmd` and `docker-compose.cmd` in `%USERPROFILE%\\bin`.\n\nThis switch is enabled by default in the script.\n\nExample: disable cmd shim creation\n\n```powershell\npowershell -ExecutionPolicy Bypass -File .\\setup-wsl-docker-wrapper.ps1 -CreateCmdShim:$false\n```\n\n### `-ForceDockerInstall`\nForces a Docker reinstall inside the WSL distro even if Docker is already detected.\n\nExample:\n\n```powershell\npowershell -ExecutionPolicy Bypass -File .\\setup-wsl-docker-wrapper.ps1 -ForceDockerInstall\n```\n\n## Usage\n\nRun the script from PowerShell:\n\n```powershell\npowershell -ExecutionPolicy Bypass -File .\\setup-wsl-docker-wrapper.ps1\n```\n\nIf your distro is not named `Ubuntu`:\n\n```powershell\npowershell -ExecutionPolicy Bypass -File .\\setup-wsl-docker-wrapper.ps1 -Distro \"Ubuntu-24.04\"\n```\n\n## What gets installed inside WSL\n\nIf Docker is missing, the script installs these packages from Docker’s official Ubuntu repository:\n\n- `docker-ce`\n- `docker-ce-cli`\n- `containerd.io`\n- `docker-buildx-plugin`\n- `docker-compose-plugin`\n\nIt also removes conflicting packages such as older distro-provided Docker packages before installation.\n\n## PowerShell wrapper behavior\n\nThe script writes a block into your PowerShell profile (`$PROFILE.CurrentUserAllHosts`) containing:\n\n- `docker`\n- `docker-compose`\n- `docker-start`\n- `docker-stop`\n- `docker-log`\n\n### Wrapper details\n\n- `docker` ensures the Docker daemon is running inside WSL, then forwards all arguments\n- `docker-compose` forwards to `docker compose`\n- `docker-start` starts `dockerd` inside WSL if it is not already running\n- `docker-stop` stops `dockerd`\n- `docker-log` prints `/tmp/dockerd.log` from inside WSL\n\nThe wrapper is written inside markers so repeated runs update the same block instead of duplicating it.\n\n## cmd shim behavior\n\nIf cmd shims are enabled, the script:\n\n1. ensures `%USERPROFILE%\\bin` exists\n2. adds `%USERPROFILE%\\bin` to the user `PATH` if missing\n3. writes:\n   - `docker.cmd`\n   - `docker-compose.cmd`\n\nThese shims make Docker available from:\n\n- `cmd.exe`\n- many IDE terminals\n- tools that call `docker` directly from Windows\n\nSome GUI tools still work better when given the shim path explicitly instead of relying on shell discovery alone.\n\n## VS Code Fallback for a local Windows VS Code window\n\nConfigure the Dev Containers extension to use the generated shim directly:\n\n```json\n{\n  \"dev.containers.dockerPath\": \"C:\\\\Users\\\\\u003cyou\u003e\\\\bin\\\\docker.cmd\"\n}\n```\n\nThen restart VS Code.\n\n## First run after setup\n\nThe script performs an automatic Docker smoke test at the end of setup.\nIf cmd shims are enabled, it also performs a Windows cmd shim smoke test.\n\nOpen a new PowerShell window and test:\n\n```powershell\ndocker version\ndocker ps\ndocker compose version\n```\n\nIf Linux group membership was changed during setup, apply it once by restarting WSL:\n\n```powershell\nwsl --shutdown\n```\n\nThen open a new terminal and test again.\n\n## Notes\n\n- This setup is intended for **Linux containers in WSL 2**.\n- It is designed for **Ubuntu-based WSL distros** because the install path uses Docker’s Ubuntu repository.\n- It does not depend on `systemd`.\n- `dockerd` is started manually in the background when needed.\n\n## Troubleshooting\n\n### `wsl.exe` not found\nInstall WSL from an elevated PowerShell:\n\n```powershell\nwsl --install -d Ubuntu\n```\n\nThen reboot, launch Ubuntu once, complete initial user setup, and rerun the script.\n\n### Distro exists but the script says it is not ready\nOpen the distro manually once:\n\n```powershell\nwsl -d Ubuntu\n```\n\nComplete the first-time Linux user creation flow, then rerun the script.\n\n### `docker` works in WSL but not in PowerShell\nOpen a new PowerShell session so the updated profile is loaded.\n\nYou can also load it manually in the current session:\n\n```powershell\n. $PROFILE.CurrentUserAllHosts\n```\n\n### `docker` works in PowerShell but not in `cmd.exe`\nCheck whether `%USERPROFILE%\\bin` is on your user `PATH`, then open a new `cmd.exe` window.\n\n### VS Code Dev Containers does not find Docker\n\nUse the preferred WSL workflow above: open the folder in a WSL window first, then run `Dev Containers: Reopen in Container`.\n\nIf you intentionally use a local Windows VS Code window, set:\n\n```json\n{\n  \"dev.containers.dockerPath\": \"C:\\\\Users\\\\\u003cyou\u003e\\\\bin\\\\docker.cmd\"\n}\n```\n\nAfter changing the setting, restart VS Code so it picks up the new Docker path.\n\n### Docker permission denied inside WSL\nThe Linux user may need the new `docker` group membership applied:\n\n```powershell\nwsl --shutdown\n```\n\nThen reopen the terminal.\n\n### Daemon startup issues\nInspect the WSL daemon log:\n\n```powershell\ndocker-log\n```\n\nOr directly inside WSL:\n\n```bash\ntail -n 200 /tmp/dockerd.log\n```\n\n## Security and scope\n\nThis setup installs Docker Engine inside the selected WSL distro and modifies:\n\n- the distro’s package sources and packages\n- Linux group membership for the default WSL user\n- your PowerShell profile\n- your user `PATH` if cmd shims are enabled\n- `%USERPROFILE%\\bin` if cmd shims are enabled\n\nReview the script before running it in managed or locked-down environments.\n\n## Example workflow\n\nAfter setup, a normal Windows PowerShell session should look like this:\n\n```powershell\ndocker version\ndocker ps\ndocker run hello-world\ndocker compose up -d\n```\n\nAll of those commands are forwarded into Docker Engine running inside WSL.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fcsidirop%2Fwindowsdockersetup","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fcsidirop%2Fwindowsdockersetup","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fcsidirop%2Fwindowsdockersetup/lists"}