Docker and WSL2 without Docker Desktop
Tags: docker, wsl2, windows
Published: 2024-05-09 20:45:13

Using Docker on Windows has grown more challenging over the past few years. This guide aims to walk you through the process, from start to finish, to help you make the most of Docker on Windows without having to install Docker Desktop.

To use Docker without Docker Desktop, you’ll need to:

- Install WSL2, to serve as a runtime environment for Docker Engine
- Install Docker Engine inside WSL2, to be able to run containers
- Expose Docker Engine to be able to access it from Windows
- Install Docker command-line tools on Windows

## Install WSL2

WSL2, or the Windows Subsystem for Linux, allows you to run a Linux distribution on Windows. To install it with the default Ubuntu distribution, open a terminal in administrator mode and use the following command:
```bash
wsl --install
```
If you want to install a different Linux distribution instead of the default Ubuntu, you can list the available distributions and then install your preferred one using the following command:
```bash
wsl --list --online
wsl --install -d <DistroName>
```
It’s not mandatory, but depending on your setup, you might find it helpful to limit the resources allocated to WSL2. To do this, create a file named `.wslconfig` in your user folder. You can quickly access your user folder by typing `%UserProfile%` in the File Explorer's search bar.

Here’s an example of what a `.wslconfig` file might look like:
```ini
[wsl2]
memory=4GB 
processors=2
```
After installing WSL2, you can start it by typing `wsl` in a terminal, or by launching the WSL program from your Windows Start menu. Once WSL2 is open, update your Linux distribution to ensure all packages are up to date with the following command:
```bash
sudo apt update && sudo apt upgrade
```
To learn more about configuring WSL2 distributions and resource allocation, refer to the following sources.

Sources:
https://learn.microsoft.com/en-us/windows/wsl/install
https://learn.microsoft.com/en-us/windows/wsl/wsl-config

## Install Docker Engine on WSL2

Next, let’s install the Docker Engine, which is the core component that runs Docker containers. The following two blocks of commands will first add the Docker apt repository and then install Docker. You can execute them directly in the WSL2 terminal.
```bash
sudo apt-get install ca-certificates curl
sudo install -m 0755 -d /etc/apt/keyrings
sudo curl -fsSL https://download.docker.com/linux/ubuntu/gpg -o /etc/apt/keyrings/docker.asc
sudo chmod a+r /etc/apt/keyrings/docker.asc

# Add the repository to Apt sources:
echo \
  "deb [arch=$(dpkg --print-architecture) signed-by=/etc/apt/keyrings/docker.asc] https://download.docker.com/linux/ubuntu \
  $(. /etc/os-release && echo "$VERSION_CODENAME") stable" | \
  sudo tee /etc/apt/sources.list.d/docker.list > /dev/null
sudo apt-get update
```
```bash
sudo apt-get install docker-ce docker-ce-cli containerd.io docker-buildx-plugin docker-compose-plugin
```
Now that Docker is installed, let’s confirm that it’s working correctly. The following command will download and run the `hello-world` container. If the installation was successful, it should display a confirmation message and then exit.
```bash
sudo docker run hello-world
```
By default, you need to use sudo with Docker commands for elevated permissions. To run Docker without sudo, you can create a group docker for Docker users and add your current user to that group.
```bash
sudo groupadd docker
sudo usermod -aG docker $USER
```
On some distributions, the Docker group is created by default. You only need to add your user to this group to have the permission to run Docker without sudo. The Docker group is automatically managed by the Docker Engine, ensuring that only users in this group have permission to run Docker commands. After adding yourself to the Docker group, exit WSL2, then restart it, or simply log out and back in. Once you re-open WSL2, you should be able to use Docker without the need for sudo.
```bash
docker run hello-world
```
If you’re using a non-default WSL distribution, like a custom Linux distro, Docker might not start automatically when you launch WSL. To ensure Docker starts every time you open WSL, use the following commands:
```bash
sudo systemctl enable docker.service
sudo systemctl enable containerd.service
```
Sources:
https://docs.docker.com/engine/install/ubuntu/
https://docs.docker.com/engine/install/linux-postinstall/

## Expose Docker Engine on Windows

