docker-magento documentation for Windows with WSL2

This guide provides comprehensive instructions for running docker-magento on Windows using WSL2. While docker-magento was primarily designed for Mac and Linux, it can work excellently on Windows with proper configuration.

Prerequisites
System Requirements
Initial Windows & WSL2 Setup
Docker Desktop Configuration
Project Setup
SSL Certificate Configuration
Performance Optimization
IDE Configuration
- PhpStorm Setup
- VS Code Setup
Common Issues and Solutions
Best Practices

Prerequisites

This guide assumes you:

Have Docker Desktop installed on Windows
Know how to install and use WSL2
Have basic knowledge of Docker
Are using Windows 10/11 Pro, Enterprise, or Home (with WSL2 support)

System Requirements

Windows Requirements

Windows 10: Version 1903 or higher (Build 18362 or higher) for x64 systems
Windows 10: Version 2004 or higher (Build 19041 or higher) for ARM64 systems
Windows 11: Any version
RAM: Minimum 16GB system RAM (32GB recommended)
CPU: Minimum dual-core (6+ cores recommended)
Storage: SSD strongly recommended

Docker Desktop Requirements

Requires Microsoft Windows 10 Professional or Enterprise 64-bit, or Windows 10 Home 64-bit with WSL2
Docker Desktop 4.x or higher

Initial Windows & WSL2 Setup

1. Enable Required Windows Features

Open PowerShell as Administrator and run:

# Enable Windows Subsystem for Linux
dism.exe /online /enable-feature /featurename:Microsoft-Windows-Subsystem-Linux /all /norestart

# Enable Virtual Machine Platform
dism.exe /online /enable-feature /featurename:VirtualMachinePlatform /all /norestart

# Enable Containers (for Docker)
Enable-WindowsOptionalFeature -Online -FeatureName containers -All

# Enable Hyper-V
Enable-WindowsOptionalFeature -Online -FeatureName Microsoft-Hyper-V -All

REBOOT YOUR SYSTEM after running these commands.

2. Install WSL2 Linux Kernel

After reboot, install the Linux kernel update package:

For x64 machines: Download x64 WSL2 Kernel
For ARM64 machines: Download ARM64 WSL2 Kernel

3. Set WSL2 as Default

Open PowerShell as Administrator:

wsl --set-default-version 2

4. Install Ubuntu

Install Ubuntu from the Microsoft Store:

Ubuntu 22.04 LTS (Recommended)
Or Ubuntu 20.04 LTS

5. Install Windows Terminal

Install Windows Terminal from the Microsoft Store for a better command-line experience.

6. Configure WSL Memory

Create a .wslconfig file in your Windows user directory (C:\Users\YourUsername\.wslconfig):

[wsl2]
memory=16GB
processors=6
swap=2GB

Adjust values based on your system. After creating this file:

Open PowerShell as Administrator
Run: wsl --shutdown
Wait 8 seconds before starting WSL again

Docker Desktop Configuration

1. Install Docker Desktop

Download and install Docker Desktop for Windows.

2. Configure Docker Desktop

Open Docker Desktop settings
Go to General and ensure "Use the WSL 2 based engine" is checked
Go to Resources > WSL Integration:
- Enable integration with your Ubuntu distro
- Check "Enable integration with my default WSL distro"
Go to Resources > Advanced:
- Memory: Allocate at least 6GB (8GB+ recommended)
- CPUs: Allocate at least 4 CPUs
Apply & Restart Docker Desktop

3. Verify Docker in WSL

Open Windows Terminal, select your Ubuntu profile, and verify Docker is accessible:

docker --version
docker run hello-world

Project Setup

1. Install Required Dependencies in Ubuntu

Open Ubuntu terminal and run:

sudo apt update
sudo apt install -y \
    curl \
    libnss3-tools \
    unzip \
    rsync \
    bc \
    jq

2. Fix Line Endings Issue

CRITICAL: Windows uses CRLF line endings while Linux uses LF. This causes "file not found" errors.

Create a .gitconfig in your WSL home directory:

nano ~/.gitconfig

Add:

[core]
    autocrlf = false
    eol = lf

3. Create Project Directory

IMPORTANT: Always create projects within the WSL filesystem for performance:

cd ~
mkdir -p Sites/magento
cd Sites/magento

4. Download and Setup Docker-Magento

# Download the Docker Compose template
curl -s https://raw.githubusercontent.com/markshust/docker-magento/master/lib/template | bash

# Fix line endings in all bin files
find ./bin -type f -exec sed -i 's/\r$//' {} +
find ./env -type f -exec sed -i 's/\r$//' {} +

5. Download Magento

bin/download 2.4.8-p1

6. Configure Hosts File

You need to add entries to both Windows and WSL hosts files.

WSL hosts file:

echo "127.0.0.1 ::1 magento.test" | sudo tee -a /etc/hosts

Windows hosts file:

Open Notepad as Administrator
Open C:\Windows\System32\drivers\etc\hosts
Add: 127.0.0.1 magento.test

