Improve documentation for using the local Docker environment on Windows

[desrosj]

The README.md file has some basic instructions for getting the local Docker development environment up and running. Unfortunately, the instructions do not work on Windows. While it does take a bit more effort, the environment can run on Windows. These extra steps should be better documented.

[Clorith]

As Windows has some particular quirks, especially when interacting with Linux images for Docker, it is generally recommended to use Windows Subsystem for Linux (WSL) if possible, or at least change the Docker engine to use Linux over Windows binaries, so ensure compatibility.

Although there are some scenarios where running in experimental mode will let the environments load as intended, experimental is obviously not a great things to expect contributors to run. I've gathered together some suggested wording that can be added alongside the instructions for setting up a local environment in our readme:

#### Windows specific instructions

For development on Windows, it is recommended to use the [Windows Subsystem for Linux (WSL)](https://learn.microsoft.com/en-us/windows/wsl/install), as this gives you access to a Linux environment, where the general recommendations and guides will work without any modifications.

You will then only need to enable the docker WSL integration, this is found under "Settings > Resources > WSL integration", and is a one time operation the first time after you install Docker.


If you wish to use Windows directly without WSL, start by installing Docker as in the previous instructions. Once the installation is completed, right click the Docker icon in your system tray, and choose the option "Switch to Linux containers...", and wait for Docker to restart. If this option is not present, or you only see "Switch to windows containers...", then you are already using the appropriate configuration, and can start your development environment. If you have other projects that rely on the Windows engine, you can easily swap back the same way.

This switch to the Linux engine is to ensure that the development environment runs the same Docker images as the environments were built with, ensuring it works across all contributor environments

[poena]

could you add any details about how you get the environment up and running successfully on Windows

I use WSL. I don't recall other steps, since I set them once and forgot.

[karthikeya01]

I had tried setting up on my Windows machine following the instructions in README, I didn't face any issues (I have WSL 2 installed already). I tried unchecking use WSL 2 based engine to check if it can cause issue but I can't even uncheck it.

I think for latest Windows versions Docker uses WSL backend by default to setup.
​https://docs.docker.com/desktop/features/wsl/#:~:text=Depending%20on%20which%20version%20of%20Windows%20you%20are%20using%2C%20Docker%20Desktop%20may%20prompt%20you%20to%20turn%20on%20WSL%202%20during%20installation.

[SirLouen]

Replying to karthikeya01:

I think for latest Windows versions Docker uses WSL backend by default to setup.

I can confirm as @karthikeya01 said that there are no issues with the basic setup both in Windows PowerShell and inside the WSL (Ubuntu in my case) shell.

Once I tried running over Hyper-V with VMWare and was a little tricky because you have to configure docker connection to access "remotely" to the VM, its well handled by docker desktop.

For nested virtualization, I have no idea on how it runs, but also seems to be possible: ​https://docs.docker.com/desktop/setup/vm-vdi/

Mainly I believe that instead of adding "installation notes" for each system, I think its OK as it's currently explained:

You will also need Docker installed and running on your computer. Docker is the virtualization software that powers the local development environment. Docker can be installed just like any other regular application.

As long as you can run docker in whatever shell you use, you have your npm set-up, no extra instructions are needed. Docker Desktop can be mentioned.

Instead of using choco I think the more modern aproach could be also commented with winget

winget install -e --id Docker.DockerDesktop

And for NPM, winget also installing fnm: ​https://nodejs.org/en/download/ (reminding to use a lesser version of NPM).

Finally, the only trouble is the file permissions part. Maybe some information could be expanded on this topic. By default, you will not be able to play around with files and folders within the working WP installation, not even with fs_method direct (it will trigger the Connection Information). This is mainly why I work directly on the WSL2 container and not over my Windows Filesystem (for Windows testing I prefer to use FlyEnv).

[sachinrajcp123]

This patch improves the documentation for setting up the local Docker development environment on Windows. 🔹 Issue: The current README.md lacks platform-specific guidance for Windows users, which can cause setup issues and confusion. 🔹 Fix: Adds a dedicated section outlining the prerequisites and installation steps for Windows users. Includes basic troubleshooting notes for common Windows-specific issues. 🔹 Impact: Makes the onboarding process smoother for contributors and developers using Windows.

on Windows.

This PR addresses Trac ticket #62196 by updating the README.md to include necessary Windows-specific configuration and troubleshooting steps for the local Docker development environment. This includes guidance on:

• Setting Git to handle line endings correctly (core.autocrlf input).
• The recommended use of WSL 2 for better performance and file permissions.
• Ensuring the correct drives are enabled for file sharing in Docker Desktop.

This resolves issues encountered by developers attempting to set up the environment natively on a Windows host.

Trac ticket: https://core.trac.wordpress.org/ticket/62196

This PR addresses ticket #62196 by improving the documentation for setting up the local Docker development environment on Windows.

I've noted that the primary bottleneck for Windows users in Docker environments is often the filesystem performance (NTFS mount). This update explicitly recommends using the WSL2 backend and ensures users understand that project files should be kept within the Linux filesystem (e.g.,
wsl$\...) to avoid significant performance degradation.

Trac ticket: #62196

## Use of AI Tools

I'm currently using Github Copilot, not used in this PR, but it's in my code editor, so decided to tell it here ;)

[marcelloruoppolome]

I've submitted a PR to the README.md file adding specific recommendations for Windows users to use the WSL2 filesystem for better performance, as discussed in this ticket. PR: ​https://github.com/WordPress/wordpress-develop/pull/10933