centersl/docker-docs
1
0
Fork 0
mirror of https://github.com/docker/docs.git synced 2026-03-27 22:38:54 +07:00
Code Issues Packages Projects Releases Wiki Activity

Improve WSL 2 docs (#14766)

Browse Source 
* wsl2: removes need to manage VMs

Previously:
> allowing Linux containers to run natively without emulation.

Now:
> allowing Linux distributions to run without having to manage Virtual
> Machines

Signed-off-by: David Scott <dave.scott@docker.com>

* wsl2: remove reference to Docker Desktop "2.3.0.2"

This version is very old, the link was to the latest version.

Signed-off-by: David Scott <dave.scott@docker.com>

* wsl2: re-order to prereqs, download, install, best practices

Previously the best practices were before the Download, which is
a bit early. Now the page has

- why you should use this
- how you get it

and then

- how to optimize it

Signed-off-by: David Scott <dave.scott@docker.com>

* wsl2: clarify that Linux distros are recommended but not a pre-req

If there are no additional Linux distros installed then the docker
CLI and UI will work fine from Windows.

We recommend installing at least one Linux distro for optimal
performance.

Also add a warning about misusing the internal distros `docker-desktop`
and `docker-desktop-data`

Signed-off-by: David Scott <dave.scott@docker.com>
This commit is contained in:
David Scott
2022-05-18 15:53:51 +01:00
committed by GitHub
parent 0679956c5c
commit 861e079559
1 changed files with 62 additions and 49 deletions
Download Patch File Download Diff File Expand all files Collapse all files

111
desktop/windows/wsl.md
View File

@@ -14,7 +14,7 @@ title: Docker Desktop WSL 2 backend
> subscription.
{: .important}
Windows Subsystem for Linux (WSL) 2 introduces a significant architectural change as it is a full Linux kernel built by Microsoft, allowing Linux containers to run natively without emulation. With Docker Desktop running on WSL 2, users can leverage Linux workspaces and avoid having to maintain both Linux and Windows build scripts. In addition, WSL 2 provides improvements to file system sharing, boot time, and allows access to some cool new features for Docker Desktop users.
Windows Subsystem for Linux (WSL) 2 introduces a significant architectural change as it is a full Linux kernel built by Microsoft, allowing Linux distributions to run without having to manage Virtual Machines. With Docker Desktop running on WSL 2, users can leverage Linux workspaces and avoid having to maintain both Linux and Windows build scripts. In addition, WSL 2 provides improvements to file system sharing, boot time, and allows access to some cool new features for Docker Desktop users.
Docker Desktop uses the dynamic memory allocation feature in WSL 2 to greatly improve the resource consumption. This means, Docker Desktop only uses the required amount of CPU and memory resources it needs, while enabling CPU and memory-intensive tasks such as building a container to run much faster.
@@ -28,6 +28,67 @@ Before you install the Docker Desktop WSL 2 backend, you must complete the follo
2. Enable WSL 2 feature on Windows. For detailed instructions, refer to the [Microsoft documentation](https://docs.microsoft.com/en-us/windows/wsl/install-win10){:target="_blank" rel="noopener" class="_"}.
3. Download and install the [Linux kernel update package](https://docs.microsoft.com/windows/wsl/wsl2-kernel){:target="_blank" rel="noopener" class="_"}.
## Download
Download [Docker Desktop for Windows](https://desktop.docker.com/win/main/amd64/Docker%20Desktop%20Installer.exe).
## Install
Ensure you have completed the steps described in the Prerequisites section **before** installing the Docker Desktop release.
1. Follow the usual installation instructions to install Docker Desktop. If you are running a supported system, Docker Desktop prompts you to enable WSL 2 during installation. Read the information displayed on the screen and enable WSL 2 to continue.
2. Start Docker Desktop from the Windows Start menu.
3. From the Docker menu, select **Settings** > **General**.
![Enable WSL 2](images/wsl2-enable.png){:width="750px"}
4. Select the **Use WSL 2 based engine** check box.
If you have installed Docker Desktop on a system that supports WSL 2, this option will be enabled by default.
5. Click **Apply & Restart**.
That's it! Now `docker` commands will work from Windows using the new WSL 2 engine.
## Enabling Docker support in WSL 2 distros
WSL 2 adds support for "Linux distros" to Windows, where each distro behaves like a VM except they all run on top of a single shared Linux kernel.
Docker Desktop does not require any particular Linux distros to be installed. The `docker` CLI and UI all work fine from Windows without any additinoal Linux distros. However for the best developer experience, we recommend installing at least one additional distro and enabling Docker support by:
1. Ensure the distribution runs in WSL 2 mode. WSL can run distributions in both v1 or v2 mode.
To check the WSL mode, run:
`wsl.exe -l -v`
To upgrade your existing Linux distro to v2, run:
`wsl.exe --set-version (distro name) 2`
To set v2 as the default version for future installations, run:
`wsl.exe --set-default-version 2`
2. When Docker Desktop starts, go to **Settings** > **Resources** > **WSL Integration**.
The Docker-WSL integration will be enabled on your default WSL distribution. To change your default WSL distro, run `wsl --set-default <distro name>`.
For example, to set Ubuntu as your default WSL distro, run `wsl --set-default ubuntu`.
Optionally, select any additional distributions you would like to enable the Docker-WSL integration on.
> **Note**
>
> The Docker-WSL integration components running in your distro depend on glibc. This can cause issues when running musl-based distros such as Alpine Linux. Alpine users can use the [alpine-pkg-glibc](https://github.com/sgerrand/alpine-pkg-glibc){:target="_blank" rel="noopener" class="_"} package to deploy glibc alongside musl to run the integration.
![WSL 2 Choose Linux distro](images/wsl2-choose-distro.png)
3. Click **Apply & Restart**.
> **Note**
>
> Docker Desktop installs 2 special-purpose internal Linux distros `docker-desktop` and `docker-desktop-data`. The first (`docker-desktop`) is used to run the Docker engine (`dockerd`) while the second (`docker-desktop-data`) stores containers and images. Neither can be used for general development.
## Best practices
- To get the best out of the file system performance when bind-mounting files, we recommend storing source code and other data that is bind-mounted into Linux containers (i.e., with `docker run -v <host-path>:<container-path>`) in the Linux file system, rather than the Windows file system. You can also refer to the [recommendation](https://docs.microsoft.com/en-us/windows/wsl/compare-versions){:target="_blank" rel="noopener" class="_"} from Microsoft.
@@ -43,54 +104,6 @@ Before you install the Docker Desktop WSL 2 backend, you must complete the follo
- If you have concerns about CPU or memory usage, you can configure limits on the memory, CPU, Swap size allocated to the [WSL 2 utility VM](https://docs.microsoft.com/en-us/windows/wsl/wsl-config#global-configuration-options-with-wslconfig){:target="_blank" rel="noopener" class="_"}.
- To avoid any potential conflicts with using WSL 2 on Docker Desktop, you must [uninstall any previous versions of Docker Engine](../../engine/install/ubuntu.md#uninstall-docker-engine) and CLI installed directly through Linux distributions before installing Docker Desktop.
## Download
Download [Docker Desktop 2.3.0.2](https://desktop.docker.com/win/main/amd64/Docker%20Desktop%20Installer.exe) or a later release.
## Install
Ensure you have completed the steps described in the Prerequisites section **before** installing the Docker Desktop Stable 2.3.0.2 release.
1. Follow the usual installation instructions to install Docker Desktop. If you are running a supported system, Docker Desktop prompts you to enable WSL 2 during installation. Read the information displayed on the screen and enable WSL 2 to continue.
2. Start Docker Desktop from the Windows Start menu.
3. From the Docker menu, select **Settings** > **General**.
![Enable WSL 2](images/wsl2-enable.png){:width="750px"}
4. Select the **Use WSL 2 based engine** check box.
If you have installed Docker Desktop on a system that supports WSL 2, this option will be enabled by default.
5. Click **Apply & Restart**.
6. Ensure the distribution runs in WSL 2 mode. WSL can run distributions in both v1 or v2 mode.
To check the WSL mode, run:
`wsl.exe -l -v`
To upgrade your existing Linux distro to v2, run:
`wsl.exe --set-version (distro name) 2`
To set v2 as the default version for future installations, run:
`wsl.exe --set-default-version 2`
7. When Docker Desktop restarts, go to **Settings** > **Resources** > **WSL Integration**.
The Docker-WSL integration will be enabled on your default WSL distribution. To change your default WSL distro, run `wsl --set-default <distro name>`.
For example, to set Ubuntu as your default WSL distro, run `wsl --set-default ubuntu`.
Optionally, select any additional distributions you would like to enable the Docker-WSL integration on.
> **Note**
>
> The Docker-WSL integration components running in your distro depend on glibc. This can cause issues when running musl-based distros such as Alpine Linux. Alpine users can use the [alpine-pkg-glibc](https://github.com/sgerrand/alpine-pkg-glibc){:target="_blank" rel="noopener" class="_"} package to deploy glibc alongside musl to run the integration.
![WSL 2 Choose Linux distro](images/wsl2-choose-distro.png)
8. Click **Apply & Restart**.
## Develop with Docker and WSL 2
The following section describes how to start developing your applications using Docker and WSL 2. We recommend that you have your code in your default Linux distribution for the best development experience using Docker and WSL 2. After you have enabled WSL 2 on Docker Desktop, you can start working with your code inside the Linux distro and ideally with your IDE still in Windows. This workflow can be pretty straightforward if you are using [VSCode](https://code.visualstudio.com/download).