7. Setup Magento

bin/setup magento.test

If you encounter "chmod: cannot access 'bin/magento': No such file or directory":

bin/copytocontainer --all
bin/setup magento.test

SSL Certificate Configuration

SSL certificates require special handling on Windows.

1. Generate SSL Certificate

bin/setup-ssl magento.test

2. Import Certificate to Windows

Open PowerShell as Administrator:

# Convert PEM to CRT (adjust path to your project)
& 'C:\Program Files\Git\usr\bin\openssl.exe' x509 -outform der -in \\wsl.localhost\Ubuntu\home\yourusername\Sites\magento\rootCA.pem -out rootca.crt

# Import to Windows certificate store
Import-Certificate -FilePath .\rootca.crt -CertStoreLocation Cert:\LocalMachine\Root\

3. Configure Browsers

Chrome

Restart Chrome: Navigate to chrome://restart
The certificate should now be trusted

Firefox

Navigate to about:config
Set security.enterprise_roots.enabled to true
Restart Firefox

Performance Optimization

1. Use WSL Filesystem

CRITICAL: Always keep your files in the WSL filesystem (~/Sites/magento), NOT in Windows directories (/mnt/c/...). Windows filesystem access from WSL is extremely slow.

2. Update Docker Compose for Linux

Use the Linux-optimized compose file:

cp compose.dev-linux.yaml compose.dev.yaml

3. Disable Windows Defender for WSL

Windows Defender can significantly slow down file operations. Add an exclusion:

Open Windows Security
Go to Virus & threat protection > Manage settings
Add exclusion for: \\wsl.localhost\Ubuntu\home\yourusername\Sites

4. Enable Docker BuildKit

Add to your WSL ~/.bashrc:

export DOCKER_BUILDKIT=1
export COMPOSE_DOCKER_CLI_BUILD=1

IDE Configuration

PhpStorm Setup

1. Open Project from WSL

In PhpStorm, open project from:

\\wsl.localhost\Ubuntu\home\yourusername\Sites\magento

Or use WSL path:

\\wsl$\Ubuntu\home\yourusername\Sites\magento

2. Configure PHP Interpreter

Go to File > Settings > PHP
Click "..." next to CLI Interpreter
Add new interpreter: From Docker, Vagrant, VM...
Select Docker Compose
Configuration:
- Server: Docker
- Configuration files: Select both compose.yaml and compose.dev.yaml
- Service: phpfpm
Name it "Docker PHP" and apply

3. Configure Deployment for Code Synchronization

Go to File > Settings > Build, Execution, Deployment > Deployment
Add new deployment configuration (Type: SFTP)
Connection settings:
- SFTP host: localhost
- Port: 22
- User name: app
- Password: app
- Root path: /var/www/html
Mappings tab:
- Local path: Your project root
- Deployment path: /

4. Configure Xdebug

Install Xdebug Helper for Chrome
In Chrome extension options, set IDE key to PHPSTORM
Enable Xdebug in container:
```
bin/xdebug enable
```
In PhpStorm, go to File > Settings > PHP > Debug:
- Debug port: 9000,9003
Create a server in PHP > Servers:
- Name: magento.test
- Host: magento.test
- Port: 80
- Debugger: Xdebug
- Use path mappings: Check and map src to /var/www/html

5. Configure Quality Tools

Go to File > Settings > PHP > Quality Tools:

For each tool (PHP_CodeSniffer, Mess Detector, etc.):

Click "..." next to Configuration
Select "By Docker Interpreter"
Choose your Docker interpreter
Set paths (replace yourusername):
- PHP_CodeSniffer: /home/yourusername/Sites/magento/src/vendor/bin/phpcs
- PHP CS Fixer: /home/yourusername/Sites/magento/src/vendor/bin/php-cs-fixer
- Mess Detector: /home/yourusername/Sites/magento/src/vendor/bin/phpmd

VS Code Setup

1. Install WSL Extension

Install the "WSL" extension in VS Code.

2. Open Project in WSL

Open VS Code
Press Ctrl+Shift+P
Run "WSL: Connect to WSL"
Open folder: ~/Sites/magento

3. Configure PHP Debug

Install "PHP Debug" extension by Felix Becker
Create .vscode/launch.json:

{
    "version": "0.2.0",
    "configurations": [
        {
            "name": "Listen for Xdebug",
            "type": "php",
            "request": "launch",
            "port": 9003,
            "pathMappings": {
                "/var/www/html": "${workspaceFolder}/src"
            },
            "hostname": "localhost"
        }
    ]
}

4. Enable Xdebug

bin/xdebug enable

5. Configure Windows Firewall for Xdebug

Open PowerShell as Administrator:

New-NetFirewallRule -DisplayName "WSL" -Direction Inbound -InterfaceAlias "vEthernet (WSL)" -Action Allow

Common Issues and Solutions

1. "There must be at least 6GB of RAM allocated to Docker"

Even with .wslconfig, this check might fail. The check is in bin/download. If you've properly configured Docker resources, you can comment out the memory check temporarily.

