mirror of https://github.com/docker/docs.git
Docs freshness (#16430)
* docs freshness for desktop troubleshoot * docs freshness for desktop get started * docs freshness for desktop wsl * fixes from review
This commit is contained in:
Allie Sadler
GitHub
parent
c31420f0b4
commit
edf8fa9529
|
|
@ -33,7 +33,7 @@ redirect_from:
|
|||
|
||||
|
||||
|
||||
To run the Quick Start Guide on demand, select {: .inline} and then choose **Quick Start Guide**.
|
||||
To run the Quick Start Guide on demand, select the Docker menu {: .inline} and then choose **Quick Start Guide**.
|
||||
|
||||
For a more detailed guide, see [Get started](../get-started/index.md).
|
||||
|
||||
|
|
@ -49,17 +49,17 @@ In large enterprises where admin access is restricted, administrators can create
|
|||
|
||||
### Two-factor authentication
|
||||
|
||||
Docker Desktop enables you to sign in to Docker Hub using two-factor authentication. Two-factor authentication provides an extra layer of security when accessing your Docker Hub account.
|
||||
Docker Desktop lets you to sign in to Docker Hub using two-factor authentication. Two-factor authentication provides an extra layer of security when accessing your Docker Hub account.
|
||||
|
||||
You must enable two-factor authentication in Docker Hub before signing into your Docker Hub account through Docker Desktop. For instructions, see [Enable two-factor authentication for Docker Hub](/docker-hub/2fa/).
|
||||
You must turn on two-factor authentication in Docker Hub before signing into your Docker Hub account through Docker Desktop. For instructions, see [Enable two-factor authentication for Docker Hub](/docker-hub/2fa/).
|
||||
|
||||
After two-factor authentication is enabled:
|
||||
After two-factor authentication is turned on:
|
||||
|
||||
1. Go to the Docker Desktop menu and then select **Sign in / Create Docker ID**.
|
||||
|
||||
2. Enter your Docker ID and password and click **Sign in**.
|
||||
2. Enter your Docker ID and password and select **Sign in**.
|
||||
|
||||
3. After you have successfully signed in, Docker Desktop prompts you to enter the authentication code. Enter the six-digit code from your phone and then click **Verify**.
|
||||
3. After you have successfully signed in, Docker Desktop prompts you to enter the authentication code. Enter the six-digit code from your phone and then select **Verify**.
|
||||
|
||||
### Credentials management for Linux users
|
||||
|
||||
|
|
@ -67,10 +67,15 @@ Docker Desktop relies on [`pass`](https://www.passwordstore.org/){: target="_bla
|
|||
Before signing in to Docker Hub from the Docker Dashboard or the Docker menu, you must initialize `pass`.
|
||||
Docker Desktop displays a warning if you've not initialized `pass`.
|
||||
|
||||
You can intialize pass by using a gpg key. To generate a gpg key, run:
|
||||
You can initialize pass by using a gpg key. To generate a gpg key, run:
|
||||
|
||||
``` console
|
||||
$ gpg --generate-key
|
||||
```
|
||||
|
||||
Below is an example similar to what you see once you run the above command:
|
||||
|
||||
```console
|
||||
...
|
||||
GnuPG needs to construct a user ID to identify your key.
|
||||
|
||||
|
|
@ -87,10 +92,14 @@ uid Molly <molly@example.com>
|
|||
sub rsa3072 2022-03-31 [E] [expires: 2024-03-30]
|
||||
```
|
||||
|
||||
To initialize `pass`, run the following command using the public key generated from the previous command
|
||||
To initialize `pass`, run the following command using the public key generated from the previous command:
|
||||
|
||||
```console
|
||||
$ pass init <generated gpg-id public key>
|
||||
```
|
||||
Below is an example similar to what you see once you run the above command:
|
||||
|
||||
```console
|
||||
molly@ubuntu:~$ pass init <generated gpg-id public key>
|
||||
mkdir: created directory '/home/molly/.password-store/'
|
||||
Password store initialized for <generated gpg-id public key>
|
||||
```
|
||||
|
|
@ -107,7 +116,7 @@ Digest: sha256:3c6b73ce467f04d4897d7a7439782721fd28ec9bf62ea2ad9e81a5fb7fb3ff96
|
|||
Status: Downloaded newer image for molly/privateimage:latest
|
||||
docker.io/molly/privateimage:latest
|
||||
```
|
||||
## Where to go next
|
||||
## What's next?
|
||||
|
||||
- [Explore Docker Desktop](use-desktop/index.md) and its features.
|
||||
- Change your Docker Desktop settings
|
||||
|
|
|
|||
|
|
@ -18,17 +18,14 @@ redirect_from:
|
|||
target-url="https://www.docker.com/pricing?utm_source=docker&utm_medium=webreferral&utm_campaign=docs_driven_upgrade_desktop_support"
|
||||
%}
|
||||
|
||||
This page contains information on:
|
||||
- How to diagnose and troubleshoot Docker Desktop issues
|
||||
- Check the logs
|
||||
- Find workarounds for common problems
|
||||
This page contains information on how to diagnose and troubleshoot Docker Desktop issues and how to check the logs
|
||||
|
||||
## Troubleshoot menu
|
||||
|
||||
To navigate to **Troubleshoot** either:
|
||||
|
||||
- Select the Docker menu {: .inline} and then **Troubleshoot**
|
||||
- Select the **Troubleshoot** icon from the Docker Dashboard
|
||||
- Select the **Troubleshoot** icon near the top-right corner of Docker Dashboard
|
||||
|
||||
{:width="600px"}
|
||||
|
||||
|
|
@ -40,7 +37,7 @@ The Troubleshoot page contains the following options:
|
|||
|
||||
- **Reset Kubernetes cluster**. Select to delete all stacks and Kubernetes resources. For more information, see [Kubernetes](../settings/linux.md#kubernetes).
|
||||
|
||||
- **Clean / Purge data**. This option resets all Docker data _without_ a
|
||||
- **Clean / Purge data**. This option resets all Docker data without a
|
||||
reset to factory defaults. Selecting this option results in the loss of existing settings.
|
||||
|
||||
- **Reset to factory defaults**: Choose this option to reset all options on
|
||||
|
|
@ -57,16 +54,16 @@ Make sure you are signed in to Docker Desktop and your [Docker Hub](https://hub.
|
|||
1. From **Troubleshoot**, select **Get support**.
|
||||
This opens the in-app **Support** page and starts collecting the diagnostics.
|
||||
{:width="600px"}
|
||||
2. When the diagnostics collection process is complete, click **Upload to get a Diagnostic ID**.
|
||||
3. When the diagnostics have been uploaded, Docker Desktop prints a diagnostic ID. Copy this ID.
|
||||
4. If you have a paid Docker subscription, click **Contact Support**. This opens the [Docker Desktop support](https://hub.docker.com/support/desktop/){:target="_blank" rel="noopener" class="_"} form. Fill in the information required and add the ID you copied in step four to the **Diagnostics ID** field.
|
||||
5. Click **Submit** to request Docker Desktop support.
|
||||
2. When the diagnostics collection process is complete, select **Upload to get a Diagnostic ID**.
|
||||
3. When the diagnostics are uploaded, Docker Desktop prints a diagnostic ID. Copy this ID.
|
||||
4. If you have a paid Docker subscription, select **Contact Support**. This opens the [Docker Desktop support](https://hub.docker.com/support/desktop/){:target="_blank" rel="noopener" class="_"} form. Fill in the information required and add the ID you copied in step three to the **Diagnostics ID** field.
|
||||
5. Select **Submit** to request Docker Desktop support.
|
||||
> **Note**
|
||||
>
|
||||
> You must be signed in to Docker Desktop using your Pro, Team, or Business tier credentials to access the support form. For information on what's covered as part of Docker Desktop support, see [Support](../../support/index.md).
|
||||
6. If you don't have a paid Docker subscription, click **Upgrade to benefit from Docker Support** to upgrade your existing account.
|
||||
Alternatively, click **Report a Bug** to open a new Docker Desktop issue on GitHub. Complete the information required and ensure you add the diagnostic ID you copied earlier.
|
||||
7. Click **submit new issue** to create a new issue.
|
||||
6. If you don't have a paid Docker subscription, select **Upgrade to benefit from Docker Support** to upgrade your existing account.
|
||||
Alternatively, select **Report a Bug** to open a new Docker Desktop issue on GitHub. Complete the information required and ensure you add the diagnostic ID you copied earlier.
|
||||
7. Select **submit new issue** to create a new issue.
|
||||
|
||||
### Diagnose from the terminal
|
||||
|
||||
|
|
@ -137,7 +134,7 @@ $ unzip –l /tmp/BE9AFAAF-F68B-41D0-9D12-84760E6B8740/20190905152051.zip
|
|||
</div>
|
||||
</div>
|
||||
|
||||
If you have a paid Docker subscription, open the [Docker Desktop support](https://hub.docker.com/support/desktop/){:target="_blank" rel="noopener" class="_"} form. Fill in the information required and add the ID to the Diagnostics ID field. Click **Submit** to request Docker Desktop support.
|
||||
If you have a paid Docker subscription, open the [Docker Desktop support](https://hub.docker.com/support/desktop/){:target="_blank" rel="noopener" class="_"} form. Fill in the information required and add the ID to the Diagnostics ID field. Select **Submit** to request Docker Desktop support.
|
||||
|
||||
### Self-diagnose tool
|
||||
|
||||
|
|
@ -182,7 +179,7 @@ $ <tool location> check
|
|||
|
||||
The tool runs a suite of checks and displays **PASS** or **FAIL** next to each check. If there are any failures, it highlights the most relevant at the end of the report.
|
||||
|
||||
You can then create and issue on GitHub:
|
||||
You can then create an issue on GitHub:
|
||||
- [For Linux](https://github.com/docker/desktop-linux/issues){:target="_blank" rel="noopener" class="_"}
|
||||
- [For Mac](https://github.com/docker/for-mac/issues){:target="_blank" rel="noopener" class="_"}
|
||||
- [For Windows](https://github.com/docker/for-win/issues){:target="_blank" rel="noopener" class="_"}
|
||||
|
|
@ -200,7 +197,7 @@ In addition to using the diagnose option to submit logs, you can browse the logs
|
|||
|
||||
### In a terminal
|
||||
|
||||
To watch the live flow of Docker Desktop logs in the command line, run the following script from your favorite shell.
|
||||
To watch the live flow of Docker Desktop logs in the command line, run the following script from your preferred shell.
|
||||
|
||||
```console
|
||||
$ pred='process matches ".*(ocker|vpnkit).*" || (process in {"taskgated-helper", "launchservicesd", "kernel"} && eventMessage contains[c] "docker")'
|
||||
|
|
|
|||
|
|
@ -7,37 +7,32 @@ redirect_from:
|
|||
title: Docker Desktop WSL 2 backend on Windows
|
||||
---
|
||||
|
||||
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.
|
||||
Windows Subsystem for Linux (WSL) 2 is a full Linux kernel built by Microsoft, which allows Linux distributions to run without managing virtual machines. With Docker Desktop running on WSL 2, users can leverage Linux workspaces and avoid maintaining both Linux and Windows build scripts. In addition, WSL 2 provides improvements to file system sharing and boot time.
|
||||
|
||||
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.
|
||||
Docker Desktop uses the dynamic memory allocation feature in WSL 2 to 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.
|
||||
|
||||
Additionally, with WSL 2, the time required to start a Docker daemon after a cold start is significantly faster. It takes less than 10 seconds to start the Docker daemon when compared to almost a minute in the previous version of Docker Desktop.
|
||||
Additionally, with WSL 2, the time required to start a Docker daemon after a cold start is significantly faster. It takes less than 10 seconds to start the Docker daemon compared to almost a minute in the previous version of Docker Desktop.
|
||||
|
||||
## Prerequisites
|
||||
|
||||
Before you install the Docker Desktop WSL 2 backend, you must complete the following steps:
|
||||
Before you turn on the Docker Desktop WSL 2, ensure you have:
|
||||
|
||||
1. Install Windows 10, version 1903 or higher or Windows 11.
|
||||
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="_"}.
|
||||
- Windows 10, version 1903 or higher, or Windows 11.
|
||||
- Enabled 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="_"}.
|
||||
- Downloaded and installed the [Linux kernel update package](https://docs.microsoft.com/windows/wsl/wsl2-kernel){:target="_blank" rel="noopener" class="_"}.
|
||||
|
||||
## Download
|
||||
## Turn on Docker Desktop WSL 2
|
||||
|
||||
Download [Docker Desktop for Windows](https://desktop.docker.com/win/main/amd64/Docker%20Desktop%20Installer.exe).
|
||||
1. Download [Docker Desktop for Windows](https://desktop.docker.com/win/main/amd64/Docker%20Desktop%20Installer.exe).
|
||||
2. 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.
|
||||
3. Start Docker Desktop from the Windows Start menu.
|
||||
4. From the Docker menu, select **Settings** and then **General**.
|
||||
5. Select the **Use WSL 2 based engine** check box.
|
||||
|
||||
## Install
|
||||
If you have installed Docker Desktop on a system that supports WSL 2, this option is enabled by default.
|
||||
6. Select **Apply & Restart**.
|
||||
|
||||
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**.
|
||||
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.
|
||||
Now `docker` commands work from Windows using the new WSL 2 engine.
|
||||
|
||||
## Enabling Docker support in WSL 2 distros
|
||||
|
||||
|
|
@ -49,21 +44,31 @@ Docker Desktop does not require any particular Linux distros to be installed. Th
|
|||
|
||||
To check the WSL mode, run:
|
||||
|
||||
`wsl.exe -l -v`
|
||||
```console
|
||||
$ wsl.exe -l -v
|
||||
```
|
||||
|
||||
To upgrade your existing Linux distro to v2, run:
|
||||
|
||||
`wsl.exe --set-version (distro name) 2`
|
||||
```console
|
||||
$ wsl.exe --set-version (distro name) 2
|
||||
```
|
||||
|
||||
To set v2 as the default version for future installations, run:
|
||||
|
||||
`wsl.exe --set-default-version 2`
|
||||
```console
|
||||
$ 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>`.
|
||||
The Docker-WSL integration is 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`.
|
||||
For example, to set Ubuntu as your default WSL distro, run:
|
||||
|
||||
```console
|
||||
$ wsl --set-default ubuntu
|
||||
```
|
||||
|
||||
Optionally, select any additional distributions you would like to enable the Docker-WSL integration on.
|
||||
|
||||
|
|
@ -71,42 +76,46 @@ Docker Desktop does not require any particular Linux distros to be installed. Th
|
|||
>
|
||||
> 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.
|
||||
|
||||
3. Click **Apply & Restart**.
|
||||
3. Select **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.
|
||||
> Docker Desktop installs two 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.
|
||||
- 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, for instance 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.
|
||||
|
||||
- Linux containers only receive file change events ("inotify events") if the
|
||||
- Linux containers only receive file change events, "inotify events", if the
|
||||
original files are stored in the Linux filesystem. For example, some web development workflows rely on inotify events for automatic reloading when files have changed.
|
||||
- Performance is much higher when files are bind-mounted from the Linux
|
||||
filesystem, rather than remoted from the Windows host. Therefore avoid
|
||||
`docker run -v /mnt/c/users:/users` (where `/mnt/c` is mounted from Windows).
|
||||
`docker run -v /mnt/c/users:/users`, where `/mnt/c` is mounted from Windows.
|
||||
- Instead, from a Linux shell use a command like `docker run -v ~/my-project:/sources <my-image>`
|
||||
where `~` is expanded by the Linux shell to `$HOME`.
|
||||
- If you have concerns about the size of the docker-desktop-data VHDX, or need to change it, take a look at the [WSL tooling built into Windows](https://docs.microsoft.com/en-us/windows/wsl/vhd-size){:target="_blank" rel="noopener" class="_"}.
|
||||
- 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="_"}.
|
||||
- If you have concerns about CPU or memory usage, you can configure limits on the memory, CPU, and 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.
|
||||
|
||||
## 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){:target="_blank" rel="noopener" class="_"}.
|
||||
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 is straightforward if you are using [VSCode](https://code.visualstudio.com/download){:target="_blank" rel="noopener" class="_"}.
|
||||
|
||||
1. Open VSCode and install the [Remote - WSL](https://marketplace.visualstudio.com/items?itemName=ms-vscode-remote.remote-wsl){:target="_blank" rel="noopener" class="_"} extension. This extension allows you to work with a remote server in the Linux distro and your IDE client still on Windows.
|
||||
2. Now, you can start working in VSCode remotely. To do this, open your terminal and type:
|
||||
1. Open VS Code and install the [Remote - WSL](https://marketplace.visualstudio.com/items?itemName=ms-vscode-remote.remote-wsl){:target="_blank" rel="noopener" class="_"} extension. This extension allows you to work with a remote server in the Linux distro and your IDE client still on Windows.
|
||||
2. Now, you can start working in VS Code remotely. To do this, open your terminal and type:
|
||||
|
||||
`wsl`
|
||||
```console
|
||||
$ wsl
|
||||
```
|
||||
|
||||
`code .`
|
||||
```console
|
||||
$ code .
|
||||
```
|
||||
|
||||
This opens a new VSCode connected remotely to your default Linux distro which you can check in the bottom corner of the screen.
|
||||
This opens a new VS Code connected remotely to your default Linux distro which you can check in the bottom corner of the screen.
|
||||
|
||||
Alternatively, you can type the name of your default Linux distro in your Start menu, open it, and then run `code` .
|
||||
3. When you are in VSCode, you can use the terminal in VSCode to pull your code and start working natively from your Windows machine.
|
||||
3. When you are in VS Code, you can use the terminal in VS Code to pull your code and start working natively from your Windows machine.
|
||||
|
||||
## GPU support
|
||||
|
||||
|
|
@ -122,6 +131,10 @@ To validate that everything works as expected, run the following command to run
|
|||
|
||||
```console
|
||||
$ docker run --rm -it --gpus=all nvcr.io/nvidia/k8s/cuda-sample:nbody nbody -gpu -benchmark
|
||||
```
|
||||
The following displays:
|
||||
|
||||
```console
|
||||
Run "nbody -benchmark [-numbodies=<numBodies>]" to measure performance.
|
||||
-fullscreen (run n-body simulation in fullscreen mode)
|
||||
-fp64 (use double precision floating point values for simulation)
|
||||
|
|
@ -151,4 +164,4 @@ GPU Device 0: "GeForce RTX 2060 with Max-Q Design" with compute capability 7.5
|
|||
|
||||
## Feedback
|
||||
|
||||
Your feedback is very important to us. Please let us know your feedback by creating an issue in the [Docker Desktop for Windows GitHub](https://github.com/docker/for-win/issues){:target="_blank" rel="noopener" class="_"} repository and adding the **WSL 2** label.
|
||||
Your feedback is very important to us. Let us know your feedback by creating an issue in the [Docker Desktop for Windows GitHub](https://github.com/docker/for-win/issues){:target="_blank" rel="noopener" class="_"} repository and adding the **WSL 2** label.
|
||||
|
|
|
|||
Loading…
Reference in New Issue