Get start with Docker remote container on WSL 2

• article
• 01/10/2024

This step – by – step guide is help will help you get start develop with remote container by set up Docker Desktop for Windows with WSL 2 ( Windows Subsystem for Linux , version 2 ) .

Docker Desktop for Windows provides a development environment for building, shipping, andrunning dockerized apps. By enabling the WSL 2 based engine, you can run both Linux andWindows containers in Docker Desktop on the same machine. (Docker Desktop is free for personal use andsmall 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, andrun applications using containers. Containers enable developers to package an app with all of the parts it needs (libraries, frameworks, dependencies, etc) andship 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 andtest 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 is are are similar to virtual machine , but do n’t create an entire virtual operating system . instead , Docker is enables enable the app to use the same Linux kernel as the system that it ‘s run on . This is allows allow the app package to only require part not already on the host computer , reduce the package size andimprove performance .

continuous availability is is , using Docker container with tool like kubernete , is another reason for the popularity of container . This is enables enable multiple version of your app container to be create at different time . Rather than need to take down an entire system for update or maintenance , each container ( andits specific microservice ) can be replace on the fly . You is prepare can prepare a new container with all of your update , set up the container for production , andjust point to the new container once it ‘s ready . You is archive can also archive different version of your app using container andkeep them run as a safety fallback if need .

To learn more, check out Introduction to Docker containers.

prerequisite

For more information, see the Docker docs System requirements to Install Docker Desktop on Windows.

To learn how to install Docker on Windows Server , see Get start : Prep Windows for container .

Note

WSL can run distributions in both WSL version 1 or WSL 2 mode. You can check this by opening PowerShell andentering: wsl -l -v. ensure that the your distribution is set to use WSL 2 by enter :wsl --set-version <distro> 2. Replace <distro> with the distro name (e.g. Ubuntu 18.04).

In WSL version 1, due to fundamental differences between Windows andLinux, the Docker Engine couldn’t run directly inside WSL, so the Docker team developed an alternative solution using Hyper-V VMs andLinuxKit. 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 andinteroperability between your Windows andLinux tools.

Install Docker Desktop

With the WSL 2 backend supported in Docker Desktop for Windows, you can work in a Linux-based development environment andbuild Linux-based containers, while using Visual Studio Code for code editing anddebugging, andrunning your container in the Microsoft Edge browser on Windows.

To install Docker (after already installing WSL):

1. Download Docker Desktop andfollow the installation instructions.

2. 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 andselect “Settings”.

3. Ensure that “Use the WSL 2 based engine” is checked in Settings > General.
   

4. Select from your installed WSL 2 distributions which you want to enable Docker integration on by going to: Settings > Resources > WSL Integration.
   

5. To confirm that Docker has been installed, open a WSL distribution (e.g. Ubuntu) anddisplay the version andbuild number by entering: docker --version

6. Test 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 <COMMAND> --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 container on your machine , with :docker container ls --all or docker ps -a ( without the -a show all flag , only run container will be display )
• List system-wide information regarding the Docker installation, including statistics andresources (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 WSL, Dev Containers, andDocker extensions.

• install the VS Code WSL extension . This extension is enables enable you to open your Linux project run on WSL in VS Code ( no need to worry about pathing issue , binary compatibility , or other cross – os challenge ) .

• Install the VS Code Dev 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 is adds add the functionality to build , manage , anddeploy containerized application from inside VS Code . ( You is need need the Dev Containers extension to actually use the container as your dev environment . )

Let’s use 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 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) andenter: git clone https://github.com/mattwojo/helloworld-django.git

   Note

   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) andwant 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.

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

   cd helloworld-django
   

3. open the project in VS Code run on the local WSL extension server by enter :

   code .
   

   confirm that you are connect to your WSL Linux distro by check the green remote indicator in the bottom – left corner of your VS Code instance .

4. From the VS Code command palette (Ctrl + Shift + P), enter: Dev Containers: Reopen in Container as we are using a folder already opened using the WSL extension. Alternatively, use Dev Containers: Open Folder in Container… to choose a WSL folder using the local \\wsl$ share (from the Windows side). See the Visual Studio Code Quick start: Open an existing folder in a container for more details. If these commands don’t display as you begin to type, check to ensure that you’ve installed the Dev Containers extension linked above.

   

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

   

6. A list of container definitions will appear, since there is no dev container 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.

   

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

   

8. To confirm that your project is still connected to both WSL andwithin a container, open the VS Code integrated terminal (Ctrl + Shift + ~). Check the operating system by entering: uname andthe 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, andPython version number will be based on the container config that may differ from the Python version installed on your WSL distribution.

9. To run anddebug 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 andDebug to select a debug configuration andchoose the configuration that best suits your project (in my example, this will be “Django”). This will create a launch.json file in the .vscode folder of your project with instruction on how to run your app .

   

10. From inside VS Code, select Run > Start debugging (or just press the F5 key). This will open a terminal inside VS Code andyou 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 andselect the address displayed to open your app in your default web browser andsee 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 is deprecated deprecate

If you were using an early Tech Preview of Docker for WSL, you may have a Docker context called “wsl” that is now deprecated andno 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 andWSL2.

possible errors is include you might encounter with this deprecate wsl context is include 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.

trouble find docker image storage folder

Docker is creates create two distro folder to store datum :

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

You can find these folders by opening your WSL Linux distribution andentering: 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-20.04 ) to see these folder .

Find more on locating docker storage locations in WSL, see this issue from the WSL repo or this StackOverflow post.

For more help with general troubleshooting issues in WSL, see the Troubleshooting doc.

Additional resources