Back in July, Docker announnced that with WSL2, they could create a more native Linux experience for Docker on Windows, and in so doing, opened up the door for that experience to work on Windows 10 Home.
Docker does have a wsl2 tech preview, but as of the time of this writing, you can't install it on Windows 10 Home.
Well, I got impatient, and started tinkering, and wouldn't you know, I got it working.
This repository will start as a document of the steps I took, and hopefully evolve into a simple script to allow automation of this setup.
- Be running Windows Build 18945 or higher. (
18917or higher shoud work, but you won't get automatic localhost resolution between Windows and Linux processes) - Have wsl2 setup Microsoft Docs - Install WSL2
- Ubuntu 18.04 installed Store link - Ubuntu 18.04
- (Optional) Install new Windows Terminal from Store
- (Optional) Install chocolatey
So here's the thing. Once I got everything up and runing, I found I had absolutely no need
to install the native windows docker client! I wound up mapping \\wsl$\Ubuntu1 to
my U: drive, and automounting root = / in /etc/wsl.conf on Ubuntu (Installation step 1).
As a result, I can now navigate to U: in windows explorer or my editor of choice to open and edit
files in the Ubuntu filesystem, including files on any mapped Windows drive.
For example, I have a 240G SSD mounted as Y drive, and that is exclusively where I have my
source code.
Now, I can open VSCode on Windows, and create a new project at Y:/example_project, and those files
will be accessible inside Ubuntu at /y/example_project.
In VSCode I set my default terminal as the Ubuntu bash terminal, (require the new Windows Terminal), and cd /y/example_project.
I can now edit files on windows or on Linux, and use docker run -v $PWD:/app and it will mount
the files I'm editing in windows, into the docker container that is running on Linux.
The same concept works with any Windows drive.
I could have created my project at C:\Users\username\example_project and cd /c/Users/username/example_project
in my terminal.
This is the same experience you get with docker on its native platform (Linux), without having to use
some tiny VM emulation layer, and having to deal with samba mounts and passwords to share
your C drive for the
windows docker client. WSL gives you seamless integration with Ubuntu, including exposing ports on
localhost between the two kernels.
Therefore, installing the docker client on Windows is completely optional! (I included the steps below anyways, since you might have your own reasons for wanting low-level powershell docker integration)
- Add wsl.conf to Ubuntu
- Install Docker on Ubuntu
- Configure Docker on Ubuntu
- (Optional) Set docker env vars on Windows
- (Optional) Install docker client on Windows
- (Optional) Install docker-compose on Windows
Save the following file as /etc/wsl.conf on your Ubuntu host:
[automount]
root = /
options = "metadata"
This will mount all of your mapped drives to a corresponding letter in the root of your Ubuntu filesystem. This is what will allow you the "native" experience of editing file on Windows and running them from your windows or ubuntu terminals.
This step is mostly going to follow the Docker Installing on Ubuntu docs, with one
major exception. The current Ubuntu distro from Microsoft doesn't use systemd, so
you'll have to start/stop docker with sudo service docker {start|stop|restart|status}.
$ sudo apt update
$ sudo apt install apt-transport-https ca-certificates curl \
gnupg-agent software-properties-common
Then add dockers gpg key and verify it matches shown fingerprint
$ curl -fsSL https://download.docker.com/linux/ubuntu/gpg | sudo apt-key add
$ sudo apt-key fingerprint 0EBFCD88
pub rsa4096 2017-02-22 [SCEA]
9DC8 5822 9FC7 DD38 854A E2D8 8D81 803C 0EBF CD88
uid [ unknown] Docker Release (CE deb) <[email protected]>
sub rsa4096 2017-02-22 [S]
Add the edge docker repository. (stable will probably work, but I suspect less errors with WSL2 on windows will happen on edge)
$ sudo add-apt-repository \
"deb [arch=amd64] https://download.docker.com/linux/ubuntu \
$(lsb_release -cs) \
edge"
Ensure you are about to install from teh Docker repo instead of default Ubuntu repo:
$ sudo apt-cache policy docker-ce
// you should see output similar to:
docker-ce:
Installed: (none)
Cadidate: 5:19.03.4~3-0ubuntu-bionic
Version table:
... (a bunch of versions listed)
Install Docker and peer packages
sudo apt install docker-ce docker-ce-cli containerd.io
In order for the docker command on the windows host to run
"natively", we'll need to use the daemon running in WSL to allow
connections from the Windows Host.
Since Windows Build 18945, services on the WSL machine are automatically exposed
to localhost on the Windows side, and vice-versa.
There is probably a startup script that can be run to figure out what the IP of the Windows
Host is from the Linux machine, but I haven't gotten that far yet, so for now, we'll
just set the daemon to listen to unix:// and optionally tcp://0.0.0.0:2375.
If you don't intend to use the docker command from powershell or a windows terminal,
and map the wsl as a network drive, you can remove the host entry from the example below to
increase security.
Create the following /etc/docker/daemon.json file in WSL machine:
{
"hosts": ["unix://", "tcp://0.0.0.0:2375"],
"experimental": true
}
sudo service docker start
Open up your Environment Variables in Windows, and add the following entries under the System Environment Variables section:
| Env Var | Value | Required/Optional |
|---|---|---|
DOCKER_HOST |
tcp://localhost:2375 |
Required |
DOCKER_CLI_EXPERIMENTAL |
enabled |
Optional |
DOCKER_API_VERSION |
1.40 |
Optional |
- Download the docker client from the following url, substituting for the release you want:
https://dockermsft.blob.core.windows.net/dockercontainer/docker-19-03-1.zip
-
Unzip the contents of the
docker-19.03-1.ziptoC:\Program Files\Docker(new directory) Note: Make sure that thedocker.exeis atC:\Program files\Docker\docker.exe -
Add
C:\Program Files\Dockerto the SystemPATHEnvironment Variable -
Run
refreshenvin Powershell and you should now be able to rundocker version!
You should see output similar to below:
Client: Docker Engine - Community
Version: 19.03.4
API version: 1.40
Go version: go1.12.10
Git commit: 9013bf583a
Built: Fri Oct 18 15:54:09 2019
OS/Arch: linux/amd64
Experimental: false
Server: Docker Engine - Community
Engine:
Version: 19.03.4
API version: 1.40 (minimum version 1.12)
Go version: go1.12.10
Git commit: 9013bf583a
Built: Fri Oct 18 15:52:40 2019
OS/Arch: linux/amd64
Experimental: true
containerd:
Version: 1.2.10
GitCommit: b34a5c8af56e510852c35414db4c1f4fa6172339
runc:
Version: 1.0.0-rc8+dev
GitCommit: 3e425f80a8c931f88e6d94a8c831b9d5aa481657
docker-init:
Version: 0.18.0
GitCommit: fec3683
Using chocolatey is the easiest for this one:
$ choco install docker-compose
*1 Make sure you use the name of the distro as listed in the output of the wsl -l command
React
Typescript
Django
Laravel
Facebook
Microsoft
Google
Alibaba
D3
Tencent