Technical

This comprehensive guide walks you through installing Docker Desktop on Windows 11, setting up WSL 2, and managing your projects effectively.

Prerequisites

• Windows 11 64-bit (Home or Pro edition)
• Administrator access to your computer
• Virtualization enabled in BIOS (we’ll verify this)

Step 1: Verify Virtualization is Enabled

Before installing Docker, check if virtualization is enabled on your system.

Quick Method – Task Manager

1. Right-click on the taskbar and select Task Manager (or press Ctrl + Shift + Esc)
2. Click on the Performance tab
3. Click on CPU in the left panel
4. Look at the bottom right for “Virtualization: Enabled”

If it shows “Disabled”, you’ll need to enable it in BIOS:

1. Restart your computer
2. Enter BIOS (usually by pressing F2, F10, Del, or Esc during startup)
3. Find virtualization settings under Advanced, CPU Configuration, or Security:
   • Intel processors: Look for “Intel VT-x” or “Intel Virtualization Technology”
   • AMD processors: Look for “AMD-V” or “SVM Mode”
4. Enable it and save changes
5. Restart your computer

Step 2: Install WSL 2 and Ubuntu

Docker Desktop on Windows requires WSL 2 (Windows Subsystem for Linux).

Install WSL and Ubuntu

1. Open PowerShell as Administrator:
   • Right-click Start menu ? Terminal (Admin) or Windows PowerShell (Admin)
2. Run the installation command: wsl --install This installs WSL 2 and Ubuntu by default.
3. Restart your computer when prompted
4. After restart, Ubuntu will automatically open:
   • Create a username (can be different from your Windows username)
   • Create a password (characters won’t appear as you type – this is normal)
   • Remember this password – you’ll need it for admin tasks

Verify WSL Installation

Open PowerShell and run:

wsl --list --verbose

You should see Ubuntu listed with VERSION 2.

Step 3: Install Docker Desktop

Download and Install

1. Go to https://www.docker.com/products/docker-desktop
2. Download Docker Desktop for Windows
3. Run the installer
4. When prompted, choose “Use WSL 2 instead of Hyper-V” (recommended)
5. Complete the installation
6. Restart your computer

Start Docker Desktop

1. Launch Docker Desktop from the Start menu
2. Wait for it to start (you’ll see a whale icon in the system tray)
3. Accept the terms and conditions if prompted

Verify Docker Installation

Open PowerShell or Command Prompt and run:

docker --version
docker run hello-world

If you see a “Hello from Docker!” message, Docker is working correctly!

Step 4: Configure Docker with WSL

Enable WSL Integration

1. Open Docker Desktop
2. Click the gear icon (Settings)
3. Go to Resources ? WSL Integration
4. Enable “Enable integration with my default WSL distro”
5. Toggle on your Ubuntu distribution
6. Click Apply & Restart

Now Docker will work from both Windows and Ubuntu terminals!

Step 5: Choose Where to Store Your Projects

You have two options for project location:

Option A: Keep Projects in Windows (Recommended for Cursor AI Users)

Location: C:\Users\YourUsername\Projects\your-project

Pros:

• Easy access with Windows tools and IDEs like Cursor AI
• Familiar file structure
• Simple drag-and-drop

Access from Docker:

cd C:\Users\YourUsername\Projects\your-project
docker run --rm -v ${PWD}:/app your-image

Option B: Store Projects in WSL Ubuntu

Location: /home/yourusername/projects/your-project (inside Ubuntu)

Pros:

• Faster Docker performance
• Native Linux development environment

Access from Windows:

• In File Explorer, type: \\wsl$\Ubuntu\home\yourusername\projects
• Bookmark this location for easy access
• Cursor AI can open projects from this path

Access from Ubuntu Terminal:

cd ~/projects/your-project
docker run --rm -v $(pwd):/app your-image

Working with Git in WSL

If your project is stored in WSL, follow these best practices:

Initial Setup

When you first access a Git repository in WSL from Windows PowerShell, you might see:

fatal: detected dubious ownership in repository

Solution: Always run Git commands from the Ubuntu terminal, not PowerShell.

