Skip to content

Latest commit

 

History

History
169 lines (129 loc) · 8.38 KB

INSTALL-ADVANCED.md

File metadata and controls

169 lines (129 loc) · 8.38 KB
Raw

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/src/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 10.15 or later (Catalina, Big Sur), 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 development tools to be installed first, as follows.

The balena CLI currently requires Node.js version ^20.6.0 Versions 21 and later are not yet fully supported.

Install development tools

Linux or WSL (Windows Subsystem for Linux)

$ sudo apt-get update && sudo apt-get -y install curl python3 git make g++
$ curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.38.0/install.sh | bash
$ . ~/.bashrc
$ nvm install 20

The curl command line above uses nvm to install Node.js, instead of using apt-get. Installing Node.js through apt-get is a common source of problems from permission errors to conflict with other system packages, and therefore not recommended.

macOS

$ curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.38.0/install.sh | bash
$ . ~/.bashrc
$ nvm install 20

Windows (not WSL)

Install:

  • If you'd like the ability to switch between Node.js versions, install

Install the balena CLI

After installing the development tools, install the balena CLI with:

$ npm install balena-cli --global --production --unsafe-perm

--unsafe-perm is needed when npm install is executed as the root user (e.g. in a Docker container) in order to allow npm scripts like postinstall to be executed.

Additional Dependencies

The balena device ssh, device detect, build, deploy and preload commands may require additional software to be installed. Check the Additional Dependencies sections for each operating system:

Where Docker or balenaEngine are required, they may be installed on the local machine (where the balena CLI is executed), 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. The preload command has additional requirements because the bind mount feature is used. For more details, see balena help for each command or the online reference.