Goal

• Prepare a basic toolset for working with containers on Windows using WSL2 and Docker Desktop.
• Use this procedure if you have a current Windows 10 system.

Requirements:

• Windows 10, version 2004 or later (build 19041+). If your version is older, use Windows Update or this manual install guide. Check your exact version with winver.
• A 64-bit system with at least 4 GB RAM.
• Virtualization enabled in BIOS/UEFI.

Architecture overview:

  +----------------+                +---------------+
  | Ubuntu on WSL2 |                | Docker Engine |
  | Docker CLI     |<--connection-->| on WSL2       |
  +----------------+  via virt.net  +---------------+
         ^                               ^
         |                               |
  Windows Terminal                 Docker Desktop

Procedure:

1. Install WSL2 and Ubuntu Linux. After installation you should have:

   • WSL2, Windows Subsystem for Linux 2 — a virtual machine for installing Linux using Hyper-V.
   • Ubuntu (current LTS, e.g., 22.04/24.04) — a complete Ubuntu environment.
   • Other distributions are available in the Microsoft Store.

2. Install Windows Terminal — a convenient terminal for connecting to Ubuntu (WSL) and other shells.

3. Verify WSL2 is working.

   • Launch Windows Terminal from the Start menu.
   • Click the dropdown arrow and select "Ubuntu" to open the Ubuntu shell.
   • Check the IP address of the Ubuntu instance: ip address.
   • Note: Antivirus software can sometimes disrupt the WSL2 network.

4. Install Docker Desktop. It provides:

   • Docker Engine — a VM that runs containers using WSL2/Hyper-V.
   • Docker CLI — a command-line tool to interact with Docker Engine.
   • Kubernetes (optional) — an orchestrator for complex container deployments.

5. Verify Docker is running.

   • The "Docker Desktop" icon and the message "Docker is running" should appear in the system tray (lower-right corner).

6. Connect the Docker CLI to Docker Engine.

   • Start Ubuntu via Windows Terminal.
   • Install required packages:

     sudo apt-get update
     sudo apt-get upgrade
     sudo apt-get install docker.io vim

   • Configure WSL integration:
     • Click the "Docker Desktop" icon.
     • Open "Settings".
     • Find Resources/WSL Integration.
     • Enable "Enable integration with additional distros".
   • Verify it works.

Finally, in the Ubuntu shell, run: docker version.

Expected output example:

Client:
 Version:           19.03.8
 API version:       1.40
 Go version:        go1.13.8
 Git commit:        afacb8b7f0
 Built:             Fri Dec 18 12:15:19 2020
 OS/Arch:           linux/amd64
 Experimental:      true

Server: Docker Engine - Community
 Engine:
  Version:          20.10.2
  API version:      1.41 (minimum version 1.12)
  Go version:       go1.13.15
  Git commit:       8891c58
  Built:            Mon Dec 28 16:15:28 2020
  OS/Arch:          linux/amd64
  Experimental:     false
 containerd:
  Version:          1.4.3
  GitCommit:        269548fa27e0089a8b8278fc4fc781d7f65a939b
 runc:
  Version:          1.0.0-rc92
  GitCommit:        ff819c7e9184c13b7c2607fe6c30ae19403a7aff
 docker-init:
  Version:          0.19.0
  GitCommit:        de40ad0

If an error appears, reconfigure Docker and WSL integration.

Open Docker Desktop → Settings. In the menu, find the "Resources" and "WSL Integration" sections. Ensure integration is enabled for your Ubuntu distribution as shown.

Troubleshooting

• Verify WSL: wsl --status and wsl -l -v. Optionally restart WSL: wsl --shutdown, then start Ubuntu again.
• If Docker doesn't run, open Docker Desktop → "Troubleshoot" → "Reset to factory defaults", or restart Docker Desktop.
• Antivirus/firewall software can cause WSL network issues; temporarily disable it or add exceptions for WSL/Docker.
• Ensure virtualization is enabled in BIOS/UEFI (Intel VT-x/AMD-V) and Windows features "Virtual Machine Platform" and "Windows Subsystem for Linux" are enabled.
• In Docker Desktop → Settings → Resources, adjust CPU/RAM if containers are slow or crashing.
• When using Docker Desktop integration within WSL, installing the docker.io package is not required; prefer the CLI provided by Docker Desktop.

Next Post