Set Up SSH for Git

If you’re using SSH for Git (like GitLab or GitHub):

1. Open Ubuntu terminal
2. Generate SSH key: ssh-keygen -t ed25519 -C "your_email@example.com" Press Enter to accept defaults
3. Copy your public key: cat ~/.ssh/id_ed25519.pub
4. Add the key to your Git hosting service:
   • GitHub: Settings ? SSH and GPG keys ? New SSH key
   • GitLab: User Settings ? SSH Keys
   • Paste your public key and save
5. Test the connection: # For GitHub ssh -T git@github.com # For GitLab ssh -T git@gitlab.com

Use SSH Agent (If Your Key Has a Passphrase)

To avoid entering your passphrase repeatedly:

# Start SSH agent
eval "$(ssh-agent -s)"

# Add your key
ssh-add ~/.ssh/id_ed25519

Enter your passphrase once – it will be cached for the session.

Make SSH Agent Start Automatically

Edit your bash profile:

nano ~/.bashrc

Add these lines at the end:

# Start SSH agent and add key
if [ -z "$SSH_AUTH_SOCK" ] ; then
  eval "$(ssh-agent -s)" > /dev/null
  ssh-add ~/.ssh/id_rsa 2>/dev/null
fi

Save (Ctrl+X, Y, Enter), then reload:

source ~/.bashrc

Fixing Git Line Ending Issues

If Git shows all files as modified after cloning, it’s likely a line ending issue (Windows uses CRLF, Linux uses LF).

Fix in Ubuntu Terminal

cd ~/your-project

# Configure Git to use Linux line endings
git config core.autocrlf input
git config core.filemode false

# Reset all files with correct line endings
git rm --cached -r .
git reset --hard HEAD

# Verify
git status

Prevent Future Issues

Create a .gitattributes file in your project root:

cat > .gitattributes << 'EOF'
* text=auto eol=lf
*.sh text eol=lf
EOF

git add .gitattributes
git commit -m "Add gitattributes to enforce LF line endings"

Recommended Workflow

For the best experience when using Cursor AI with WSL:

1. Store projects in Windows (C:\Users\YourUsername\Projects\)
2. Edit code in Cursor AI (Windows application)
3. Run Docker commands from either PowerShell or Ubuntu terminal
4. Run Git commands from Ubuntu terminal
5. Keep both Cursor AI and Ubuntu terminal open side-by-side

This workflow gives you the best of both worlds: easy editing with Windows tools and proper Linux environment for Docker and Git.

Common Docker Commands

Running Containers

# Run a container
docker run image-name

# Run with port mapping
docker run -p 4000:4000 image-name

# Run with volume mounting
docker run -v ${PWD}:/app image-name

# Run in detached mode
docker run -d image-name

Managing Containers

# List running containers
docker ps

# List all containers
docker ps -a

# Stop a container
docker stop container-id

# Remove a container
docker rm container-id

Managing Images

# List images
docker images

# Remove an image
docker rmi image-name

# Build an image
docker build -t my-image .

Docker Compose

# Start services
docker-compose up

# Start in detached mode
docker-compose up -d

# Stop services
docker-compose down

# View logs
docker-compose logs

Troubleshooting

Docker Desktop Won’t Start

• Ensure virtualization is enabled in BIOS
• Check that WSL 2 is properly installed: wsl --list --verbose
• Restart Docker Desktop
• Restart your computer

“Cannot connect to Docker daemon”

• Make sure Docker Desktop is running (check system tray)
• In Docker Desktop settings, verify WSL integration is enabled

Slow Performance

• Store projects in WSL filesystem instead of Windows for better performance
• Allocate more resources to Docker in Settings ? Resources

Git Shows All Files Modified

• Follow the line ending fix in the “Fixing Git Line Ending Issues” section above

Conclusion

You now have a fully functional Docker development environment on Windows 11! This setup allows you to:

• Run Docker containers efficiently using WSL 2
• Use your favorite Windows tools like Cursor AI for development
• Leverage Linux commands and tools through Ubuntu
• Manage Git repositories properly with SSH authentication

Happy coding!