Update/improve npm install instructions for Windows

Change-type: patch
Signed-off-by: Paulo Castro <paulo@balena.io>

INSTALL.md

@@ -13,8 +13,16 @@ There are 3 options to choose from to install balena's CLI:
 Some specific CLI commands have a few extra installation steps: see section [Additional
 Dependencies](#additional-dependencies).
 
-> **Windows users:** We now have a [YouTube video tutorial](https://www.youtube.com/watch?v=2LApclXFqsg)
+> **Windows users:**
-for installing and getting started with the balena CLI on Windows!
+> * There is a [YouTube video tutorial](https://www.youtube.com/watch?v=2LApclXFqsg) for installing
+>   and getting started with the balena CLI on Windows. (The video uses the standalone zip package
+>   option.)
+> * If you are using Microsoft's [Windows Subsystem for
+>   Linux](https://docs.microsoft.com/en-us/windows/wsl/about) (WSL), the recommendation is to
+>   install a balena CLI release for Linux rather than Windows, like the Linux standalone zip
+>   package. An installation with the graphical executable installer for Windows will not run on
+>   WSL. See also [FAQ](https://github.com/balena-io/balena-cli/blob/master/TROUBLESHOOTING.md) for
+>   using balena CLI with WSL and Docker Desktop for Windows.
 
 ## Executable Installer
 
@@ -69,17 +77,31 @@ If you are a Node.js developer, you may wish to install the balena CLI via [npm]
 The npm installation involves building native (platform-specific) binary modules, which require
 some additional development tools to be installed first:
 
-* Node.js version 8 or 10 (v12 has not been thoroughly tested yet)
+* Node.js version 8, 10 or 12 (on Linux/Mac, [nvm](https://github.com/nvm-sh/nvm/blob/master/README.md)
+  is recommended)
 * Python 2.7
 * g++ compiler
 * make
 * git
-* On Windows, the `windows-build-tools` npm package should be installed too, running the following
+
-  command in an administrator console (available as "Command Prompt (Admin)" or "Windows PowerShell
+On Windows, the dependencies above and additional ones can be met with:
-  (Admin)" when typing Windows+X):  
+
+* The [MSYS2 shell](https://www.msys2.org/) may be used to provide `git`, `ssh`, `rsync`, `make`
+  and `g++`:
+  * `pacman -S git openssh rsync gcc make`
+  * [Set a Windows environment variable](https://www.onmsft.com/how-to/how-to-set-an-environment-variable-in-windows-10): `MSYS2_PATH_TYPE=inherit`
+  * Note that a bug in the MSYS2 launch script (`msys2_shell.cmd`) makes text-based
+    interactive CLI menus to misbehave. [Check this Github issue for a
+    workaround](https://github.com/msys2/MINGW-packages/issues/1633#issuecomment-240583890).
+* Install the Windows Driver Kit (WDK) which is needed to compile some native Node modules:
+  * [WDK for Windows 10](https://docs.microsoft.com/en-us/windows-hardware/drivers/download-the-wdk)
+  * [WDK for earlier versions of Windows](https://docs.microsoft.com/en-us/windows-hardware/drivers/other-wdk-downloads)
+* Install Node from the [Nodejs website](https://www.howtogeek.com/194041/how-to-open-the-command-prompt-as-administrator-in-windows-8.1/)
+* Install the `windows-build-tools` npm package (which provides Python 2.7 and more), running the following command in an [administrator
+  console](https://www.howtogeek.com/194041/how-to-open-the-command-prompt-as-administrator-in-windows-8.1/):  
   `npm install -g --production windows-build-tools`
 
-With those in place, the CLI installation command is:
+With these dependencies in place, the balena CLI installation command is:
 
 ```sh
 $ npm install balena-cli -g --production --unsafe-perm
@@ -112,12 +134,6 @@ CLI on an Ubuntu Docker image: https://gist.github.com/pdcastro/5d4d96652181e7da
     Check the [README](https://github.com/balena-io/balena-cli/blob/master/README.md) file
     for proxy configuration instructions.
 
-* The `balena sync` command (deprecated) currently requires `rsync` (>= 2.6.9) to be installed:
-  * Linux: `apt-get install rsync`
-  * macOS: [Xcode command-line tools](https://developer.apple.com/xcode/features/) or [homebrew](https://brew.sh/)
-  * Windows: One option is to use the [MinGW](http://www.mingw.org) shell and install the
-    `msys-rsync` package. Check the README file for other shell options under Windows.
-
 ## Configuring SSH keys
 
 The `balena ssh` command requires an SSH key to be added to your balena account. If you had

README.md

@@ -27,11 +27,20 @@ On **Windows,** the standard Command Prompt (`cmd.exe`) and
 are supported. We are aware of users also having a good experience with alternative shells,
 including:
 
-* Microsoft's [Windows Subsystem for Linux](https://docs.microsoft.com/en-us/windows/wsl/about)
+* [MSYS2](https://www.msys2.org/):
-  (a.k.a. Microsoft's "bash for Windows 10")
+  * Install additional packages with the command:  
+    `pacman -S git openssh rsync`
+  * [Set a Windows environment variable](https://www.onmsft.com/how-to/how-to-set-an-environment-variable-in-windows-10): `MSYS2_PATH_TYPE=inherit`
+  * Note that a bug in the MSYS2 launch script (`msys2_shell.cmd`) makes text-based interactive CLI
+    menus to break. [Check this Github issue for a
+    workaround](https://github.com/msys2/MINGW-packages/issues/1633#issuecomment-240583890).
+* [MSYS](http://www.mingw.org/wiki/MSYS): select the `msys-rsync` and `msys-openssh` packages too
 * [Git for Windows](https://git-for-windows.github.io/)
-* [MSYS](http://www.mingw.org/wiki/MSYS) and [MSYS2](https://www.msys2.org/) (install the
+* Microsoft's [Windows Subsystem for Linux](https://docs.microsoft.com/en-us/windows/wsl/about)
-  `msys-rsync` and `msys-openssh` packages too)
+  (WSL). In this case, a Linux distribution like Ubuntu is installed via the Microsoft Store, and a
+  balena CLI release **for Linux** is recommended. See
+  [FAQ](https://github.com/balena-io/balena-cli/blob/master/TROUBLESHOOTING.md) for using balena
+  CLI with WSL and Docker Desktop for Windows.
 
 On **macOS** and **Linux,** the standard terminal window is supported. _Optionally,_ `bash` command
 auto completion may be enabled by copying the

TROUBLESHOOTING.md

@@ -88,7 +88,7 @@ $ sudo chown -R <user> $HOME/.balena
 
 Users sometimes come across broken line wrapping or cursor behavior in text terminals, for example when long command lines are typed in a `balena ssh` session, or when using text editors like `vim` or `nano`. This is not something specific to the balena CLI, being also a commonly reported issue with standard remote terminal tools like `ssh` or `telnet`. It is often a remote shell configuration issue (files like `/etc/profile`, `~/.bash_profile`, `~/.bash_login`, `~/.profile` and the like), including UTF-8 misconfiguration, the use of unsupported ASCII control characters in shell prompt formatting (e.g. the `$PS1` env var) or the output of tools or log files that use colored text. The issue can sometimes be fixed by resizing the client terminal window, or by running one or more of the following commands on the shell:
 
-```
+```sh
 export TERMINAL=linux
 stty sane
 shopt -s checkwinsize
@@ -108,3 +108,21 @@ If nothing seems to help, consider also using a different client-side terminal a
 * Linux: xterm, KDE Konsole, GNOME Terminal
 * Mac: Terminal, iTerm2
 * Windows: PowerShell, PuTTY, WSL (Windows Subsystem for Linux)
+
+## "Docker seems to be unavailable" error when using Windows Subsystem for Linux (WSL)
+
+When running on WSL, the recommendation is to install a CLI release for Linux, like the standalone
+zip package for Linux. However, commands like "balena build" that contact a local Docker daemon,
+like the Docker Desktop for Windows, will try to reach Docker at the Unix socket path
+`/var/run/docker.sock`, while Docker Desktop for Windows uses a Windows named pipe at
+`//./pipe/docker_engine` (which the Linux CLI on WSL cannot use). A solution is:
+
+- Open the Docker Desktop for Windows settings panel and tick the checkbox _"Expose daemon on tcp://localhost:2375 without TLS"._
+- On the WSL command line, set an env var:  
+`export DOCKER_HOST=tcp://localhost:2375`  
+Alternatively, use the command-line options `-h 127.0.0.1 -p 2375` for commands like `balena build` and `balena deploy`.
+
+Further reference:
+
+- https://techcommunity.microsoft.com/t5/Containers/WSL-Interoperability-with-Docker/ba-p/382405
+- https://forums.docker.com/t/wsl-and-docker-for-windows-cannot-connect-to-the-docker-daemon-at-tcp-localhost-2375-is-the-docker-daemon-running/63571/12

doc/cli.markdown

@@ -20,11 +20,20 @@ On **Windows,** the standard Command Prompt (`cmd.exe`) and
 are supported. We are aware of users also having a good experience with alternative shells,
 including:
 
-* Microsoft's [Windows Subsystem for Linux](https://docs.microsoft.com/en-us/windows/wsl/about)
+* [MSYS2](https://www.msys2.org/):
-  (a.k.a. Microsoft's "bash for Windows 10")
+  * Install additional packages with the command:  
+    `pacman -S git openssh rsync`
+  * [Set a Windows environment variable](https://www.onmsft.com/how-to/how-to-set-an-environment-variable-in-windows-10): `MSYS2_PATH_TYPE=inherit`
+  * Note that a bug in the MSYS2 launch script (`msys2_shell.cmd`) makes text-based interactive CLI
+    menus to break. [Check this Github issue for a
+    workaround](https://github.com/msys2/MINGW-packages/issues/1633#issuecomment-240583890).
+* [MSYS](http://www.mingw.org/wiki/MSYS): select the `msys-rsync` and `msys-openssh` packages too
 * [Git for Windows](https://git-for-windows.github.io/)
-* [MSYS](http://www.mingw.org/wiki/MSYS) and [MSYS2](https://www.msys2.org/) (install the
+* Microsoft's [Windows Subsystem for Linux](https://docs.microsoft.com/en-us/windows/wsl/about)
-  `msys-rsync` and `msys-openssh` packages too)
+  (WSL). In this case, a Linux distribution like Ubuntu is installed via the Microsoft Store, and a
+  balena CLI release **for Linux** is recommended. See
+  [FAQ](https://github.com/balena-io/balena-cli/blob/master/TROUBLESHOOTING.md) for using balena
+  CLI with WSL and Docker Desktop for Windows.
 
 On **macOS** and **Linux,** the standard terminal window is supported. _Optionally,_ `bash` command
 auto completion may be enabled by copying the