ExternalVendorCode/balena-cli
1
0
Fork 0
mirror of https://github.com/balena-io/balena-cli.git synced 2024-12-18 21:27:51 +00:00
Code Issues Actions Packages Projects Releases Wiki Activity

Update/improve npm install instructions for Windows

Browse Source 
Change-type: patch
Signed-off-by: Paulo Castro <paulo@balena.io>
This commit is contained in:
Paulo Castro 2019-10-09 16:32:54 +01:00
parent cc45d872c7
commit a8fcd85f1a
4 changed files with 74 additions and 22 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

42
INSTALL.md
View File

@ -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)
for installing and getting started with the balena CLI on Windows!
> **Windows users:**
> * 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
(Admin)" when typing Windows+X):
On Windows, the dependencies above and additional ones can be met with:
* 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

17
README.md
View File

@ -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)
(a.k.a. Microsoft's "bash for Windows 10")
* [MSYS2](https://www.msys2.org/):
* 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
`msys-rsync` and `msys-openssh` packages too)
* Microsoft's [Windows Subsystem for Linux](https://docs.microsoft.com/en-us/windows/wsl/about)
(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

20
TROUBLESHOOTING.md
View File

@ -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

17
doc/cli.markdown
View File

@ -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)
(a.k.a. Microsoft's "bash for Windows 10")
* [MSYS2](https://www.msys2.org/):
* 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
`msys-rsync` and `msys-openssh` packages too)
* Microsoft's [Windows Subsystem for Linux](https://docs.microsoft.com/en-us/windows/wsl/about)
(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