How to use Docker Toolbox via WSL1 (Debian)
Tags: docker, bash, wsl, debian
Published: 2020-07-05 00:33:00

# Prerequisites
I assume you have already installed Docker Toolbox in your machine. If you have not, please refer to [Docker's documentation](https://docs.docker.com/toolbox/toolbox_install_windows/).

# 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:
```bash
uname -m
```

And run this to find out the version of your distro:
```bash
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:
```bash
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](https://docs.docker.com/engine/install/debian/#install-using-the-repository).

### 3. Setup WSL start settings:

Open `/etc/wsl.conf` and paste this in it:
```text
[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:

```bash
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:
```text
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](https://en.wikipedia.org/wiki/Symmetric-key_algorithm) 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.