From 636ecaf4e09cd287f5c4f54b16d846929ef39159 Mon Sep 17 00:00:00 2001 From: Paulo Castro <paulo@balena.io> Date: Fri, 8 Nov 2019 14:32:21 +0000 Subject: [PATCH] Improve help and docs (CLI install dependencies) for the preload command Change-type: patch Signed-off-by: Paulo Castro <paulo@balena.io> --- INSTALL.md | 26 ++++++++++++++++++++++++-- doc/cli.markdown | 11 +++++++---- lib/actions/preload.coffee | 11 +++++++---- 3 files changed, 38 insertions(+), 10 deletions(-) diff --git a/INSTALL.md b/INSTALL.md index 9f12c3ae..723314ef 100644 --- a/INSTALL.md +++ b/INSTALL.md @@ -21,8 +21,7 @@ Dependencies](#additional-dependencies). > 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. +> WSL. ## Executable Installer @@ -142,6 +141,29 @@ 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 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). + ## Configuring SSH keys The `balena ssh` command requires an SSH key to be added to your balena account. If you had diff --git a/doc/cli.markdown b/doc/cli.markdown index 150d58e6..10590ce2 100644 --- a/doc/cli.markdown +++ b/doc/cli.markdown @@ -1372,12 +1372,15 @@ how frequently (in minutes) to poll for application updates ## preload <image> +Preload a balena application release (app images/containers), and optionally +a balenaOS splash screen, in a previously downloaded balenaOS image file (or +Edison zip archive) in the local disk. The balenaOS image file can then be +flashed to a device's SD card. When the device boots, it will not need to +download the application, as it was preloaded. + Warning: "balena preload" requires Docker to be correctly installed in your shell environment. For more information (including Windows support) -please check the README here: https://github.com/balena-io/balena-cli . - -Use this command to preload an application to a local disk image (or -Edison zip archive) with a built release from balena. +check: https://github.com/balena-io/balena-cli/blob/master/INSTALL.md Examples: diff --git a/lib/actions/preload.coffee b/lib/actions/preload.coffee index f6c52cb6..8b3ea4b2 100644 --- a/lib/actions/preload.coffee +++ b/lib/actions/preload.coffee @@ -185,12 +185,15 @@ module.exports = signature: 'preload <image>' description: 'preload an app on a disk image (or Edison zip archive)' help: ''' + Preload a balena application release (app images/containers), and optionally + a balenaOS splash screen, in a previously downloaded balenaOS image file (or + Edison zip archive) in the local disk. The balenaOS image file can then be + flashed to a device's SD card. When the device boots, it will not need to + download the application, as it was preloaded. + Warning: "balena preload" requires Docker to be correctly installed in your shell environment. For more information (including Windows support) - please check the README here: https://github.com/balena-io/balena-cli . - - Use this command to preload an application to a local disk image (or - Edison zip archive) with a built release from balena. + check: https://github.com/balena-io/balena-cli/blob/master/INSTALL.md Examples: