mirror of
https://github.com/balena-io/balena-cli.git
synced 2024-12-20 06:07:55 +00:00
Reorganize and simplify installation instructions
Change-type: patch
This commit is contained in:
Paulo Castro
parent
b9c3b57b85
commit
f98c25eaee
150
INSTALL-ADVANCED.md
Normal file
150
INSTALL-ADVANCED.md
Normal file
@ -0,0 +1,150 @@
|
|||||||
|
# balenaCLI Advanced Installation Options
|
||||||
|
|
||||||
|
**These are alternative, advanced installation options. Most users would prefer the [recommended,
|
||||||
|
streamlined installation
|
||||||
|
instructions](https://github.com/balena-io/balena-cli/blob/master/INSTALL.md).**
|
||||||
|
|
||||||
|
There are 3 options to choose from to install balena's CLI:
|
||||||
|
|
||||||
|
* [Executable Installer](#executable-installer): the easiest method on Windows and macOS, using the
|
||||||
|
traditional graphical desktop application installers.
|
||||||
|
* [Standalone Zip Package](#standalone-zip-package): these are plain zip files with the balenaCLI
|
||||||
|
executable in them: extract and run. Available for all platforms: Linux, Windows, macOS.
|
||||||
|
Recommended also for scripted installation in CI (continuous integration) environments.
|
||||||
|
* [NPM Installation](#npm-installation): recommended for Node.js developers who may be interested
|
||||||
|
in integrating balenaCLI in their existing projects or workflow.
|
||||||
|
|
||||||
|
Some specific CLI commands have a few extra installation steps: see section [Additional
|
||||||
|
Dependencies](#additional-dependencies).
|
||||||
|
|
||||||
|
## Executable Installer
|
||||||
|
|
||||||
|
This is the recommended installation option on macOS and Windows. Follow the specific OS
|
||||||
|
instructions:
|
||||||
|
|
||||||
|
* [Windows](./INSTALL-WINDOWS.md)
|
||||||
|
* [macOS](./INSTALL-MAC.md)
|
||||||
|
|
||||||
|
> Note regarding WSL ([Windows Subsystem for
|
||||||
|
> Linux](https://docs.microsoft.com/en-us/windows/wsl/about))
|
||||||
|
> If you would like to use WSL, follow the [installations instructions for
|
||||||
|
> Linux](./INSTALL-LINUX.md) rather than Windows, as WSL consists of a Linux environment.
|
||||||
|
|
||||||
|
If you had previously installed the CLI using a standalone zip package, it may be a good idea to
|
||||||
|
check your system's `PATH` environment variable for duplicate entries, as the terminal will use the
|
||||||
|
entry that comes first. Check the [Standalone Zip Package](#standalone-zip-package) instructions
|
||||||
|
for how to modify the PATH variable.
|
||||||
|
|
||||||
|
By default, the CLI is installed to the following folders:
|
||||||
|
|
||||||
|
OS | Folders
|
||||||
|
--- | ---
|
||||||
|
Windows: | `C:\Program Files\balena-cli\`
|
||||||
|
macOS: | `/usr/local/lib/balena-cli/` <br> `/usr/local/bin/balena`
|
||||||
|
|
||||||
|
## Standalone Zip Package
|
||||||
|
|
||||||
|
1. Download the latest zip file from the [releases page](https://github.com/balena-io/balena-cli/releases).
|
||||||
|
Look for a file name that ends with the word "standalone", for example:
|
||||||
|
`balena-cli-vX.Y.Z-linux-x64-standalone.zip` ← _also for the Windows Subsystem for Linux_
|
||||||
|
`balena-cli-vX.Y.Z-macOS-x64-standalone.zip`
|
||||||
|
`balena-cli-vX.Y.Z-windows-x64-standalone.zip`
|
||||||
|
|
||||||
|
2. Extract the zip file contents to any folder you choose. The extracted contents will include a
|
||||||
|
`balena-cli` folder.
|
||||||
|
|
||||||
|
3. Add the `balena-cli` folder to the system's `PATH` environment variable.
|
||||||
|
See instructions for:
|
||||||
|
[Linux](https://stackoverflow.com/questions/14637979/how-to-permanently-set-path-on-linux-unix) |
|
||||||
|
[macOS](https://www.architectryan.com/2012/10/02/add-to-the-path-on-mac-os-x-mountain-lion/#.Uydjga1dXDg) |
|
||||||
|
[Windows](https://www.computerhope.com/issues/ch000549.htm)
|
||||||
|
|
||||||
|
> * If you are using macOS Catalina (10.15), [check this known issue and
|
||||||
|
> workaround](https://github.com/balena-io/balena-cli/issues/1479).
|
||||||
|
> * **Linux Alpine** and **Busybox:** the standalone zip package is not currently compatible with
|
||||||
|
> these "compact" Linux distributions, because of the alternative C libraries they ship with.
|
||||||
|
> For these, consider the [NPM Installation](#npm-installation) option.
|
||||||
|
> * Note that moving the `balena` executable out of the extracted `balena-cli` folder on its own
|
||||||
|
> (e.g. moving it to `/usr/local/bin/balena`) will **not** work, as it depends on the other
|
||||||
|
> folders and files also present in the `balena-cli` folder.
|
||||||
|
|
||||||
|
To update the CLI to a new version, download a new release zip file and replace the previous
|
||||||
|
installation folder. To uninstall, simply delete the folder and edit the PATH environment variable
|
||||||
|
as described above.
|
||||||
|
|
||||||
|
## NPM Installation
|
||||||
|
|
||||||
|
If you are a Node.js developer, you may wish to install balenaCLI via [npm](https://www.npmjs.com).
|
||||||
|
The npm installation involves building native (platform-specific) binary modules, which require
|
||||||
|
some additional development tools to be installed first:
|
||||||
|
|
||||||
|
* [Node.js](https://nodejs.org/) version 10 (min **10.20.0**) or 12 (version 14 is not yet fully supported)
|
||||||
|
* **Linux, macOS** and **Windows Subsystem for Linux (WSL):**
|
||||||
|
Installing Node via [nvm](https://github.com/nvm-sh/nvm/blob/master/README.md) is recommended.
|
||||||
|
When the "system" or "default" Node.js and npm packages are installed with "apt-get" in Linux
|
||||||
|
distributions like Ubuntu, users often report permission or compilation errors when running
|
||||||
|
"npm install". This [sample
|
||||||
|
Dockerfile](https://gist.github.com/pdcastro/5d4d96652181e7da685a32caf629dd44) shows the CLI
|
||||||
|
installation steps on an Ubuntu 18.04 base image.
|
||||||
|
* [Python 2.7](https://www.python.org/), [git](https://git-scm.com/), [make](https://www.gnu.org/software/make/), [g++](https://gcc.gnu.org/)
|
||||||
|
* **Linux** and **Windows Subsystem for Linux (WSL):**
|
||||||
|
`sudo apt-get install -y python git make g++`
|
||||||
|
* **macOS:** install Apple's Command Line Tools by running on a Terminal window:
|
||||||
|
`xcode-select --install`
|
||||||
|
|
||||||
|
On **Windows (not WSL),** the dependencies above and additional ones can be met by installing:
|
||||||
|
|
||||||
|
* Node.js from the [Nodejs.org download page](https://nodejs.org/en/download/).
|
||||||
|
* The [MSYS2 shell](https://www.msys2.org/), which provides `git`, `make`, `g++`, `ssh`, `rsync`
|
||||||
|
and more:
|
||||||
|
* `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).
|
||||||
|
* The Windows Driver Kit (WDK), which is needed to compile some native Node modules. It is **not**
|
||||||
|
necessary to install Visual Studio, only the WDK, which is "step 2" in the following guides:
|
||||||
|
* [WDK for Windows 10](https://docs.microsoft.com/en-us/windows-hardware/drivers/download-the-wdk#download-icon-step-2-install-wdk-for-windows-10-version-1903)
|
||||||
|
* [WDK for earlier versions of Windows](https://docs.microsoft.com/en-us/windows-hardware/drivers/other-wdk-downloads#step-2-install-the-wdk)
|
||||||
|
* The [windows-build-tools](https://www.npmjs.com/package/windows-build-tools) npm package (which
|
||||||
|
provides Python 2.7 and more), by running the following command on 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 these dependencies in place, the balenaCLI installation command is:
|
||||||
|
|
||||||
|
```sh
|
||||||
|
$ npm install balena-cli -g --production --unsafe-perm
|
||||||
|
```
|
||||||
|
|
||||||
|
`--unsafe-perm` is required when `npm install` is executed as the root user, or on systems where
|
||||||
|
the global install directory is not user-writable. It allows npm install steps to download and save
|
||||||
|
prebuilt native binaries, and also allows the execution of npm scripts like `postinstall` that are
|
||||||
|
used to patch dependencies. It is usually possible to omit `--unsafe-perm` if installing under a
|
||||||
|
regular (non-root) user account, especially if using a user-managed node installation such as
|
||||||
|
[nvm](https://github.com/creationix/nvm).
|
||||||
|
|
||||||
|
## Additional Dependencies
|
||||||
|
|
||||||
|
The `balena ssh`, `scan`, `build`, `deploy`, `preload` and `os configure` commands may require
|
||||||
|
additional software to be installed. Check the Additional Dependencies sections for each operating
|
||||||
|
system:
|
||||||
|
|
||||||
|
* [Windows](./INSTALL-WINDOWS.md#additional-dependencies)
|
||||||
|
* [macOS](./INSTALL-MAC.md#additional-dependencies)
|
||||||
|
* [Linux](./INSTALL-LINUX.md#additional-dependencies)
|
||||||
|
|
||||||
|
The `build` and `deploy` commands are also capable of using Docker or balenaEngine on a remote
|
||||||
|
server, or on a balenaOS device running a [balenaOS development
|
||||||
|
image](https://www.balena.io/docs/reference/OS/overview/2.x/#dev-vs-prod-images)). Reasons why this
|
||||||
|
may be desirable include:
|
||||||
|
|
||||||
|
* To avoid having to install Docker on the development machine / laptop.
|
||||||
|
* To take advantage of a more powerful server (CPU, memory).
|
||||||
|
* To build or run images "natively" on an ARM device, avoiding the need for QEMU emulation.
|
||||||
|
|
||||||
|
To use a remote Docker Engine (daemon) or balenaEngine, specify the remote machine's IP address and
|
||||||
|
port number with the `--dockerHost` and `--dockerPort` command-line options. For more details,
|
||||||
|
check `balena help build` or the [online
|
||||||
|
reference](https://www.balena.io/docs/reference/cli/#cli-command-reference).
|
||||||
60
INSTALL-LINUX.md
Normal file
60
INSTALL-LINUX.md
Normal file
@ -0,0 +1,60 @@
|
|||||||
|
# balenaCLI Installation Instructions for Linux
|
||||||
|
|
||||||
|
These instructions are for the recommended installation option. They are suitable for most Linux
|
||||||
|
distributions, except notably for **Linux Alpine** or **Busybox**. For these distros, see [advanced
|
||||||
|
installation options](./INSTALL-ADVANCED.md).
|
||||||
|
|
||||||
|
Selected operating system: **Linux**
|
||||||
|
|
||||||
|
1. Download the latest zip file from the [latest release
|
||||||
|
page](https://github.com/balena-io/balena-cli/releases/latest). Look for a file name that ends
|
||||||
|
with "-standalone.zip", for example:
|
||||||
|
`balena-cli-vX.Y.Z-linux-x64-standalone.zip`
|
||||||
|
|
||||||
|
2. Extract the zip file contents to any folder you choose. The extracted contents will include a
|
||||||
|
`balena-cli` folder.
|
||||||
|
|
||||||
|
3. Add the `balena-cli` folder to the system's `PATH` environment variable. There are several
|
||||||
|
ways of achieving this on Linux: See this [StackOverflow post](https://stackoverflow.com/questions/14637979/how-to-permanently-set-path-on-linux-unix).
|
||||||
|
|
||||||
|
No further steps are required to run most balenaCLI commands. The `balena ssh`, `scan`, `build`,
|
||||||
|
`deploy` and `preload` commands may require additional software to be installed, as described
|
||||||
|
below.
|
||||||
|
|
||||||
|
To update balenaCLI to a new version, download a new release zip file and replace the previous
|
||||||
|
installation folder. To uninstall, simply delete the folder and edit the PATH environment variable
|
||||||
|
as described above.
|
||||||
|
|
||||||
|
## Additional Dependencies
|
||||||
|
|
||||||
|
### build, deploy
|
||||||
|
|
||||||
|
These commands require [Docker](https://docs.docker.com/install/overview/) or
|
||||||
|
[balenaEngine](https://www.balena.io/engine/) to be available (on a local or remote machine). Most
|
||||||
|
users will simply follow [Docker's installation
|
||||||
|
instructions](https://docs.docker.com/install/overview/) to install Docker on the same laptop (dev
|
||||||
|
machine) where balenaCLI is installed. The [advanced installation
|
||||||
|
options](./INSTALL-ADVANCED.md) document describes other possibilities.
|
||||||
|
|
||||||
|
### balena ssh
|
||||||
|
|
||||||
|
The `balena ssh` command requires the `ssh` command-line tool to be available. Most Linux
|
||||||
|
distributions will already have it installed. Otherwise, `sudo apt-get install openssh-client`
|
||||||
|
should do the trick on Debian or Ubuntu.
|
||||||
|
|
||||||
|
The `balena ssh` command also requires an SSH key to be added to your balena account: see [SSH
|
||||||
|
Access documentation](https://www.balena.io/docs/learn/manage/ssh-access/). The `balena key*`
|
||||||
|
command set can also be used to list and manage SSH keys: see `balena help -v`.
|
||||||
|
|
||||||
|
### balena scan
|
||||||
|
|
||||||
|
The `balena scan` command requires a multicast DNS (mDNS) service like
|
||||||
|
[Avahi](https://en.wikipedia.org/wiki/Avahi_(software)), which is installed by default on most
|
||||||
|
desktop Linux distributions. Otherwise, on Debian or Ubuntu, the installation command would be
|
||||||
|
`sudo apt-get install avahi-daemon`.
|
||||||
|
|
||||||
|
### balena preload
|
||||||
|
|
||||||
|
Like the `build` and `deploy` commands, the `preload` command requires Docker, with the additional
|
||||||
|
restriction that Docker must be installed on the local machine (because Docker's bind mounting
|
||||||
|
feature is used).
|
||||||
68
INSTALL-MAC.md
Normal file
68
INSTALL-MAC.md
Normal file
@ -0,0 +1,68 @@
|
|||||||
|
# balenaCLI Installation Instructions for macOS
|
||||||
|
|
||||||
|
These instructions are for the recommended installation option. Advanced users may also be
|
||||||
|
interested in [advanced installation options](./INSTALL-ADVANCED.md).
|
||||||
|
|
||||||
|
Selected operating system: **macOS**
|
||||||
|
|
||||||
|
1. Download the installer from the [latest release
|
||||||
|
page](https://github.com/balena-io/balena-cli/releases/latest).
|
||||||
|
Look for a file name that ends with "-installer.pkg":
|
||||||
|
`balena-cli-vX.Y.Z-macOS-x64-installer.pkg`
|
||||||
|
|
||||||
|
2. Double click the downloaded file to run the installer. After the installation completes,
|
||||||
|
close and re-open any open [command
|
||||||
|
terminal](https://www.balena.io/docs/reference/cli/#choosing-a-shell-command-promptterminal)
|
||||||
|
windows (so that the changes made by the installer to the PATH environment variable can take
|
||||||
|
effect).
|
||||||
|
|
||||||
|
3. Check that the installation was successful by running the following commands on a
|
||||||
|
command terminal:
|
||||||
|
* `balena version` - should print the installed CLI version
|
||||||
|
* `balena help` - should print the balenaCLI help
|
||||||
|
|
||||||
|
No further steps are required to run most balenaCLI commands. The `balena ssh`, `build`, `deploy`
|
||||||
|
and `preload` commands may require additional software to be installed, as described below.
|
||||||
|
|
||||||
|
## Additional Dependencies
|
||||||
|
|
||||||
|
### build and deploy
|
||||||
|
|
||||||
|
These commands require [Docker](https://docs.docker.com/install/overview/) or
|
||||||
|
[balenaEngine](https://www.balena.io/engine/) to be available (on a local or remote machine). Most
|
||||||
|
users will simply follow [Docker's installation
|
||||||
|
instructions](https://docs.docker.com/install/overview/) to install Docker on the same laptop (dev
|
||||||
|
machine) where balenaCLI is installed. The [advanced installation
|
||||||
|
options](./INSTALL-ADVANCED.md) document describes other possibilities.
|
||||||
|
|
||||||
|
### balena ssh
|
||||||
|
|
||||||
|
The `balena ssh` command requires the `ssh` command-line tool to be available. To check whether
|
||||||
|
it is already installed, run `ssh` on a Terminal window. If it is not yet installed, the options
|
||||||
|
include:
|
||||||
|
|
||||||
|
* Download the Xcode Command Line Tools from https://developer.apple.com/downloads
|
||||||
|
* Or, if you have Xcode installed, open Xcode, choose Preferences → General → Downloads →
|
||||||
|
Components → Command Line Tools → Install.
|
||||||
|
* Or, install [Homebrew](https://brew.sh/), then `brew install openssh`
|
||||||
|
|
||||||
|
The `balena ssh` command also requires an SSH key to be added to your balena account: see [SSH
|
||||||
|
Access documentation](https://www.balena.io/docs/learn/manage/ssh-access/). The `balena key*`
|
||||||
|
command set can also be used to list and manage SSH keys: see `balena help -v`.
|
||||||
|
|
||||||
|
### balena preload
|
||||||
|
|
||||||
|
Like the `build` and `deploy` commands, the `preload` command requires Docker, with the additional
|
||||||
|
restriction that Docker must be installed on the local machine (because Docker's bind mounting
|
||||||
|
feature is used). Also, for some device types (such as the Raspberry Pi), the `preload` command
|
||||||
|
requires Docker to support the [AUFS storage
|
||||||
|
driver](https://docs.docker.com/storage/storagedriver/aufs-driver/). Unfortunately, Docker Desktop
|
||||||
|
for Windows dropped support for the AUFS filesystem in Docker CE versions greater than 18.06.1. The
|
||||||
|
present workaround is to either:
|
||||||
|
|
||||||
|
* Downgrade Docker Desktop to version 18.06.1. Link: [Docker CE for
|
||||||
|
Mac](https://docs.docker.com/docker-for-mac/release-notes/#docker-community-edition-18061-ce-mac73-2018-08-29)
|
||||||
|
* Install balenaCLI on a Linux machine (as Docker for Linux still supports AUFS). A Linux Virtual
|
||||||
|
Machine also works, but a Docker container is _not_ recommended.
|
||||||
|
|
||||||
|
Long term, we are working on replacing AUFS with overlay2 for the affected device types.
|
||||||
82
INSTALL-WINDOWS.md
Normal file
82
INSTALL-WINDOWS.md
Normal file
@ -0,0 +1,82 @@
|
|||||||
|
# balenaCLI Installation Instructions for Windows
|
||||||
|
|
||||||
|
These instructions are for the recommended installation option. Advanced users may also be
|
||||||
|
interested in [advanced installation options](./INSTALL-ADVANCED.md).
|
||||||
|
|
||||||
|
Selected operating system: **Windows**
|
||||||
|
|
||||||
|
1. Download the installer from the [latest release
|
||||||
|
page](https://github.com/balena-io/balena-cli/releases/latest).
|
||||||
|
Look for a file name that ends with "-installer.exe":
|
||||||
|
`balena-cli-vX.Y.Z-windows-x64-installer.exe`
|
||||||
|
|
||||||
|
2. Double click the downloaded file to run the installer. After the installation completes,
|
||||||
|
close and re-open any open [command
|
||||||
|
terminal](https://www.balena.io/docs/reference/cli/#choosing-a-shell-command-promptterminal)
|
||||||
|
windows (so that the changes made by the installer to the PATH environment variable can take
|
||||||
|
effect).
|
||||||
|
|
||||||
|
3. Check that the installation was successful by running the following commands on a
|
||||||
|
command terminal:
|
||||||
|
* `balena version` - should print the installed CLI version
|
||||||
|
* `balena help` - should print the balenaCLI help
|
||||||
|
|
||||||
|
No further steps are required to run most balenaCLI commands. The `balena ssh`, `scan`, `build`,
|
||||||
|
`deploy`, `preload` and `os configure` commands may require additional software to be installed, as
|
||||||
|
described below.
|
||||||
|
|
||||||
|
## Additional Dependencies
|
||||||
|
|
||||||
|
### build and deploy
|
||||||
|
|
||||||
|
These commands require [Docker](https://docs.docker.com/install/overview/) or
|
||||||
|
[balenaEngine](https://www.balena.io/engine/) to be available (on a local or remote machine). Most
|
||||||
|
users will simply follow [Docker's installation
|
||||||
|
instructions](https://docs.docker.com/install/overview/) to install Docker on the same laptop (dev
|
||||||
|
machine) where balenaCLI is installed. The [advanced installation
|
||||||
|
options](./INSTALL-ADVANCED.md) document describes other possibilities.
|
||||||
|
|
||||||
|
### balena ssh
|
||||||
|
|
||||||
|
The `balena ssh` command requires the `ssh` command-line tool to be available. Microsoft started
|
||||||
|
distributing an SSH client with Windows 10, which is automatically installed through Windows
|
||||||
|
Update. To check whether it is installed, run `ssh` on a Windows Command Prompt or PowerShell. It
|
||||||
|
can also be [manually
|
||||||
|
installed](https://docs.microsoft.com/en-us/windows-server/administration/openssh/openssh_install_firstuse)
|
||||||
|
if needed. For older versions of Windows, there are several ssh/OpenSSH clients provided by 3rd
|
||||||
|
parties.
|
||||||
|
|
||||||
|
The `balena ssh` command also requires an SSH key to be added to your balena account: see [SSH
|
||||||
|
Access documentation](https://www.balena.io/docs/learn/manage/ssh-access/). The `balena key*`
|
||||||
|
command set can also be used to list and manage SSH keys: see `balena help -v`.
|
||||||
|
|
||||||
|
### balena scan
|
||||||
|
|
||||||
|
The `balena scan` command requires a multicast DNS (mDNS) service like Apple's Bonjour.
|
||||||
|
Many Windows machines will already have this service installed, as it is bundled in popular
|
||||||
|
applications such as Skype (Wikipedia lists [several others](https://en.wikipedia.org/wiki/Bonjour_(software))).
|
||||||
|
Otherwise, Bonjour for Windows can be downloaded and installed from: https://support.apple.com/kb/DL999
|
||||||
|
|
||||||
|
### balena preload
|
||||||
|
|
||||||
|
Like the `build` and `deploy` commands, the `preload` command requires Docker, with the additional
|
||||||
|
restriction that Docker must be installed on the local machine (because Docker's bind mounting
|
||||||
|
feature is used). Also, for some device types (such as the Raspberry Pi), the `preload` command
|
||||||
|
requires Docker to support the [AUFS storage
|
||||||
|
driver](https://docs.docker.com/storage/storagedriver/aufs-driver/). Unfortunately, Docker Desktop
|
||||||
|
for Windows dropped support for the AUFS filesystem in Docker CE versions greater than 18.06.1. The
|
||||||
|
present workaround is to either:
|
||||||
|
|
||||||
|
* Downgrade Docker Desktop to version 18.06.1. Link: [Docker CE for
|
||||||
|
Windows](https://docs.docker.com/docker-for-windows/release-notes/#docker-community-edition-18061-ce-win73-2018-08-29)
|
||||||
|
* Install balenaCLI on a Linux machine (as Docker for Linux still supports AUFS). A Linux Virtual
|
||||||
|
Machine also works, but a Docker container is _not_ recommended.
|
||||||
|
|
||||||
|
Long term, we are working on replacing AUFS with overlay2 for the affected device types.
|
||||||
|
|
||||||
|
### balena os configure
|
||||||
|
|
||||||
|
* The `balena os configure` command is currently not supported on Windows natively, but works with
|
||||||
|
the [Windows Subsystem for Linux](https://docs.microsoft.com/en-us/windows/wsl/about) (WSL). When
|
||||||
|
using WSL, [install balenaCLI for
|
||||||
|
Linux](https://github.com/balena-io/balena-cli/blob/master/INSTALL-LINUX.md).
|
||||||
235
INSTALL.md
235
INSTALL.md
@ -1,231 +1,12 @@
|
|||||||
# balenaCLI Installation Instructions
|
# balenaCLI Installation Instructions
|
||||||
|
|
||||||
There are 3 options to choose from to install balena's CLI:
|
Please select your operating system:
|
||||||
|
|
||||||
* [Executable Installer](#executable-installer): the easiest method on Windows and macOS, using the
|
* [Windows](./INSTALL-WINDOWS.md)
|
||||||
traditional graphical desktop application installers.
|
* [macOS](./INSTALL-MAC.md)
|
||||||
* [Standalone Zip Package](#standalone-zip-package): these are plain zip files with the balena CLI
|
* [Linux](./INSTALL-LINUX.md)
|
||||||
executable in them: extract and run. Available for all platforms: Linux, Windows, macOS.
|
|
||||||
Recommended also for scripted installation in CI (continuous integration) environments.
|
|
||||||
* [NPM Installation](#npm-installation): recommended for Node.js developers who may be interested
|
|
||||||
in integrating the balena CLI in their existing projects or workflow.
|
|
||||||
|
|
||||||
Some specific CLI commands have a few extra installation steps: see section [Additional
|
> Note regarding WSL ([Windows Subsystem for
|
||||||
Dependencies](#additional-dependencies).
|
> Linux](https://docs.microsoft.com/en-us/windows/wsl/about))
|
||||||
|
> If you would like to use WSL, follow the installations instructions for Linux
|
||||||
> **Windows users:**
|
> rather than Windows, as WSL consists of a Linux environment.
|
||||||
> * 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), install a balena CLI release
|
|
||||||
> for Linux rather than for Windows, like the standalone zip package for Linux. An installation
|
|
||||||
> with the graphical executable installer for Windows will **not** work with WSL.
|
|
||||||
|
|
||||||
## Executable Installer
|
|
||||||
|
|
||||||
Recommended for Windows (but not Windows Subsystem for Linux) and macOS:
|
|
||||||
|
|
||||||
1. Download the latest installer from the [releases page](https://github.com/balena-io/balena-cli/releases).
|
|
||||||
Look for a file name that ends with "-installer", for example:
|
|
||||||
`balena-cli-vX.Y.Z-windows-x64-installer.exe`
|
|
||||||
`balena-cli-vX.Y.Z-macOS-x64-installer.pkg`
|
|
||||||
|
|
||||||
2. Double click the downloaded file to run the installer.
|
|
||||||
_If you are using macOS Catalina (10.15), [check this known issue and
|
|
||||||
workaround](https://github.com/balena-io/balena-cli/issues/1479)._
|
|
||||||
|
|
||||||
3. After the installation completes, close and re-open any open [command
|
|
||||||
terminal](https://www.balena.io/docs/reference/cli/#choosing-a-shell-command-promptterminal)
|
|
||||||
windows so that the changes made by the installer to the PATH environment variable can take
|
|
||||||
effect. Check that the installation was successful by running the following commands on a
|
|
||||||
command terminal:
|
|
||||||
|
|
||||||
* `balena version` - should print the installed CLI version
|
|
||||||
* `balena help` - should print the balena CLI help
|
|
||||||
|
|
||||||
> Note: If you had previously installed the CLI using a standalone zip package, it may be a good
|
|
||||||
> idea to check your system's `PATH` environment variable for duplicate entries, as the terminal
|
|
||||||
> will use the entry that comes first. Check the [Standalone Zip Package](#standalone-zip-package)
|
|
||||||
> instructions for how to modify the PATH variable.
|
|
||||||
|
|
||||||
By default, the CLI is installed to the following folders:
|
|
||||||
|
|
||||||
OS | Folders
|
|
||||||
--- | ---
|
|
||||||
Windows: | `C:\Program Files\balena-cli\`
|
|
||||||
macOS: | `/usr/local/lib/balena-cli/` <br> `/usr/local/bin/balena`
|
|
||||||
|
|
||||||
## Standalone Zip Package
|
|
||||||
|
|
||||||
1. Download the latest zip file from the [releases page](https://github.com/balena-io/balena-cli/releases).
|
|
||||||
Look for a file name that ends with the word "standalone", for example:
|
|
||||||
`balena-cli-vX.Y.Z-linux-x64-standalone.zip` ← _also for the Windows Subsystem for Linux_
|
|
||||||
`balena-cli-vX.Y.Z-macOS-x64-standalone.zip`
|
|
||||||
`balena-cli-vX.Y.Z-windows-x64-standalone.zip`
|
|
||||||
|
|
||||||
2. Extract the zip file contents to any folder you choose. The extracted contents will include a
|
|
||||||
`balena-cli` folder.
|
|
||||||
|
|
||||||
3. Add the `balena-cli` folder to the system's `PATH` environment variable.
|
|
||||||
See instructions for:
|
|
||||||
[Linux](https://stackoverflow.com/questions/14637979/how-to-permanently-set-path-on-linux-unix) |
|
|
||||||
[macOS](https://www.architectryan.com/2012/10/02/add-to-the-path-on-mac-os-x-mountain-lion/#.Uydjga1dXDg) |
|
|
||||||
[Windows](https://www.computerhope.com/issues/ch000549.htm)
|
|
||||||
|
|
||||||
> * If you are using macOS Catalina (10.15), [check this known issue and
|
|
||||||
> workaround](https://github.com/balena-io/balena-cli/issues/1479).
|
|
||||||
> * **Linux Alpine** and **Busybox:** the standalone zip package is not currently compatible with
|
|
||||||
> these "compact" Linux distributions, because of the alternative C libraries they ship with.
|
|
||||||
> It should however work with all "desktop" or "server" distributions, e.g. Ubuntu, Debian, Suse,
|
|
||||||
> Fedora, Arch Linux and many more.
|
|
||||||
> * Note that moving the `balena` executable out of the extracted `balena-cli` folder on its own
|
|
||||||
> (e.g. moving it to `/usr/local/bin/balena`) will **not** work, as it depends on the other
|
|
||||||
> folders and files also present in the `balena-cli` folder.
|
|
||||||
|
|
||||||
To update the CLI to a new version, download a new release zip file and replace the previous
|
|
||||||
installation folder. To uninstall, simply delete the folder and edit the PATH environment variable
|
|
||||||
as described above.
|
|
||||||
|
|
||||||
## NPM Installation
|
|
||||||
|
|
||||||
If you are a Node.js developer, you may wish to install the balena CLI via [npm](https://www.npmjs.com).
|
|
||||||
The npm installation involves building native (platform-specific) binary modules, which require
|
|
||||||
some additional development tools to be installed first:
|
|
||||||
|
|
||||||
* [Node.js](https://nodejs.org/) version 10 (min **10.20.0**) or 12 (version 14 is not yet fully supported)
|
|
||||||
* **Linux, macOS** and **Windows Subsystem for Linux (WSL):**
|
|
||||||
Installing Node via [nvm](https://github.com/nvm-sh/nvm/blob/master/README.md) is recommended.
|
|
||||||
When the "system" or "default" Node.js and npm packages are installed with "apt-get" in Linux
|
|
||||||
distributions like Ubuntu, users often report permission or compilation errors when running
|
|
||||||
"npm install". This [sample
|
|
||||||
Dockerfile](https://gist.github.com/pdcastro/5d4d96652181e7da685a32caf629dd44) shows the CLI
|
|
||||||
installation steps on an Ubuntu 18.04 base image.
|
|
||||||
* [Python 2.7](https://www.python.org/), [git](https://git-scm.com/), [make](https://www.gnu.org/software/make/), [g++](https://gcc.gnu.org/)
|
|
||||||
* **Linux** and **Windows Subsystem for Linux (WSL):**
|
|
||||||
`sudo apt-get install -y python git make g++`
|
|
||||||
* **macOS:** install Apple's Command Line Tools by running on a Terminal window:
|
|
||||||
`xcode-select --install`
|
|
||||||
|
|
||||||
On **Windows (not WSL),** the dependencies above and additional ones can be met by installing:
|
|
||||||
|
|
||||||
* Node.js from the [Nodejs.org download page](https://nodejs.org/en/download/).
|
|
||||||
* The [MSYS2 shell](https://www.msys2.org/), which provides `git`, `make`, `g++`, `ssh`, `rsync`
|
|
||||||
and more:
|
|
||||||
* `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).
|
|
||||||
* The Windows Driver Kit (WDK), which is needed to compile some native Node modules. It is **not**
|
|
||||||
necessary to install Visual Studio, only the WDK, which is "step 2" in the following guides:
|
|
||||||
* [WDK for Windows 10](https://docs.microsoft.com/en-us/windows-hardware/drivers/download-the-wdk#download-icon-step-2-install-wdk-for-windows-10-version-1903)
|
|
||||||
* [WDK for earlier versions of Windows](https://docs.microsoft.com/en-us/windows-hardware/drivers/other-wdk-downloads#step-2-install-the-wdk)
|
|
||||||
* The [windows-build-tools](https://www.npmjs.com/package/windows-build-tools) npm package (which
|
|
||||||
provides Python 2.7 and more), by running the following command on 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 these dependencies in place, the balena CLI installation command is:
|
|
||||||
|
|
||||||
```sh
|
|
||||||
$ npm install balena-cli -g --production --unsafe-perm
|
|
||||||
```
|
|
||||||
|
|
||||||
`--unsafe-perm` is required when `npm install` is executed as the root user, or on systems where
|
|
||||||
the global install directory is not user-writable. It allows npm install steps to download and save
|
|
||||||
prebuilt native binaries, and also allows the execution of npm scripts like `postinstall` that are
|
|
||||||
used to patch dependencies. It is usually possible to omit `--unsafe-perm` if installing under a
|
|
||||||
regular (non-root) user account, especially if using a user-managed node installation such as
|
|
||||||
[nvm](https://github.com/creationix/nvm).
|
|
||||||
|
|
||||||
|
|
||||||
## Additional Dependencies
|
|
||||||
|
|
||||||
* The `balena ssh` command requires a recent version of the `ssh` command-line tool to be available:
|
|
||||||
* macOS and Linux usually already have it installed. Otherwise, search for the available packages
|
|
||||||
on your specific Linux distribution, or for the Mac consider the [Xcode command-line
|
|
||||||
tools](https://developer.apple.com/xcode/features/) or [homebrew](https://brew.sh/).
|
|
||||||
|
|
||||||
* Microsoft started distributing an SSH client with Windows 10, which we understand is
|
|
||||||
automatically installed through Windows Update, but can be manually installed too
|
|
||||||
([more information](https://docs.microsoft.com/en-us/windows-server/administration/openssh/openssh_install_firstuse)).
|
|
||||||
For other versions of Windows, there are several ssh/OpenSSH clients provided by 3rd parties.
|
|
||||||
|
|
||||||
* The [`proxytunnel`](http://proxytunnel.sourceforge.net/) package (command-line tool) is needed
|
|
||||||
for the `balena ssh` command to work behind a proxy. It is available for Linux distributions
|
|
||||||
like Ubuntu/Debian (`apt install proxytunnel`), and for macOS through
|
|
||||||
[Homebrew](https://brew.sh/). Windows support is limited to the Windows Subsystem for Linux
|
|
||||||
(e.g., by installing Ubuntu through the Microsoft App Store). Check the
|
|
||||||
[README](https://github.com/balena-io/balena-cli/blob/master/README.md) file for proxy
|
|
||||||
configuration instructions.
|
|
||||||
|
|
||||||
* The `balena preload`, `balena build` and `balena deploy --build` commands require
|
|
||||||
[Docker](https://docs.docker.com/install/overview/) or [balenaEngine](https://www.balena.io/engine/)
|
|
||||||
to be available:
|
|
||||||
* The `balena preload` command requires the Docker Engine to support the [AUFS storage
|
|
||||||
driver](https://docs.docker.com/storage/storagedriver/aufs-driver/). Docker Desktop for Mac and
|
|
||||||
Windows dropped support for the AUFS filesystem in Docker CE versions greater than 18.06.1, so
|
|
||||||
the workaround is to downgrade to version 18.06.1 (links: [Docker CE for
|
|
||||||
Windows](https://docs.docker.com/docker-for-windows/release-notes/#docker-community-edition-18061-ce-win73-2018-08-29)
|
|
||||||
and [Docker CE for
|
|
||||||
Mac](https://docs.docker.com/docker-for-mac/release-notes/#docker-community-edition-18061-ce-mac73-2018-08-29)).
|
|
||||||
See more details in [CLI issue 1099](https://github.com/balena-io/balena-cli/issues/1099).
|
|
||||||
* Commonly, Docker is installed on the same machine where the CLI is being used, but the
|
|
||||||
`balena build` and `balena deploy` commands can also use a remote Docker Engine (daemon)
|
|
||||||
or balenaEngine (which could be a remote device running a [balenaOS development
|
|
||||||
image](https://www.balena.io/docs/reference/OS/overview/2.x/#dev-vs-prod-images)) by specifying
|
|
||||||
its IP address and port number as command-line options. Check the documentation for each
|
|
||||||
command, e.g. `balena help build`, or the [online
|
|
||||||
reference](https://www.balena.io/docs/reference/cli/#cli-command-reference).
|
|
||||||
* If you are using Microsoft's [Windows Subsystem for
|
|
||||||
Linux](https://docs.microsoft.com/en-us/windows/wsl/about) (WSL) and Docker Desktop for
|
|
||||||
Windows, check the [FAQ item "Docker seems to be
|
|
||||||
unavailable"](https://github.com/balena-io/balena-cli/blob/master/TROUBLESHOOTING.md#docker-seems-to-be-unavailable-error-when-using-windows-subsystem-for-linux-wsl).
|
|
||||||
|
|
||||||
* The `balena scan` command requires a multicast DNS (mDNS) service like Bonjour or Avahi:
|
|
||||||
* On Windows, check if 'Bonjour' is installed (Control Panel > Programs and Features).
|
|
||||||
If not, you can download Bonjour for Windows from https://support.apple.com/kb/DL999
|
|
||||||
* Most 'desktop' Linux distributions ship with [Avahi](https://en.wikipedia.org/wiki/Avahi_(software)).
|
|
||||||
Search for the installation command for your distribution. E.g. for Ubuntu:
|
|
||||||
`sudo apt-get install avahi-daemon`
|
|
||||||
* macOS comes with [Bonjour](https://en.wikipedia.org/wiki/Bonjour_(software)) built-in.
|
|
||||||
|
|
||||||
* The `balena os configure` command is currently not supported on Windows natively. Windows users are advised
|
|
||||||
to install the [Windows Subsystem for Linux](https://docs.microsoft.com/en-us/windows/wsl/about) (WSL)
|
|
||||||
with Ubuntu, and use the Linux release of the balena CLI.
|
|
||||||
|
|
||||||
|
|
||||||
## Configuring SSH keys
|
|
||||||
|
|
||||||
The `balena ssh` command requires an SSH key to be added to your balena account. If you had
|
|
||||||
already added a SSH key in order to [deploy with 'git push'](https://www.balena.io/docs/learn/getting-started/raspberrypi3/nodejs/#adding-an-ssh-key),
|
|
||||||
then you are probably done and may skip this section. You can check whether you already have
|
|
||||||
an SSH key in your balena account with the `balena keys` command, or by visiting the
|
|
||||||
[balena web dashboard](https://dashboard.balena-cloud.com/), clicking on your name -> Preferences
|
|
||||||
-> SSH Keys.
|
|
||||||
|
|
||||||
> Note: An "SSH key" actually consists of a public/private key pair. A typical name for the private
|
|
||||||
> key file is "id_rsa", and a typical name for the public key file is "id_rsa.pub". Both key files
|
|
||||||
> are saved to your computer (with the private key optionally protected by a password), but only
|
|
||||||
> the public key is saved to your balena account. This means that if you change computers or
|
|
||||||
> otherwise lose the private key, _you cannot recover the private key through your balena account._
|
|
||||||
> You can however add new keys, and delete the old ones.
|
|
||||||
|
|
||||||
If you don't have an SSH key in your balena account:
|
|
||||||
|
|
||||||
* If you have an existing SSH key in your computer that you would like to use, you can add it
|
|
||||||
to your balena account through the balena web dashboard (Preferences -> SSH Keys), or through
|
|
||||||
the CLI itself:
|
|
||||||
|
|
||||||
```bash
|
|
||||||
# Windows 10 (cmd.exe prompt) example:
|
|
||||||
$ balena key add MyKey %userprofile%\.ssh\id_rsa.pub
|
|
||||||
# Linux / macOS example:
|
|
||||||
$ balena key add MyKey ~/.ssh/id_rsa.pub
|
|
||||||
```
|
|
||||||
|
|
||||||
* To generate a new key, you can follow [GitHub's documentation](https://help.github.com/en/articles/generating-a-new-ssh-key-and-adding-it-to-the-ssh-agent),
|
|
||||||
skipping the step about adding the key to your GitHub account, and instead adding the key to
|
|
||||||
your balena account as described above.
|
|
||||||
|
|||||||
21
README.md
21
README.md
@ -88,13 +88,20 @@ HTTP(S) proxies can be configured through any of the following methods, in prece
|
|||||||
* The `HTTPS_PROXY` and/or `HTTP_PROXY` environment variables, in the same URL format as
|
* The `HTTPS_PROXY` and/or `HTTP_PROXY` environment variables, in the same URL format as
|
||||||
`BALENARC_PROXY`.
|
`BALENARC_PROXY`.
|
||||||
|
|
||||||
> Note: The `balena ssh` command has additional setup requirements to work behind a proxy.
|
#### Proxy setup for balena ssh
|
||||||
> Check the [installation instructions](https://github.com/balena-io/balena-cli/blob/master/INSTALL.md),
|
|
||||||
> and ensure that the proxy server is configured to allow proxy requests to ssh port 22, using
|
In order to work behind a proxy server, the `balena ssh` command requires the
|
||||||
> SSL encryption. For example, in the case of the [Squid](http://www.squid-cache.org/) proxy
|
[`proxytunnel`](http://proxytunnel.sourceforge.net/) package (command-line tool) to be installed.
|
||||||
> server, it should be configured with the following rules in the `squid.conf` file:
|
`proxytunnel` is available for Linux distributions like Ubuntu/Debian (`apt install proxytunnel`),
|
||||||
> `acl SSL_ports port 22`
|
and for macOS through [Homebrew](https://brew.sh/). Windows support is limited to the [Windows
|
||||||
> `acl Safe_ports port 22`
|
Subsystem for Linux](https://docs.microsoft.com/en-us/windows/wsl/about) (e.g., by installing
|
||||||
|
Ubuntu through the Microsoft App Store).
|
||||||
|
|
||||||
|
Ensure that the proxy server is configured to allow proxy requests to ssh port 22, using
|
||||||
|
SSL encryption. For example, in the case of the [Squid](http://www.squid-cache.org/) proxy
|
||||||
|
server, it should be configured with the following rules in the `squid.conf` file:
|
||||||
|
`acl SSL_ports port 22`
|
||||||
|
`acl Safe_ports port 22`
|
||||||
|
|
||||||
#### Proxy exclusion
|
#### Proxy exclusion
|
||||||
|
|
||||||
|
|||||||
@ -81,13 +81,20 @@ HTTP(S) proxies can be configured through any of the following methods, in prece
|
|||||||
* The `HTTPS_PROXY` and/or `HTTP_PROXY` environment variables, in the same URL format as
|
* The `HTTPS_PROXY` and/or `HTTP_PROXY` environment variables, in the same URL format as
|
||||||
`BALENARC_PROXY`.
|
`BALENARC_PROXY`.
|
||||||
|
|
||||||
> Note: The `balena ssh` command has additional setup requirements to work behind a proxy.
|
#### Proxy setup for balena ssh
|
||||||
> Check the [installation instructions](https://github.com/balena-io/balena-cli/blob/master/INSTALL.md),
|
|
||||||
> and ensure that the proxy server is configured to allow proxy requests to ssh port 22, using
|
In order to work behind a proxy server, the `balena ssh` command requires the
|
||||||
> SSL encryption. For example, in the case of the [Squid](http://www.squid-cache.org/) proxy
|
[`proxytunnel`](http://proxytunnel.sourceforge.net/) package (command-line tool) to be installed.
|
||||||
> server, it should be configured with the following rules in the `squid.conf` file:
|
`proxytunnel` is available for Linux distributions like Ubuntu/Debian (`apt install proxytunnel`),
|
||||||
> `acl SSL_ports port 22`
|
and for macOS through [Homebrew](https://brew.sh/). Windows support is limited to the [Windows
|
||||||
> `acl Safe_ports port 22`
|
Subsystem for Linux](https://docs.microsoft.com/en-us/windows/wsl/about) (e.g., by installing
|
||||||
|
Ubuntu through the Microsoft App Store).
|
||||||
|
|
||||||
|
Ensure that the proxy server is configured to allow proxy requests to ssh port 22, using
|
||||||
|
SSL encryption. For example, in the case of the [Squid](http://www.squid-cache.org/) proxy
|
||||||
|
server, it should be configured with the following rules in the `squid.conf` file:
|
||||||
|
`acl SSL_ports port 22`
|
||||||
|
`acl Safe_ports port 22`
|
||||||
|
|
||||||
#### Proxy exclusion
|
#### Proxy exclusion
|
||||||
|
|
||||||
@ -1293,15 +1300,30 @@ balenaCloud ID for the SSH key
|
|||||||
|
|
||||||
## key add <name> [path]
|
## key add <name> [path]
|
||||||
|
|
||||||
Register an SSH in balenaCloud for the logged in user.
|
Add an SSH key to the balenaCloud account of the logged in user.
|
||||||
|
|
||||||
If `path` is omitted, the command will attempt
|
If `path` is omitted, the command will attempt to read the SSH key from stdin.
|
||||||
to read the SSH key from stdin.
|
|
||||||
|
About SSH keys
|
||||||
|
An "SSH key" actually consists of a public/private key pair. A typical name
|
||||||
|
for the private key file is "id_rsa", and a typical name for the public key
|
||||||
|
file is "id_rsa.pub". Both key files are saved to your computer (with the
|
||||||
|
private key optionally protected by a password), but only the public key is
|
||||||
|
saved to your balena account. This means that if you change computers or
|
||||||
|
otherwise lose the private key, you cannot recover the private key through
|
||||||
|
your balena account. You can however add new keys, and delete the old ones.
|
||||||
|
|
||||||
|
To generate a new SSH key pair, a nice guide can be found in GitHub's docs:
|
||||||
|
https://help.github.com/en/articles/generating-a-new-ssh-key-and-adding-it-to-the-ssh-agent
|
||||||
|
Skip the step about adding the key to a GitHub account, and instead add it to
|
||||||
|
your balena account.
|
||||||
|
|
||||||
Examples:
|
Examples:
|
||||||
|
|
||||||
$ balena key add Main ~/.ssh/id_rsa.pub
|
$ balena key add Main ~/.ssh/id_rsa.pub
|
||||||
$ cat ~/.ssh/id_rsa.pub | balena key add Main
|
$ cat ~/.ssh/id_rsa.pub | balena key add Main
|
||||||
|
# Windows 10 (cmd.exe prompt) example
|
||||||
|
$ balena key add Main %userprofile%.sshid_rsa.pub
|
||||||
|
|
||||||
### Arguments
|
### Arguments
|
||||||
|
|
||||||
|
|||||||
@ -34,15 +34,30 @@ export default class KeyAddCmd extends Command {
|
|||||||
public static description = stripIndent`
|
public static description = stripIndent`
|
||||||
Add an SSH key to balenaCloud.
|
Add an SSH key to balenaCloud.
|
||||||
|
|
||||||
Register an SSH in balenaCloud for the logged in user.
|
Add an SSH key to the balenaCloud account of the logged in user.
|
||||||
|
|
||||||
If \`path\` is omitted, the command will attempt
|
If \`path\` is omitted, the command will attempt to read the SSH key from stdin.
|
||||||
to read the SSH key from stdin.
|
|
||||||
|
About SSH keys
|
||||||
|
An "SSH key" actually consists of a public/private key pair. A typical name
|
||||||
|
for the private key file is "id_rsa", and a typical name for the public key
|
||||||
|
file is "id_rsa.pub". Both key files are saved to your computer (with the
|
||||||
|
private key optionally protected by a password), but only the public key is
|
||||||
|
saved to your balena account. This means that if you change computers or
|
||||||
|
otherwise lose the private key, you cannot recover the private key through
|
||||||
|
your balena account. You can however add new keys, and delete the old ones.
|
||||||
|
|
||||||
|
To generate a new SSH key pair, a nice guide can be found in GitHub's docs:
|
||||||
|
https://help.github.com/en/articles/generating-a-new-ssh-key-and-adding-it-to-the-ssh-agent
|
||||||
|
Skip the step about adding the key to a GitHub account, and instead add it to
|
||||||
|
your balena account.
|
||||||
`;
|
`;
|
||||||
|
|
||||||
public static examples = [
|
public static examples = [
|
||||||
'$ balena key add Main ~/.ssh/id_rsa.pub',
|
'$ balena key add Main ~/.ssh/id_rsa.pub',
|
||||||
'$ cat ~/.ssh/id_rsa.pub | balena key add Main',
|
'$ cat ~/.ssh/id_rsa.pub | balena key add Main',
|
||||||
|
'# Windows 10 (cmd.exe prompt) example',
|
||||||
|
'$ balena key add Main %userprofile%.sshid_rsa.pub',
|
||||||
];
|
];
|
||||||
|
|
||||||
public static args = [
|
public static args = [
|
||||||
|
|||||||
Loading…
Reference in New Issue
Block a user