Prerequisites

I assume you have already installed Docker Toolbox in your machine. If you have not, please refer to Docker's documentation.

Steps

1. Check your system's architecture and the version of your distro

It needs to be x86_64, amd64, armhf or arm64. It also needs to be one of those two versions of Debian:

• Debian Buster 10 (stable)
• Debian Stretch 9 / Raspbian Stretch

Of course you have to check it out if you're using another distro.

Run this on your WSL terminal to find out your system's architecture:

uname -m

And run this to find out the version of your distro:

cat /etc/os-release

It will return all the info you need to see if you can get everything working.

2. Install Docker client in your Debian distribution, via WSL

To do that, just run these two commands:

sudo apt-get update
sudo apt-get install docker-ce docker-ce-cli containerd.io

If you find something wrong along the line, maybe you are missing some features needed for the complete installation. Since the documentation includes steps you probably don't need if you have gone through some dev setup before, I cut it outhere. If you need, all those steps are also in Docker's documentation.

3. Setup WSL start settings:

Open /etc/wsl.conf and paste this in it:

[automount]
root = /
options = "metadata"

root = / defines the drivers root at "/c" or "/d" instead of "/mnt/c". This is done to avoid conflicts, since MINGW64, which is used by Docker Toolbox's quickstart terminal, uses that path structure.

options= "metadata" adds the metadata of the files, meaning you enable WSL to know permissions for the file both on Linux and on Windows. This just gives you an extra security so that the permissions of the file on Linux can be respected.

4. Setup terminal settings

Now, you must tell docker every time you run a command, where the host machine is. The host machine is the VM set up by Docker Toolbox's installer.

To avoid that, and use the commands as you would do anywhere else, you're going to change the configuration file for your terminal. Since I'm using Oh My Zsh!, my .zshrc file would do the trick.

Run this to edit the file on VS Code:

code ~/.zshrc

If you are using just bash, you should use ~/.bashrc. You can also use nano or vim to edit it directly in the terminal.

Then paste this at the end of your file:

export DOCKER_HOST="tcp://192.168.99.100:2376"
export DOCKER_TLS_VERIFY=1
export DOCKER_CERT_PATH="/c/Users/<your-user-name>/.docker/machine/certs"

OBS: Please change <your-user-name> to your Windows user name.

This will set up environment variables that will tell Docker's client the settings it should use when running its commands.

DOCKER_HOST should have the IP and port used to access the VM. It is common that Docker Toolbox use that IP, but you should change if it is different from the one you see after opening Docker Quickstart Terminal.

DOCKER_TLS_VERIFY is saying it must be verified if all connections are using TLS protocol. It uses symmetric cryptography to ensure data security. So, 1 is "ensure all connections are using TLS protocol" and 0 is "I don't care if it is insecure, bring it on".

DOCKER_CERT_PATH tells where Docker can find the certificates used on the TLS connection. Those certificates contain the decryption keys necessary to understand the data that comes and goes through the connection.

5. Log out of your Windows user account and log in again

This is needed so that the settings made to wsl.conf are loaded.

6. Test if it worked

• From Start menu, open Docker Quickstart Terminal;
• Wait until everything is fully loaded and you see the whale;
• Open Debian;
• Run docker run hello-world.

Conclusion

If you've followed the tutorial and need help at some point of it, please leave a comment. If you have found an answer to some problem you've had, please share with us.