Simplify CLI installation and first usage

[pdcastro]

User experience / product feedback (gsheet, flowdock) is that the CLI installation (and first usage) is "pretty complicated". Some specific action points have been identified:

• Have a proper installer for Linux: apt install balena-cli

  • 1436 Produce Ubuntu/Debian packages (deb installer) on releases (oclif publish:deb)

    This issue has been bumped up in the ordered backlog.
     

• Especially for the getting started / first-time users workflow, avoid requiring users to read a long installation document, open a releases page and choose the right version and file to download:

  • One "vision" is for the getting started guide (and CLI docs) to have a link like "Click here to download and install the CLI" (exact wording to be decided) and that link points directly to the .exe / .pkg file (Windows / Mac respectively), which the user downloads and executes. No need to read install docs and make early installation choices.

  • For Linux, once we have the installer, the download link might be replaced with: "run sudo apt-get install balena-cli to install the CLI" (exact wording to be decided).

  • On the other hand, users might benefit from the awareness of additional installation options. For example, previous mixpanel data analysis suggest that many dashboard Windows users use the CLI on Linux (including the Windows Subsystem for Linux app installed via Microsoft App Store), in which case the assumption that the CLI for Windows is the correct the download option may not be correct. In addition, the standalone zip installation option may be the best choice for text-only (no GUI) remote usage, especially in Continuous Integration environments (including Windows Servers on Azure), though clearly this is not applicable to getting started / first-time users.

  • Perhaps a reasonable compromise would be for the getting started guide (and CLI docs) to have a couple of links, something like:
     
    Click here to download and install the CLI for Windows
    Note: Additional platforms and installation options are available, including the ability to choose specific CLI versions to install -- read more about the installation options.
     
    Such that, hopefully, first-time users just click the first link, but at a later time (once they are more invested in the platform) they could choose to click the second link.

  • Subtask: #1716 Generate download link to latest CLI release ("balena update")
    (The docs / getting started guide should dynamically generate the download link to the latest available CLI release, for the required platform.)

• The installer should present an information screen at the end of the installation process, indicating what to do next: open a command shell (which one?) and run balena version or something. (And also, discretely add that second link for additional installation options.)

  • 1717 Executable GUI installer should print "next steps" info at the end (Windows, macOS)

     

• Additional Dependencies
  We want to avoid requiring the user to manually install additional dependencies, by bundling them and automatically installing them (subject to user consent). (Documenting the external dependencies is better than nothing, but doesn't meet the frictionless standard.) Where the CLI cannot automatically install the dependencies, or as an intermediate step, the CLI should guide / provide information to the user on how to install the dependencies, at 2 stages: during CLI installation, and during command usage. (Consider also that some users may only attempt running commands that require the extra dependencies a long time after the initial installation, so they would not remember any advice provided at installation time.)

  • balena scan

  • 1714 Improve balena scan error message re insufficient privileges and "sudo"

  • 1715 balena scan [Windows]: solve Bonjour situation

  • 1718 balena scan [Linux]: detect that dependencies are installed (avahi)

  • 1713 balena scan should not filter out production devices

  • 1578 Flag devices which do not have local-mode enabled in balena scan results.

     

  • balena ssh

  • 1720 Remove dependency on external ssh tool

     

  • balena build, balena deploy

  • 1719 Detect and facilitate Docker installation

     

• Web authorization

  • 1710 Reword web authorization

  • 1404 Login command may hang for a while after authorizing through the web dashboard

     

• Performance

  • 1721 Explain / solve why the CLI takes a long time to run after installation

  • Installer speed: #1709 Speed up CLI installation on Windows
  • The CLI is slow to run generally:

  • 1404 Login command may hang for a while after authorizing through the web dashboard

  • 1436 balena version responds immediately but hangs around for a long time

  • 1708 Speed up balena help by creating/saving usage information at compile time

All subtasks identified in this issue have also been added to a GitHub project: https://github.com/balena-io/balena-cli/projects/3

[frederikheld]

I just found some more issues with balena-cli. Might be related to the installation process (and could be fixed with a proper installer).

a) if I do $ balena login but then $ sudo balena preload, balena-cli tells me that I'm not logged in. So I have to do $ sudo balena login separately. But this does not open the website automatically, I have to click on the link manually.

I don't remember having this issue on my old computer. So it might be related to the fact that I installed balena-cli first and then docker, which brings me to the next issue:

b) balena-cli does not tell me that I need to install docker first. Of course, there's no installer. But the installation instructions don't tell me either and balena doesn't mention missing docker engine until it fails because of the missing docker engine.

Should I submit separate issues for that?

[pdcastro]

Thank you for the feedback @frederikheld 👍

if I do $ balena login but then $ sudo balena preload, balena-cli tells me that I'm not logged in.

As far as I am aware, the balena preload command does not require sudo if Docker is configured to run without sudo. In PR #2208, which was inspired by your contributions in #2149 and #2206 🙏, I am adding a note on how to configure Docker to run without sudo.

If there is a CLI command that requires login and also requires sudo, we will need to amend documentation further. A workaround is to the use the sudo -E flag. For example, I believe that sudo -E balena preload would not require you to log in again if you are already logged as a regular user.

The explanation is that the CLI creates a ~/.balena/token file in the homedir, e.g. /home/paulo/.balena/token. But when we use sudo, in some Linux distros, sudo switches the homedir to /root and the CLI will then look at /root/.balena/token. The sudo -E flag causes sudo not to switch the homedir by preserving the environment variables, including $HOME.

For the record, :-) we are amending documentation as an easy, short-term workaround to what are really design / implementation issues. Code changes to implement dynamic privilege escalation, dynamic environment detection, and improved CLI installers would avoid the need of a number of manual installation steps and respective documentation.

But the installation instructions don't tell me either and balena doesn't mention missing docker engine until it fails because of the missing docker engine.

The Linux installation instructions, Additional Dependencies section, mention that Docker is required for the balena build, deploy and preload commands. Other than that, I think that issue 1719 Detect and facilitate Docker installation would be best -- the CLI could install Docker for the user, or at least dynamically ask the user to install Docker, including validating the installation if something is missing, for example if Docker is configured to require the use of sudo.

Should I submit separate issues for that?

With regard to sudo and installers, the problem is not lack of issues, it's lack of developer hours to solve the known issues. :-) In addition to the issues already linked from this issue, other sudo-related issues include:

477, #385, #542, #550, #572, #940, #1444, #1714, #2062, #2101, #2149

They compete with ~300 other issues just in the balena-cli repo, plus lots of other issues in tens of other git repositories used by the balena-cli repo. The platform codebase is massive, but also almost completely open source, and community contribution is welcome. ;-)

[frederikheld]

Thanks for the clarification :-)

I would actually like to contribute more, but it's difficult to find time between my day job and side projects. And installers aren't my turf yet :-P But I just started to use balena, I might contribute more as soon as I understand it better :-)