To access the Docker Engine from Windows, you’ll need to configure remote access for Docker. There are two ways to do this, by modifying the docker daemon, or by overriding systemd launch configuration.

### With daemon.json

For that method, you need to create or edit the `/etc/docker/daemon.json` file inside WSL2. Navigate to the `/etc/docker` directory and use the following command to edit the file:
```bash
vi daemon.json

# In vi,
# You press the key 'I' to enter in insert mode and be able to edit the file
# You press the key 'ESC', once you have finished inserting
# You press the keys ':wq' to save and quit editing
```

Then add this content to the file:

```json
{
  "hosts": ["unix:///var/run/docker.sock", "tcp://0.0.0.0:2375"]
}
```

### With systemd

With that method, to override the systemd launch configuration for the Docker service, you can create or edit a systemd override file by using the following command:
```bash
sudo systemctl edit docker.service
```
Then add, or modify, the following lines
```ini
[Service]
ExecStart=
ExecStart=/usr/bin/dockerd -H fd:// -H tcp://0.0.0.0:2375
```
Be sure to only use one of the two methods, not both. No matter the method you choose, for these changes to be applied, you will need to restart the Docker service.
```bash
sudo systemctl daemon-reload
sudo systemctl restart docker.service
```
To confirm that Docker is exposed on Windows, visit the URL http://localhost:2375/version. If you receive a response showing the current version of the Docker Engine, it means the exposure is successful.

### Create the link between WSL2 andWindows

To ensure that the Docker agent on Windows can detect the Docker Engine installed on WSL2, you need to establish a connection between the two by adding a DOCKER_HOSTenvironment variable on Windows. It specifies the address of the Docker Engine and determines where Docker commands will be sent.

![Adding an environment variable](https://dev-to-uploads.s3.amazonaws.com/uploads/articles/yh34l311y3kger2snwfq.png)

Depending on the configuration of your computer, and the activation of IPv6, you can set it to `tcp://localhost:2375` or `tcp://[::1]:2375`.

Sources:
https://docs.docker.com/config/daemon/remote-access/
https://gist.github.com/styblope/dc55e0ad2a9848f2cc3307d4819d819f

## Install Docker CLI on Windows
The final step is to install the Docker CLI on Windows. The CLI consists of several executable files that must be placed in specific locations within the Windows filesystem.

First, you must install the main executable. Create a folder for the installation wherever you’d like in the Windows filesystem, and then add that folder to your PATH. Next, visit https://download.docker.com/win/static/stable/x86_64/, download the latest version, and unzip the executables into the folder you just created.

You should now be able to run most Docker commands. To test it, try executing:
```bash
docker version
```
If it doesn’t work, one advice is to try with the other value for the `DOCKER_HOST` environment variable.

### Plugins, Buildx and Compose

Simply installing the main executable usually isn’t enough if you want to use all of Docker’s features. The builder included with the executable is the legacy builder, and the `docker compose` command will be unavailable. To access those additional features, you'll need to install some plugins.

In your user folder, accessible by typing `%UserProfile%` in the File Explorer's search bar, create the folder tree `.docker\cli-plugins\` if it doesn’t exists already.

To install the newest builder, download the latest version of the buildxplugin by visiting https://github.com/docker/buildx/releases. Find the most recent release, go to the “Assets” section, and expand the list of assets. Download the file that ends with `windows-amd64.exe`, like `buildx-v0.14.0.windows-amd64.exe`. Place the downloaded file in the `cli-plugins` folder you created earlier, and rename it to `docker-buildx.exe`. Now, the command `docker build` will automatically use the new builder.

To install docker compose tool, download the latest version of the plugin by visiting https://github.com/docker/compose/releases. Find the most recent release, go to the “Assets” section, and expand the list of assets. Download the file that ends with `windows-x86_64.exe`, like `docker-compose-windows-w86_64.exe`. Place the downloaded file in the `cli-plugins` folder you created earlier, and rename it to `docker-compose.exe`. Now, we can use the command `docker compose`.

The installation is finished ! 🥳
I hope everything is working fine ! Don’t forget to start WSL2 when you want to use Docker.

Sources:
https://docs.docker.com/engine/install/binaries/#install-server-and-client-binaries-on-windows
https://github.com/docker/buildx/releases
https://github.com/docker/compose/releases