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 &#60;image&#62;
 
+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: