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
478b5dd363
balena-cli/INSTALL-ADVANCED.md
Paulo Castro 478b5dd363 Revert styling of "balena CLI" as "balenaCLI" 
Change-type: patch
2020-10-21 00:07:46 +01:00

8.4 KiB
Raw Blame History

balena CLI Advanced Installation Options

These are alternative, advanced installation options. Most users would prefer the recommended, streamlined installation instructions.

There are 3 options to choose from to install balena's CLI:

  • Executable Installer: the easiest method on Windows and macOS, using the traditional graphical desktop application installers.
  • Standalone Zip Package: these are plain zip files with the balena CLI 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: 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 Dependencies.

Executable Installer

This is the recommended installation option on macOS and Windows. Follow the specific OS instructions:

Note regarding WSL (Windows Subsystem for Linux)
If you would like to use WSL, follow the installations instructions for Linux 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 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/
/usr/local/bin/balena

Standalone Zip Package

  1. Download the latest zip file from the releases page. 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 | macOS | Windows

  • If you are using macOS Catalina (10.15), check this known issue and workaround.
  • 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 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 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 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 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 shows the CLI installation steps on an Ubuntu 18.04 base image.
  • Python 2.7, git, make, g++
    • 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:

With these dependencies in place, the balena CLI installation command is:

$ 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.

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:

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). 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.