Windows WSL2 support

[back-2-95]

• mkcert is used in Windows 10, no need it to be installed with Stonehenge
• mkcert is installed to Windows with Chocolatey
• WSL_DISTRO_NAME=Ubuntu-20.04 can be used to detect WSL2 Ubuntu
• Ubuntu needs make to be installed
• certs created in Windows need to be used by docker-compose.yml setup

[j-vee]

Tested using Windows 10 Professional, WSL2 with Ubuntu 18.04.

• Install WSL2
• In Microsoft Store search and install Ubuntu 18.04 (should work with later versions as well)
• Install Docker Desktop and make sure "Use the WSL2 based engine" checkbox is checked in the settings.

In Ubuntu terminal

• Once Ubuntu has finished installing, open the shell and run sudo apt-get update sudo apt-get upgrade sudo apt-get install build-essential
• Copy your ssh key over to ~/.ssh/id_rsa
• Install s2i
• Install stonehenge as per the readme
• Open your Stonehenge directory cd ~/stonehenge
• Run make up
• You now have rootCA.pem file in your ~/stonehenge/certs folder
• cd ~/stonehenge/certs
• explorer.exe .

You now have a Windows Explorer window open for the certs-folder. Copy its path from the address bar.

• Open Manage user certificates.
• Open Action -> All tasks -> Import
• In the dialog that opens up, select Next, Browse and then paste the path from above to the address bar and select rootCA.pem file for import.
• In the next step, select the Certification Store to be Trusted Root Certification Authorities and save.

Your Windows environment now trusts the certificate that the initial make up -command created on the WSL2 side.

Install your dev site at this stage

In Windows

• Open the HOSTS file using your preferred HOSTS-editor.
• Get the IP that you see under the section "Added by Docker Desktop"
• Use that IP in a new row with your site address. So for example 192.168.1.101 site.docker.sh

ISSUES

• Issues with the docker container & write permissions on sites

[j-vee]

For dev work, VS Code with its WSL - Remote plugin works wonders.

Read more

When in Ubuntu terminal, type code . to open your current folder in VS Code on the Windows side.

Type explorer.exe . in the terminal to open your current folder in the Windows file browser.

[sebarickert]

Tested with Windows 10 Professional with Debian 10.6

• Install WSL2
• In Microsoft Store search for "Debian" and install it.
  • Additionally you probably want a proper terminal. Search for "Windows terminal" in the store and download it as well.
• Install Docker Desktop and make sure "Use the WSL2 based engine" checkbox is checked in the settings.
  • Also ensure that Docker is enabled for you WSL2 distro. Open Docker GUI Settings -> Resources -> WSL Intregration

In WSL terminal

• sudo apt update && sudo apt upgrade && sudo apt install build-essential
• Copy your ssh key over to ~/.ssh/
  • Test with ssh -T git@github.com. You should get, e.g. Hi {YOURNAME}! You've successfully authenticated, but GitHub does not provide shell access.
  • Fix file permissions if needed.
• Install stonehenge as per the readme
• Open your Stonehenge directory cd ~/stonehenge
• Run make up

DNS configuration

• Open Powershell terminal and run command: Get-DnsClientServerAddress
  • Check correct Interface Index
    • Usually when you have a wired connection it is Ethernet and with wireless it's Wi-Fi
• When you have the correct Interface Index, run this command:
  • You need to run Powershell terminal as an administrator for this command!
  • Set-DnsClientServerAddress -InterfaceIndex {YOUR INTERFACE INDEX NUMBER} -ServerAddresses ("127.0.0.48","1.1.1.1")
• Finally flush your DNS ipconfig -flushdns

If stonehenge can't connect to docker socket, just restart it.

[back-2-95]

@j-vee and @shamalainen

Could you check this PR https://github.com/druidfi/stonehenge/pull/43/ and check the new documentation.

I'd like to have certainty of the following:

• are commands in right context (are they run in linux/wsl2 or in windows/powershell)
• what is actually done in DNS section? Ethernet vs Wifi. Maybe more clarification what is going on.

If there is anything we can automate further, that would be nice.

[j-vee]

The commands look good to me.

Though the doco is missing the section where the rootCA.pem generated by stonehenge gets added to the Windows User Certificates so that you don't get SSL Certificate Errors when viewing the sites on Windows side. So a section before DNS Configuration like

In WSL

Install stonehenge as per the readme Open your Stonehenge directory cd ~/stonehenge Run make up You now have rootCA.pem file in your ~/stonehenge/certs folder cd ~/stonehenge/certs explorer.exe . You now have a Windows Explorer window open for the certs-folder. Copy its path from the address bar. Open Manage user certificates. Open Action -> All tasks -> Import In the dialog that opens up, select Next, Browse and then paste the path from above to the address bar and select the rootCA.pem file for import. In the next step, select the Certification Store to be Trusted Root Certification Authorities and Save. Your Windows environment now trusts the certificate that the initial make up -command created on the WSL2 side.

[back-2-95]

@shamalainen did you have https and certs working?

[sebarickert]

@back-2-95 Currently I have it not working. I need to tell the browser that the site is safe etc. everytime.

[sebarickert]

@back-2-95 @j-vee I had issues adding the certificate via the GUI, so I did it via Powershell (as an admin).

So after You now have a Windows Explorer window open for the certs-folder. Copy its path from the address bar. I opened Powershell as an admin and ran this command: Import-Certificate -Filepath '{THE PATH YOU COPIED}' -CertStoreLocation cert:\CurrentUser\Root, e.g. my path was Import-Certificate -Filepath '\\wsl$\Work\home\coder\stonehenge\certs\rootCA.pem' -CertStoreLocation cert:\CurrentUser\Root where my username is coder and WSL2 machine name is Work

EDIT 1:

This command worked for me, I had to replace CurrentUser with LocalMachine. Import-Certificate -Filepath '{THE PATH YOU COPIED}' -CertStoreLocation cert:\LocalMachine\Root.

EDIT 2:

I got it working through the GUI as well, but had to add Root certificates to LocalComputer instead of CurrentUser.

[back-2-95]

I have now tested your stuff @j-vee and @shamalainen. DNS stuff worked as did the Import-Certificate.

And here is something I put together: https://github.com/druidfi/stonehenge/blob/3e9e7d0a757a35e5b3092a5f20dd779b88455d28/WSL2.md

The oneliner is still WiP but I checked that it really run the code. You can see the script here: https://github.com/druidfi/stonehenge/blob/3e9e7d0a757a35e5b3092a5f20dd779b88455d28/install.ps1

Certificate importing is now automated as I was able to detect WSL name and user so I can create the path to cert. No need to use explorer to copy it. I just hope that \\wsl$\WSL_NAME\home\WSL_USER\stonehenge\certs\rootCA.pem is valid in all WSL distros we want to support.

DNS configuration is still with those manual steps. I cannot find automated solution for that. Basically you need to add that nameserver IP for selected index which might be different for everyone.

[back-2-95]

Update: as we're nearing removal of resolver, WSL2 usage will also be easier. Stay tuned.

[back-2-95]

@j-vee you reported that new resolverless version works fine with WSL2 - could you check if the PR #49 is close to truth?

[j-vee]

@back-2-95 Yup! Looks good to me. I tested most of the manual commands out just now and they all worked fine.