This guide will show you how to enable Windows Subsystem for Linux (WSL) feature on Windows server 2019 and run a Linux Server such as Ubuntu inside Windows Server. In our last article, we covered running Docker containers on Windows Server. Last June, the Docker team announced that they will be investing in getting Docker running with the Windows Subsystem for Linux (WSL). All of this is made possible with the recent changes to the architecture of WSL to run within a lightweight virtual machine (VM), which we talked about in an earlier blog post about WSL 2.
This step-by-step guide will help you get started developing with remote containers by setting up Docker Desktop for Windows with WSL 2 (Windows Subsystem for Linux, version 2). Docker Desktop for Windows is available for free and provides a development environment for building, shipping, and running dockerized apps. As a Windows Insider, I tried the Windows Subsystem for Linux since day 1 and I really enjoyed it. Now that Falls Creators U p date is out, I'm using the Ubuntu distro from the store, and the. 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. Starting with WSL2, Docker can run in it's full flow in Windows and you can use images built for Linux.
-->This step-by-step guide will help you get started developing with remote containers by setting up Docker Desktop for Windows with WSL 2 (Windows Subsystem for Linux, version 2).
Docker Desktop for Windows is available for free and provides a development environment for building, shipping, and running dockerized apps. By enabling the WSL 2 based engine, you can run both Linux and Windows containers in Docker Desktop on the same machine.
Overview of Docker containers
Docker is a tool used to create, deploy, and run applications using containers. Containers enable developers to package an app with all of the parts it needs (libraries, frameworks, dependencies, etc) and ship it all out as one package. Using a container ensures that the app will run the same regardless of any customized settings or previously installed libraries on the computer running it that could differ from the machine that was used to write and test the app's code. This permits developers to focus on writing code without worrying about the system that code will be run on.
Docker containers are similar to virtual machines, but don't create an entire virtual operating system. Instead, Docker enables the app to use the same Linux kernel as the system that it's running on. This allows the app package to only require parts not already on the host computer, reducing the package size and improving performance.
Continuous availability, using Docker containers with tools like Kubernetes, is another reason for the popularity of containers. This enables multiple versions of your app container to be created at different times. Rather than needing to take down an entire system for updates or maintenance, each container (and it's specific microservices) can be replaced on the fly. You can prepare a new container with all of your updates, set up the container for production, and just point to the new container once it's ready. You can also archive different versions of your app using containers and keep them running as a safety fallback if needed.
To learn more, checkout the Introduction to Docker containers on Microsoft Learn.
Prerequisites
- Ensure your machine is running Windows 10, updated to version 2004, Build 18362 or higher.
- Enable WSL, install a Linux distribution, and update to WSL 2.
- Download and install the Linux kernel update package.
- Install Visual Studio Code(optional). This will provide the best experience, including the ability to code and debug inside a remote Docker container and connected to your Linux distribution.
- Install Windows Terminal(optional). This will provide the best experience, including the ability to customize and open multiple terminals in the same interface (including Ubuntu, Debian, PowerShell, Azure CLI, or whatever you prefer to use).
- Sign up for a Docker ID at Docker Hub(optional).
Note
WSL can run distributions in both WSL version 1 or WSL 2 mode. You can check this by opening PowerShell and entering: wsl -l -v. Ensure that the your distribution is set to use WSL 2 by entering: wsl --set-version 2. Replace with the distro name (e.g. Ubuntu 18.04).
In WSL version 1, due to fundamental differences between Windows and Linux, the Docker Engine couldn't run directly inside WSL, so the Docker team developed an alternative solution using Hyper-V VMs and LinuxKit. However, since WSL 2 now runs on a Linux kernel with full system call capacity, Docker can fully run in WSL 2. This means that Linux containers can run natively without emulation, resulting in better performance and interoperability between your Windows and Linux tools.
Install Docker Desktop
With the WSL 2 backend supported in Docker Desktop for Windows, you can work in a Linux-based development environment and build Linux-based containers, while using Visual Studio Code for code editing and debugging, and running your container in the Microsoft Edge browser on Windows.
To install Docker (after already installing WSL 2):
Download Docker Desktop and follow the installation instructions.
Once installed, start Docker Desktop from the Windows Start menu, then select the Docker icon from the hidden icons menu of your taskbar. Right-click the icon to display the Docker commands menu and select 'Settings'.
Ensure that 'Use the WSL 2 based engine' is checked in Settings > General.
Select from your installed WSL 2 distributions which you want to enable Docker integration on by going to: Settings > Resources > WSL Integration.
To confirm that Docker has been installed, open a WSL distribution (e.g. Ubuntu) and display the version and build number by entering:
docker --versionTest that your installation works correctly by running a simple built-in Docker image using:
docker run hello-world
Tip
Here are a few helpful Docker commands to know:
- List the commands available in the Docker CLI by entering:
docker - List information for a specific command with:
docker --help - List the docker images on your machine (which is just the hello-world image at this point), with:
docker image ls --all - List the containers on your machine, with:
docker container ls --allordocker ps -a(without the -a show all flag, only running containers will be displayed) - List system-wide information regarding the Docker installation, including statistics and resources (CPU & memory) available to you in the WSL 2 context, with:
docker info
Develop in remote containers using VS Code
To get started developing apps using Docker with WSL 2, we recommend using VS Code, along with the Remote-WSL extension and Docker extension.
Install the VS Code Remote-WSL extension. This extension enables you to open your Linux project running on WSL in VS Code (no need to worry about pathing issues, binary compatibility, or other cross-OS challenges).
Install the VS code Remote-Containers extension. This extension enables you to open your project folder or repo inside of a container, taking advantage of Visual Studio Code's full feature set to do your development work within the container.
Install the VS Code Docker extension. This extension adds the functionality to build, manage, and deploy containerized applications from inside VS Code. (You need the Remote-Container extension to actually use the container as your dev environment.)
Let's use Docker to create a development container for an existing app project.
For this example, I'll use the source code from my Hello World tutorial for Django in the Python development environment set up docs. You can skip this step if you prefer to use your own project source code. To download my HelloWorld-Django web app from GitHub, open a WSL terminal (Ubuntu for example) and enter:
git clone https://github.com/mattwojo/helloworld-django.gitNote
Always store your code in the same file system that you're using tools in. This will result in faster file access performance. In this example, we are using a Linux distro (Ubuntu) and want to store our project files on the WSL file system
wsl. Storing project files on the Windows file system would significantly slow things down when using Linux tools in WSL to access those files.From your WSL terminal, change directories to the source code folder for this project:
Open the project in VS Code running on the local Remote-WSL extension server by entering:
Confirm that you are connected to your WSL Linux distro by checking the green remote indicator in the bottom-left corner of your VS Code instance.
From the VS Code command pallette (Ctrl + Shift + P), enter: Remote-Containers: Open Folder in Container.. If this command doesn't display as you begin to type it, check to ensure that you've installed the Remote Container extension linked above.
Select the project folder that you wish to containerize. In my case, this is
wslUbuntu-20.04homemattwojoreposhelloworld-djangoA list of container definitions will appear, since there is no DevContainer configuration in the project folder (repo) yet. The list of container configuration definitions that appears is filtered based on your project type. For my Django project, I'll select Python 3.
A new instance of VS Code will open, begin building our new image, and once the build completed, will start our container. You will see that a new
.devcontainerfolder has appeared with container configuration information inside aDockerfileanddevcontainer.jsonfile.To confirm that your project is still connected to both WSL and within a container, open the VS Code integrated terminal (Ctrl + Shift + ~). Check the operating system by entering:
unameand the Python version with:python3 --version. You can see that the uname came back as 'Linux', so you are still connected to the WSL 2 engine, and Python version number will be based on the container config that may differ from the Python version installed on your WSL distribution.To run and debug your app inside of the container using Visual Studio Code, first open the Run menu (Ctrl+Shift+D or select the tab on the far left menu bar). Then select Run and Debug to select a debug configuration and choose the configuration that best suites your project (in my example, this will be 'Django'). This will create a
launch.jsonfile in the.vscodefolder of your project with instructions on how to run your app.From inside VS Code, select Run > Start debugging (or just press the F5 key). This will open a terminal inside VS Code and you should see a result saying something like: 'Starting development server at http://127.0.0.1:8000/ Quit the server with CONTROL-C.' Hold down the Control key and select the address displayed to open your app in your default web browser and see your project running inside of its container.
You have now successfully configured a remote development container using Docker Desktop, powered by the WSL 2 backend, that you can code in, build, run, deploy, or debug using VS Code!
Troubleshooting
WSL docker context deprecated
If you were using an early Tech Preview of Docker for WSL, you may have a Docker context called 'wsl' that is now deprecated and no longer used. You can check with the command: docker context ls. You can remove this 'wsl' context to avoid errors with the command: docker context rm wsl as you want to use the default context for both Windows and WSL2.
Possible errors you might encounter with this deprecated wsl context include: docker wsl open //./pipe/docker_wsl: The system cannot find the file specified. or error during connect: Get http://%2F%2F.%2Fpipe%2Fdocker_wsl/v1.40/images/json?all=1: open //./pipe/docker_wsl: The system cannot find the file specified.
For more on this issue, see How to set up Docker within Windows System for Linux (WSL2) on Windows 10.
Apple createinstallmedia yosemite. Next run the createinstallmedia command provided by Apple (opens new window). Note that the command is made for USB's formatted with the name MyVolume. Make the USB installer with the createinstallmedia method from Apple. For those downloading Big Sur 11.0.1+ Watch this video. High Sierra, Mojave or Catalina, watch this one. Plug the bootable installer into a Mac that is connected to the internet and compatible with the version of macOS you're installing. Turn on your Mac and continue to hold the power button until you see the startup options window, which shows your bootable volumes and a gear icon labled Options. Plug the bootable installer into a Mac that is connected to the Internet and compatible with the version of macOS you're installing. Turn on your Mac and continue to hold the power button until you see the startup options window, which shows your bootable volumes and a gear icon labelled Options. Apple Footer 本网站包含用户提交的内容、评论和观点，仅供参考。根据提供的信息，Apple 可能会提供或推荐回复来作为可行的解决方案；每个潜在问题可能都会涉及多个因素，这些因素在电子论坛上的对话中没有详加说明，因此，对于在社区论坛上提出的任何解决方案，Apple 不保证一定有效。.
Trouble finding docker image storage folder
Docker creates two distro folders to store data:
- wsl$docker-desktop
- wsl$docker-desktop-data
You can find these folders by opening your WSL Linux distribution and entering: explorer.exe . to view the folder in Windows File Explorer. Enter: wslmntwsl replacing with the name of your distribution (ie. Ubuntu-20.04) to see these folders.
Find more on locating docker storage locations in WSL, see this issue from the WSL repo or this StackOverlow post. Install elasticsearch in docker kubernetes.
For more help with general troubleshooting issues in WSL, see the Troubleshooting doc.
Additional resources
March 2, 2020 by Matt Hernandez, @fiveisprime
Last June, the Docker team announced that they will be investing in getting Docker running with the Windows Subsystem for Linux (WSL). All of this is made possible with the recent changes to the architecture of WSL to run within a lightweight virtual machine (VM), which we talked about in an earlier blog post about WSL 2. Since this announcement, the Docker team has released a Technical Preview of Docker that includes support for running with WSL 2.
This article explains how the Docker Desktop technical preview works as well as how to use the Docker extension with the technical preview.
How it works
This new Docker architecture works a lot like Visual Studio Code's WSL remote development support in that the Docker CLI running on the host machine executes commands within the Docker Integration Package, which runs on the remote WSL VM.
Image credit: Docker Engineering
DockerD runs directly within WSL so there's no need for the Hyper-V VM and all Linux containers run within the Linux userspace on Windows for improved performance and compatibility.
Getting set up
First some prerequisites:
- Install Windows 10 Insider Preview build 18975 (Slow) or later for WSL 2.
- Install Ubuntu from the Microsoft store.
- Enable WSL 2 by following this guide.
- Install the Remote - WSL extension for VS Code.
- Install the Docker WSL 2 Technical Preview.
Run Docker In Windows Subsystem For Linux
Once installed, Docker will recognize that you have WSL installed and prompt to enable WSL integration. You want to Enable WSL integration for this tutorial.
This option will allow you to access Docker Desktop via the Docker CLI directly from within your Linux distro.
Run Docker In Linux Subsystem For Windows 10
If you have multiple Linux distros, make sure you only have WSL integration turned on for the correct one in your Docker settings:
With that configured, all commands will execute in the Linux context - this includes Docker commands run from PowerShell so running something like docker run mongo… will start a Linux container within the WSL VM.
Running the docker ps command over in WSL, you'll see the container as expected. Notice that the container ID matches.
To install Docker (after already installing WSL 2):
Download Docker Desktop and follow the installation instructions.
Once installed, start Docker Desktop from the Windows Start menu, then select the Docker icon from the hidden icons menu of your taskbar. Right-click the icon to display the Docker commands menu and select 'Settings'.
Ensure that 'Use the WSL 2 based engine' is checked in Settings > General.
Select from your installed WSL 2 distributions which you want to enable Docker integration on by going to: Settings > Resources > WSL Integration.
To confirm that Docker has been installed, open a WSL distribution (e.g. Ubuntu) and display the version and build number by entering:
docker --versionTest that your installation works correctly by running a simple built-in Docker image using:
docker run hello-world
Tip
Here are a few helpful Docker commands to know:
- List the commands available in the Docker CLI by entering:
docker - List information for a specific command with:
docker --help - List the docker images on your machine (which is just the hello-world image at this point), with:
docker image ls --all - List the containers on your machine, with:
docker container ls --allordocker ps -a(without the -a show all flag, only running containers will be displayed) - List system-wide information regarding the Docker installation, including statistics and resources (CPU & memory) available to you in the WSL 2 context, with:
docker info
Develop in remote containers using VS Code
To get started developing apps using Docker with WSL 2, we recommend using VS Code, along with the Remote-WSL extension and Docker extension.
Install the VS Code Remote-WSL extension. This extension enables you to open your Linux project running on WSL in VS Code (no need to worry about pathing issues, binary compatibility, or other cross-OS challenges).
Install the VS code Remote-Containers extension. This extension enables you to open your project folder or repo inside of a container, taking advantage of Visual Studio Code's full feature set to do your development work within the container.
Install the VS Code Docker extension. This extension adds the functionality to build, manage, and deploy containerized applications from inside VS Code. (You need the Remote-Container extension to actually use the container as your dev environment.)
Let's use Docker to create a development container for an existing app project.
For this example, I'll use the source code from my Hello World tutorial for Django in the Python development environment set up docs. You can skip this step if you prefer to use your own project source code. To download my HelloWorld-Django web app from GitHub, open a WSL terminal (Ubuntu for example) and enter:
git clone https://github.com/mattwojo/helloworld-django.gitNote
Always store your code in the same file system that you're using tools in. This will result in faster file access performance. In this example, we are using a Linux distro (Ubuntu) and want to store our project files on the WSL file system
wsl. Storing project files on the Windows file system would significantly slow things down when using Linux tools in WSL to access those files.From your WSL terminal, change directories to the source code folder for this project:
Open the project in VS Code running on the local Remote-WSL extension server by entering:
Confirm that you are connected to your WSL Linux distro by checking the green remote indicator in the bottom-left corner of your VS Code instance.
From the VS Code command pallette (Ctrl + Shift + P), enter: Remote-Containers: Open Folder in Container.. If this command doesn't display as you begin to type it, check to ensure that you've installed the Remote Container extension linked above.
Select the project folder that you wish to containerize. In my case, this is
wslUbuntu-20.04homemattwojoreposhelloworld-djangoA list of container definitions will appear, since there is no DevContainer configuration in the project folder (repo) yet. The list of container configuration definitions that appears is filtered based on your project type. For my Django project, I'll select Python 3.
A new instance of VS Code will open, begin building our new image, and once the build completed, will start our container. You will see that a new
.devcontainerfolder has appeared with container configuration information inside aDockerfileanddevcontainer.jsonfile.To confirm that your project is still connected to both WSL and within a container, open the VS Code integrated terminal (Ctrl + Shift + ~). Check the operating system by entering:
unameand the Python version with:python3 --version. You can see that the uname came back as 'Linux', so you are still connected to the WSL 2 engine, and Python version number will be based on the container config that may differ from the Python version installed on your WSL distribution.To run and debug your app inside of the container using Visual Studio Code, first open the Run menu (Ctrl+Shift+D or select the tab on the far left menu bar). Then select Run and Debug to select a debug configuration and choose the configuration that best suites your project (in my example, this will be 'Django'). This will create a
launch.jsonfile in the.vscodefolder of your project with instructions on how to run your app.From inside VS Code, select Run > Start debugging (or just press the F5 key). This will open a terminal inside VS Code and you should see a result saying something like: 'Starting development server at http://127.0.0.1:8000/ Quit the server with CONTROL-C.' Hold down the Control key and select the address displayed to open your app in your default web browser and see your project running inside of its container.
You have now successfully configured a remote development container using Docker Desktop, powered by the WSL 2 backend, that you can code in, build, run, deploy, or debug using VS Code!
Troubleshooting
WSL docker context deprecated
If you were using an early Tech Preview of Docker for WSL, you may have a Docker context called 'wsl' that is now deprecated and no longer used. You can check with the command: docker context ls. You can remove this 'wsl' context to avoid errors with the command: docker context rm wsl as you want to use the default context for both Windows and WSL2.
Possible errors you might encounter with this deprecated wsl context include: docker wsl open //./pipe/docker_wsl: The system cannot find the file specified. or error during connect: Get http://%2F%2F.%2Fpipe%2Fdocker_wsl/v1.40/images/json?all=1: open //./pipe/docker_wsl: The system cannot find the file specified.
For more on this issue, see How to set up Docker within Windows System for Linux (WSL2) on Windows 10.
Apple createinstallmedia yosemite. Next run the createinstallmedia command provided by Apple (opens new window). Note that the command is made for USB's formatted with the name MyVolume. Make the USB installer with the createinstallmedia method from Apple. For those downloading Big Sur 11.0.1+ Watch this video. High Sierra, Mojave or Catalina, watch this one. Plug the bootable installer into a Mac that is connected to the internet and compatible with the version of macOS you're installing. Turn on your Mac and continue to hold the power button until you see the startup options window, which shows your bootable volumes and a gear icon labled Options. Plug the bootable installer into a Mac that is connected to the Internet and compatible with the version of macOS you're installing. Turn on your Mac and continue to hold the power button until you see the startup options window, which shows your bootable volumes and a gear icon labelled Options. Apple Footer 本网站包含用户提交的内容、评论和观点，仅供参考。根据提供的信息，Apple 可能会提供或推荐回复来作为可行的解决方案；每个潜在问题可能都会涉及多个因素，这些因素在电子论坛上的对话中没有详加说明，因此，对于在社区论坛上提出的任何解决方案，Apple 不保证一定有效。.
Trouble finding docker image storage folder
Docker creates two distro folders to store data:
- wsl$docker-desktop
- wsl$docker-desktop-data
You can find these folders by opening your WSL Linux distribution and entering: explorer.exe . to view the folder in Windows File Explorer. Enter: wslmntwsl replacing with the name of your distribution (ie. Ubuntu-20.04) to see these folders.
Find more on locating docker storage locations in WSL, see this issue from the WSL repo or this StackOverlow post. Install elasticsearch in docker kubernetes.
For more help with general troubleshooting issues in WSL, see the Troubleshooting doc.
Additional resources
March 2, 2020 by Matt Hernandez, @fiveisprime
Last June, the Docker team announced that they will be investing in getting Docker running with the Windows Subsystem for Linux (WSL). All of this is made possible with the recent changes to the architecture of WSL to run within a lightweight virtual machine (VM), which we talked about in an earlier blog post about WSL 2. Since this announcement, the Docker team has released a Technical Preview of Docker that includes support for running with WSL 2.
This article explains how the Docker Desktop technical preview works as well as how to use the Docker extension with the technical preview.
How it works
This new Docker architecture works a lot like Visual Studio Code's WSL remote development support in that the Docker CLI running on the host machine executes commands within the Docker Integration Package, which runs on the remote WSL VM.
Image credit: Docker Engineering
DockerD runs directly within WSL so there's no need for the Hyper-V VM and all Linux containers run within the Linux userspace on Windows for improved performance and compatibility.
Getting set up
First some prerequisites:
- Install Windows 10 Insider Preview build 18975 (Slow) or later for WSL 2.
- Install Ubuntu from the Microsoft store.
- Enable WSL 2 by following this guide.
- Install the Remote - WSL extension for VS Code.
- Install the Docker WSL 2 Technical Preview.
Run Docker In Windows Subsystem For Linux
Once installed, Docker will recognize that you have WSL installed and prompt to enable WSL integration. You want to Enable WSL integration for this tutorial.
This option will allow you to access Docker Desktop via the Docker CLI directly from within your Linux distro.
Run Docker In Linux Subsystem For Windows 10
If you have multiple Linux distros, make sure you only have WSL integration turned on for the correct one in your Docker settings:
With that configured, all commands will execute in the Linux context - this includes Docker commands run from PowerShell so running something like docker run mongo… will start a Linux container within the WSL VM.
Running the docker ps command over in WSL, you'll see the container as expected. Notice that the container ID matches.
Using VS Code
With this set up and running, you can install the VS Code Docker extension and access your containers. If you're already running WSL 2 and the Remote - WSL extension, this will help you get Docker integrated into your WSL workflow rather than switching contexts when you need containers. And because the Docker CLI's context is set to use DockerD in WSL, the extension will work with your containers regardless of whether you opened VS Code using the Remote - WSL extension.
Notice how in the screenshot below, I'm connected and working in WSL and still building/running containers without changing from my preferred environment (zsh in Ubuntu).
Theme: Noctis Sereno
I've personally noticed a vast improvement in container execution times using this configuration and each part of my typical development workflow remains the same. I'm also using the Remote - Containers extension within WSL for testing specific environments without setting things up directly on my machine.
We want your feedback
Keep in mind that you're using prerelease software and, while the Windows Insiders Slow ring is very stable, you may run into some issues. If you do find something that isn't working as expected, please open an issue via the Feedback tool in Windows. Any direct Docker issues or feedback can be logged in the Docker for Windows repo.
Happy Coding!
Matt Hernandez, VS Code Program Manager @fiveisprime
