{"id":47950013,"url":"https://github.com/loresoft/docker-wsl","last_synced_at":"2026-04-04T09:00:16.926Z","repository":{"id":331068241,"uuid":"1124273266","full_name":"loresoft/docker-wsl","owner":"loresoft","description":"Automated PowerShell script to set up Docker in WSL2 without Docker Desktop.","archived":false,"fork":false,"pushed_at":"2026-01-02T14:48:29.000Z","size":26,"stargazers_count":12,"open_issues_count":0,"forks_count":1,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-04-04T09:00:06.834Z","etag":null,"topics":["docker","wsl","wsl-ubuntu","wsl2"],"latest_commit_sha":null,"homepage":"","language":"PowerShell","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/loresoft.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":"2025-12-28T17:41:58.000Z","updated_at":"2026-03-25T14:08:24.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/loresoft/docker-wsl","commit_stats":null,"previous_names":["loresoft/docker-wsl"],"tags_count":0,"template":false,"template_full_name":null,"purl":"pkg:github/loresoft/docker-wsl","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/loresoft%2Fdocker-wsl","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/loresoft%2Fdocker-wsl/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/loresoft%2Fdocker-wsl/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/loresoft%2Fdocker-wsl/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/loresoft","download_url":"https://codeload.github.com/loresoft/docker-wsl/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/loresoft%2Fdocker-wsl/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":31393782,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-04-04T04:26:24.776Z","status":"ssl_error","status_checked_at":"2026-04-04T04:23:34.147Z","response_time":60,"last_error":"SSL_read: 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":["docker","wsl","wsl-ubuntu","wsl2"],"created_at":"2026-04-04T09:00:14.921Z","updated_at":"2026-04-04T09:00:16.881Z","avatar_url":"https://github.com/loresoft.png","language":"PowerShell","readme":"# Docker WSL Setup Script\n\nAutomated PowerShell script to set up Docker in WSL2 without Docker Desktop.\n\n## Overview\n\nThis script provides a complete automated installation of Docker running natively in WSL2 (Ubuntu), allowing you to use Docker from both Windows PowerShell and the Linux environment without requiring Docker Desktop.\n\n## Features\n\n- Installs and configures WSL2 with mirrored networking mode\n- Installs Ubuntu distribution\n- Installs Docker Engine in Ubuntu\n- Configures Docker daemon with systemd\n- Installs Docker CLI tools on Windows\n- Automatically detects WSL IP and configures DOCKER_HOST\n- Sets up Task Scheduler to auto-start Ubuntu at user logon\n- Enables Docker commands from both Windows and WSL\n\n## Prerequisites\n\n- Windows 10 version 2004 or higher (Build 19041 and higher) or Windows 11\n- Administrator privileges\n- Internet connection\n\n## Installation\n\n### Quick Start\n\n1. **Open PowerShell as Administrator**\n   - Right-click PowerShell and select \"Run as Administrator\"\n\n2. **Run the script**\n\n   ```powershell\n   .\\docker-wsl.ps1\n   ```\n\n3. **Follow the prompts**\n   - The script will pause for you to complete Ubuntu setup (username/password)\n   - After creating your Ubuntu username and password, type `exit` to return to PowerShell\n   - Press any key to continue the installation\n\n4. **Restart your computer**\n   - Required for all WSL changes to take effect\n\n5. **Test Docker**\n\n   ```powershell\n   docker run hello-world\n   ```\n\n## What the Script Does\n\nThe installation process includes 8 steps:\n\n1. **Install WSL** - Enables Windows Subsystem for Linux\n2. **Enable Virtual Machine Platform** - Required for WSL2\n3. **Update WSL** - Gets the latest WSL version\n4. **Set WSL 2 as default and configure networking** - Ensures new distributions use WSL2 and sets up mirrored networking mode\n5. **Install Ubuntu** - Installs Ubuntu distribution from Windows Store\n6. **Update Ubuntu and Install Docker** - Updates Ubuntu packages and installs Docker Engine, CLI, containerd, and Docker Compose plugin\n7. **Install Windows Docker tools** - Installs Docker CLI, Compose, and Buildx on Windows, and configures DOCKER_HOST with `tcp://127.0.0.1:2375`\n8. **Create Task Scheduler job** - Sets up automatic Ubuntu startup at user logon to ensure the WSL distribution stays running (required for Docker to remain accessible from Windows)\n\n## How It Works\n\n- **WSL networking** is configured in mirrored mode for better network compatibility\n- **Docker Engine** runs inside WSL Ubuntu as a systemd service\n- **Docker CLI** on Windows connects to the WSL Docker daemon via localhost (127.0.0.1:2375) in mirrored networking mode\n- **Task Scheduler** automatically starts Ubuntu at user logon and keeps it running in the background\n  - WSL distributions automatically shut down when idle to save resources\n  - The scheduled task runs a background process (`sleep infinity`) to prevent Ubuntu from stopping\n  - This ensures Docker remains accessible from Windows PowerShell at all times\n  - Without this task, you would need to manually start WSL before using Docker commands\n- You can use `docker` commands from both PowerShell and Ubuntu terminal\n- The `DOCKER_HOST` environment variable is automatically set to `tcp://127.0.0.1:2375` for mirrored networking mode\n\n## Usage\n\nAfter installation, you can use Docker commands from any PowerShell or terminal window:\n\n```powershell\n# Pull and run containers\ndocker pull nginx\ndocker run -d -p 8080:80 nginx\n\n# Use Docker Compose\ndocker compose up -d\n\n# Check Docker status\ndocker ps\ndocker images\n```\n\nFrom within Ubuntu WSL:\n```bash\n# Same Docker commands work\ndocker ps\nsudo systemctl status docker\n```\n\n## Managing Docker with Portainer\n\nFor a web-based Docker management interface, we recommend using [Portainer](https://www.portainer.io/). Portainer provides an intuitive UI to manage containers, images, volumes, networks, and more.\n\n### Installing Portainer\n\n```powershell\n# Create a volume for Portainer data\ndocker volume create portainer_data\n\n# Run Portainer container\ndocker run -d `\n  --name portainer `\n  -p 9000:9000 `\n  -p 9443:9443 `\n  --restart always `\n  -v /var/run/docker.sock:/var/run/docker.sock `\n  -v portainer_data:/data `\n  portainer/portainer-ce:latest\n```\n\n### Accessing Portainer\n\n1. Open your browser and navigate to: `http://localhost:9000` or `https://localhost:9443`\n2. Create your admin account on first launch\n3. Select \"Docker\" as the environment to manage\n4. Start managing your Docker environment through the web interface\n\n### Portainer Features\n\n- Visual container management (start, stop, restart, remove)\n- Image management and registry connections\n- Volume and network management\n- Docker Compose stack deployment\n- Container logs and stats viewing\n- Terminal access to containers\n\n## Troubleshooting\n\n### Ensure Ubuntu distribution is running\n\n```powershell\n# Check if Ubuntu is running\nwsl -l -v\n\n# Check if the scheduled task is running\nGet-ScheduledTask -TaskName \"WSL-Ubuntu-Startup\"\n\n# If the task is not running, start it\nStart-ScheduledTask -TaskName \"WSL-Ubuntu-Startup\"\n\n# Alternative: If Ubuntu is not running (State: Stopped), \n# you can start it manually instead of using the scheduled task\nwsl -d Ubuntu\n```\n\n### Docker daemon not running\n\n```powershell\nwsl -d Ubuntu sudo systemctl start docker\n```\n\n### Check Docker status\n\n```powershell\nwsl -d Ubuntu sudo systemctl status docker\n```\n\n### Restart Docker service\n\n```powershell\nwsl -d Ubuntu sudo systemctl restart docker\n```\n\n### Verify DOCKER_HOST is set\n\n```powershell\necho $env:DOCKER_HOST\n# Should output: tcp://127.0.0.1:2375\n```\n\n### DOCKER_HOST connection issues\n\nIf Docker commands fail to connect, try these alternatives:\n\n**For mirrored networking mode (default in this script):**\n\n```powershell\n# Try IPv4 localhost\n[Environment]::SetEnvironmentVariable(\"DOCKER_HOST\", \"tcp://127.0.0.1:2375\", \"User\")\n\n# Try IPv6 localhost\n[Environment]::SetEnvironmentVariable(\"DOCKER_HOST\", \"tcp://[::1]:2375\", \"User\")\n```\n\n**For NAT networking mode (if you changed from mirrored):**\n\n```powershell\n# Get the WSL IP address and set DOCKER_HOST\n$wslIp = wsl -d Ubuntu hostname -I | ForEach-Object { $_.Trim().Split()[0] }\n[Environment]::SetEnvironmentVariable(\"DOCKER_HOST\", \"tcp://${wslIp}:2375\", \"User\")\n```\n\nAfter changing DOCKER_HOST, restart your PowerShell session for the changes to take effect.\n\n**Test without changing environment variable:**\n\nYou can test different host addresses without modifying DOCKER_HOST using the `-H` option:\n\n```powershell\n# Test with IPv4 localhost\ndocker -H tcp://127.0.0.1:2375 ps\n\n# Test with IPv6 localhost\ndocker -H tcp://[::1]:2375 ps\n\n# Test with WSL IP (for NAT mode)\n$wslIp = wsl -d Ubuntu hostname -I | ForEach-Object { $_.Trim().Split()[0] }\ndocker -H tcp://${wslIp}:2375 ps\n```\n\n### Test Docker API connection\n\n```powershell\n# Test if Docker API is responding (mirrored networking uses localhost)\ncurl http://localhost:2375/version\n```\n\n### Restart WSL\n\n```powershell\nwsl --shutdown\nwsl\n```\n\n## Security Considerations\n\n⚠️ **Important**: This script configures Docker to listen on `tcp://0.0.0.0:2375` without TLS encryption. This is suitable for local development but exposes Docker to your local network.\n\nFor production use, consider:\n\n- Using Unix socket only\n- Enabling TLS authentication\n- Restricting network access with firewall rules\n\n## Uninstallation\n\nTo remove Docker:\n\n```powershell\n# Remove Docker CLI tools from Windows (run in PowerShell as Administrator)\nwinget uninstall Docker.DockerCLI\nwinget uninstall Docker.DockerCompose\nwinget uninstall Docker.Buildx\n\n# Remove DOCKER_HOST environment variable\n[Environment]::SetEnvironmentVariable(\"DOCKER_HOST\", $null, \"User\")\n\n# Remove Task Scheduler job\nUnregister-ScheduledTask -TaskName \"WSL-Ubuntu-Startup\" -Confirm:$false\n\n# Optionally remove Ubuntu distribution\nwsl --unregister Ubuntu\n\n# Optionally remove .wslconfig file\nRemove-Item \"$env:USERPROFILE\\.wslconfig\" -Force\n```\n\n## License\n\nMIT License - See [LICENSE](LICENSE) file for details\n\n## Contributing\n\nContributions are welcome! Please feel free to submit issues or pull requests.\n","funding_links":[],"categories":[],"sub_categories":[],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Floresoft%2Fdocker-wsl","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Floresoft%2Fdocker-wsl","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Floresoft%2Fdocker-wsl/lists"}