2. 403 Forbidden Errors

If you get 403 errors when accessing the site:

# Fix permissions
bin/fixowns
bin/fixperms

# Restart containers
bin/restart

3. "No such file or directory" Errors

This is almost always a line endings issue:

# Fix line endings for all shell scripts
find ./bin -type f -exec dos2unix {} \;
# Or if dos2unix is not installed:
find ./bin -type f -exec sed -i 's/\r$//' {} +

4. Slow Performance

Ensure you're:

Using the WSL filesystem (not /mnt/c/)
Have adequate resources allocated in .wslconfig
Have excluded WSL paths from Windows Defender
Not syncing large directories like vendor/ or generated/ from Windows

5. Composer/Curl Issues

If you encounter network issues:

# Disable IPv6 if causing issues
sudo sysctl -w net.ipv6.conf.all.disable_ipv6=1
sudo sysctl -w net.ipv6.conf.default.disable_ipv6=1

# Set DNS servers
echo "nameserver 1.1.1.1" | sudo tee /etc/resolv.conf
echo "nameserver 8.8.8.8" | sudo tee -a /etc/resolv.conf

6. Windows PATH Interference

If Windows paths interfere with WSL:

Create /etc/wsl.conf in WSL:

sudo nano /etc/wsl.conf

Add:

[interop]
appendWindowsPath = false

Then restart WSL:

wsl --shutdown

7. Clock Sync Issues

WSL clock can drift, affecting SSL:

sudo hwclock -s

Best Practices

1. File Location

ALWAYS use WSL filesystem for projects
Access from Windows via \\wsl.localhost\Ubuntu\home\username\Sites
Never use /mnt/c/ for project files

2. Git Configuration

Configure Git in WSL, not Windows
Use SSH keys generated in WSL
Set proper line endings in .gitconfig

3. Regular Maintenance

Keep Docker Desktop updated
Regularly update WSL: wsl --update
Monitor disk usage: docker system df
Clean up periodically: docker system prune -a

4. Backups

Use Windows tools to backup WSL files via \\wsl.localhost\
Consider using wsl --export for full WSL backups

5. Terminal Usage

Use Windows Terminal with Ubuntu profile
Avoid mixing Windows and WSL commands
Run all docker-magento commands from WSL

Final Steps

After completing setup:

Access Magento at: https://magento.test
Admin panel: https://magento.test/admin
- Username: john.smith
- Password: password123
Mailcatcher: http://magento.test:1080
PhpMyAdmin: http://localhost:8080

Troubleshooting Checklist

If something isn't working:

Are you in WSL Ubuntu terminal (not Windows)?
Are files in WSL filesystem (not /mnt/c/)?
Did you fix line endings in bin/ files?
Is Docker Desktop running with WSL2 integration?
Did you add hosts entries to both Windows and WSL?
Did you allocate enough resources in .wslconfig?
Have you restarted WSL after configuration changes?
Are you using the correct URL (https://magento.test)?

Remember: Most issues on Windows stem from line endings, file permissions, or using Windows filesystem instead of WSL filesystem.

markshust/README.md

docker-magento documentation for Windows with WSL2

Table of Contents

Prerequisites

System Requirements

Windows Requirements

Docker Desktop Requirements

Initial Windows & WSL2 Setup

1. Enable Required Windows Features

2. Install WSL2 Linux Kernel

3. Set WSL2 as Default

4. Install Ubuntu

5. Install Windows Terminal

6. Configure WSL Memory

Docker Desktop Configuration

1. Install Docker Desktop

2. Configure Docker Desktop

3. Verify Docker in WSL

Project Setup

1. Install Required Dependencies in Ubuntu

2. Fix Line Endings Issue

3. Create Project Directory

4. Download and Setup Docker-Magento

5. Download Magento

6. Configure Hosts File

WSL hosts file:

Windows hosts file:

7. Setup Magento

SSL Certificate Configuration

1. Generate SSL Certificate

2. Import Certificate to Windows

3. Configure Browsers

Chrome

Firefox

Performance Optimization

1. Use WSL Filesystem

2. Update Docker Compose for Linux

3. Disable Windows Defender for WSL

4. Enable Docker BuildKit

IDE Configuration

PhpStorm Setup

1. Open Project from WSL

2. Configure PHP Interpreter

3. Configure Deployment for Code Synchronization

4. Configure Xdebug

5. Configure Quality Tools

VS Code Setup

1. Install WSL Extension

2. Open Project in WSL

3. Configure PHP Debug

4. Enable Xdebug

5. Configure Windows Firewall for Xdebug

Common Issues and Solutions

1. "There must be at least 6GB of RAM allocated to Docker"

2. 403 Forbidden Errors

3. "No such file or directory" Errors

4. Slow Performance

5. Composer/Curl Issues

6. Windows PATH Interference

7. Clock Sync Issues

Best Practices

1. File Location

2. Git Configuration

3. Regular Maintenance

4. Backups

5. Terminal Usage

Final Steps

Troubleshooting Checklist