Go started with Docker remote containers on WSL ii

  • Article
  • 9 minutes to read

This step-by-step guide will help you go started developing with remote containers by setting upwards Docker Desktop for Windows with WSL 2 (Windows Subsystem for Linux, version two).

Docker Desktop for Windows provides a development environment for building, aircraft, and running dockerized apps. By enabling the WSL ii based engine, yous can run both Linux and Windows containers in Docker Desktop on the same automobile. (Docker Desktop is complimentary for personal utilise and small businesses, for info on Pro, Team, or Business pricing, see the Docker site FAQs).

Overview of Docker containers

Docker is a tool used to create, deploy, and run applications using containers. Containers enable developers to bundle an app with all of the parts information technology needs (libraries, frameworks, dependencies, etc) and ship it all out equally one parcel. 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 car that was used to write and test the app's code. This permits developers to focus on writing code without worrying about the arrangement that lawmaking 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 employ the same Linux kernel as the organization that it's running on. This allows the app package to only require parts not already on the host reckoner, reducing the package size and improving performance.

Continuous availability, using Docker containers with tools similar Kubernetes, is another reason for the popularity of containers. This enables multiple versions of your app container to exist created at different times. Rather than needing to take down an entire organisation for updates or maintenance, each container (and it's specific microservices) can be replaced on the fly. You tin set a new container with all of your updates, gear up upwards the container for product, and just signal to the new container once it'due south set up. You tin as well archive different versions of your app using containers and continue them running as a safety fallback if needed.

To learn more, checkout the Introduction to Docker containers on Microsoft Learn.

Prerequisites

  • Ensure your car is running Windows 10, updated to version 2004, Build 18362 or later.
  • Install WSL and set up a user name and password for your Linux distribution running in WSL two.
  • Install Visual Studio Code (optional). This will provide the best experience, including the ability to lawmaking and debug within a remote Docker container and connected to your Linux distribution.
  • Install Windows Concluding (optional). This will provide the all-time experience, including the ability to customize and open multiple terminals in the same interface (including Ubuntu, Debian, PowerShell, Azure CLI, or whatever you lot adopt to use).
  • Sign up for a Docker ID at Docker Hub (optional).
  • See the Docker Desktop license agreement for updates on the terms of use.

Annotation

WSL tin run distributions in both WSL version 1 or WSL 2 manner. You tin check this past opening PowerShell and entering: wsl -l -v. Ensure that the your distribution is set to employ WSL ii by entering: wsl --set-version <distro> 2. Replace <distro> with the distro proper noun (e.g. Ubuntu xviii.04).

In WSL version 1, due to fundamental differences between Windows and Linux, the Docker Engine couldn't run straight inside WSL, and then the Docker team adult an alternative solution using Hyper-Five VMs and LinuxKit. All the same, since WSL 2 now runs on a Linux kernel with full arrangement call capacity, Docker can fully run in WSL two. This ways that Linux containers tin 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 lawmaking editing and debugging, and running your container in the Microsoft Border browser on Windows.

To install Docker (after already installing WSL):

  1. Download Docker Desktop and follow the installation instructions.

  2. Once installed, start Docker Desktop from the Windows Outset carte du jour, and so select the Docker icon from the hidden icons menu of your taskbar. Correct-click the icon to display the Docker commands bill of fare and select "Settings". Docker Desktop dashboard icon

  3. Ensure that "Use the WSL 2 based engine" is checked in Settings > General. Docker Desktop general settings

  4. Select from your installed WSL ii distributions which y'all want to enable Docker integration on by going to: Settings > Resources > WSL Integration. Docker Desktop resource settings

  5. To confirm that Docker has been installed, open a WSL distribution (e.one thousand. Ubuntu) and display the version and build number past entering: docker --version

  6. Test that your installation works correctly past running a simple built-in Docker image using: docker run hello-world

Tip

Here are a few helpful Docker commands to know:

  • Listing the commands available in the Docker CLI by inbound: docker
  • List information for a specific control with: docker <COMMAND> --assist
  • List the docker images on your machine (which is just the howdy-world image at this point), with: docker image ls --all
  • List the containers on your motorcar, with: docker container ls --all or docker ps -a (without the -a show all flag, only running containers will be displayed)
  • List arrangement-wide data regarding the Docker installation, including statistics and resource (CPU & retention) bachelor to y'all in the WSL 2 context, with: docker info

Develop in remote containers using VS Code

To become started developing apps using Docker with WSL 2, nosotros recommend using VS Lawmaking, forth with the Remote-WSL extension and Docker extension.

  • Install the VS Code Remote-WSL extension. This extension enables y'all to open up 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 up 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 really utilize the container as your dev environment.)

Let's apply Docker to create a development container for an existing app project.

  1. For this example, I'll use the source code from my Hello World tutorial for Django in the Python development surround prepare docs. Y'all can skip this pace 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.git

    Note

    Always store your lawmaking in the same file system that y'all're using tools in. This will result in faster file access operation. In this example, we are using a Linux distro (Ubuntu) and want to shop our project files on the WSL file system \\wsl\. Storing project files on the Windows file system would significantly slow things downward when using Linux tools in WSL to access those files.

  2. From your WSL terminal, change directories to the source code folder for this projection:

                      cd helloworld-django

  3. Open the project in VS Code running on the local Remote-WSL extension server by inbound:

                      lawmaking .

    Confirm that y'all are continued to your WSL Linux distro past checking the green remote indicator in the bottom-left corner of your VS Code case.

    VS Code WSL Remote indicator

  4. From the VS Code command pallette (Ctrl + Shift + P), enter: Remote-Containers: Open up Folder in Container... If this command doesn't display as you begin to blazon it, cheque to ensure that y'all've installed the Remote Container extension linked above.

    VS Code Remote Container command

  5. Select the project folder that you wish to containerize. In my case, this is \\wsl\Ubuntu-20.04\home\mattwojo\repos\helloworld-django\

    VS Code Remote Container folder

  6. A list of container definitions will appear, since there is no DevContainer configuration in the projection binder (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.

    VS Code Remote Container config definitions

  7. A new instance of VS Code will open up, begin building our new image, and once the build completed, will start our container. You will see that a new .devcontainer folder has appeared with container configuration information within a Dockerfile and devcontainer.json file.

    VS Code .devcontainer folder

  8. To confirm that your project is still continued to both WSL and within a container, open the VS Code integrated terminal (Ctrl + Shift + ~). Check the operating system by entering: uname and the Python version with: python3 --version. You tin can see that the uname came dorsum every bit "Linux", and so you lot are even so connected to the WSL ii engine, and Python version number volition be based on the container config that may differ from the Python version installed on your WSL distribution.

  9. 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 volition be "Django"). This volition create a launch.json file in the .vscode binder of your project with instructions on how to run your app.

    VS Code run debug configuration

  10. From inside VS Code, select Run > Start debugging (or just press the F5 key). This will open a terminal within VS Code and you lot should run into a event maxim something like: "Starting development server at http://127.0.0.1:8000/ Quit the server with CONTROL-C." Concur downward the Control cardinal and select the address displayed to open your app in your default web browser and see your project running inside of its container.

    VS Code running a docker container

You have now successfully configured a remote development container using Docker Desktop, powered by the WSL ii backend, that yous tin lawmaking in, build, run, deploy, or debug using VS Code!

Troubleshooting

WSL docker context deprecated

If y'all were using an early Tech Preview of Docker for WSL, you may have a Docker context chosen "wsl" that is now deprecated and no longer used. You tin can check with the command: docker context ls. Yous tin can remove this "wsl" context to avoid errors with the command: docker context rm wsl equally you want to employ 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 observe the file specified. or error during connect: Get http://%2F%2F.%2Fpipe%2Fdocker_wsl/v1.forty/images/json?all=1: open //./pipage/docker_wsl: The system cannot observe the file specified.

For more than on this issue, see How to prepare Docker within Windows System for Linux (WSL2) on Windows 10.

Trouble finding docker epitome storage folder

Docker creates two distro folders to store data:

  • \wsl$\docker-desktop
  • \wsl$\docker-desktop-data

You tin can find these folders by opening your WSL Linux distribution and entering: explorer.exe . to view the folder in Windows File Explorer. Enter: \\wsl\<distro name>\mnt\wsl replacing <distro name> with the name of your distribution (ie. Ubuntu-twenty.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.

For more aid with general troubleshooting issues in WSL, see the Troubleshooting medico.

Boosted resources

  • Docker docs: Best practices for Docker Desktop with WSL 2
  • Feedback for Docker Desktop for Windows: File an issue
  • VS Lawmaking Web log: Guidelines for choosing a development environment
  • VS Code Weblog: Using Docker in WSL 2
  • VS Code Blog: Using Remote Containers in WSL 2
  • Hanselminutes Podcast: Making Docker lovely for Developers with Simon Ferquel