ExternalVendorCode/balena-cli
1
0
Fork 0
mirror of https://github.com/balena-io/balena-cli.git synced 2025-05-02 00:53:06 +00:00
Code Issues Actions Packages Projects Releases Wiki Activity

docs: Further clarify Docker requirements for preload

Browse Source 
Change-type: patch
This commit is contained in:
Paulo Castro 2021-04-04 22:47:27 +01:00
parent b66706e8ee
commit f53e658ca2
6 changed files with 51 additions and 34 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

11
INSTALL-ADVANCED.md
View File

@ -124,7 +124,7 @@ regular (non-root) user account, especially if using a user-managed node install
## Additional Dependencies ## Additional Dependencies
The `balena ssh`, `scan`, `build`, `deploy`, `preload` and `os configure` commands may require The `balena ssh`, `scan`, `build`, `deploy` and `preload` commands may require
additional software to be installed. Check the Additional Dependencies sections for each operating additional software to be installed. Check the Additional Dependencies sections for each operating
system: system:
@ -132,8 +132,8 @@ system:
* [macOS](./INSTALL-MAC.md#additional-dependencies) * [macOS](./INSTALL-MAC.md#additional-dependencies)
* [Linux](./INSTALL-LINUX.md#additional-dependencies) * [Linux](./INSTALL-LINUX.md#additional-dependencies)
The `build` and `deploy` commands are also capable of using Docker or balenaEngine on a remote Where Docker or balenaEngine are required, they may be installed on the local machine (where the
server, or on a balenaOS device running a [balenaOS development balena CLI is executed), on a remote server, or on a balenaOS device running a [balenaOS development
image](https://www.balena.io/docs/reference/OS/overview/2.x/#dev-vs-prod-images)). Reasons why this image](https://www.balena.io/docs/reference/OS/overview/2.x/#dev-vs-prod-images)). Reasons why this
may be desirable include: may be desirable include:
@ -142,6 +142,7 @@ may be desirable include:
* To build or run images "natively" on an ARM device, avoiding the need for QEMU emulation. * 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 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, port number with the `--dockerHost` and `--dockerPort` command-line options. The `preload` command
check `balena help build` or the [online has additional requirements because the bind mount feature is used. For more details, see
`balena help` for each command or the [online
reference](https://www.balena.io/docs/reference/cli/#cli-command-reference). reference](https://www.balena.io/docs/reference/cli/#cli-command-reference).

8
INSTALL-LINUX.md
View File

@ -53,11 +53,11 @@ steps](https://docs.docker.com/engine/install/linux-postinstall/) on how to achi
### build, deploy ### build, deploy
These commands require [Docker](https://docs.docker.com/install/overview/) or These commands require [Docker](https://docs.docker.com/install/overview/) or
[balenaEngine](https://www.balena.io/engine/) to be available (on a local or remote [balenaEngine](https://www.balena.io/engine/) to be available on a local or remote
machine). Most users will follow [Docker's installation machine. Most users will follow [Docker's installation
instructions](https://docs.docker.com/install/overview/) to install Docker on the same instructions](https://docs.docker.com/install/overview/) to install Docker on the same
workstation (laptop) as the balena CLI. The [advanced installation workstation as the balena CLI. The [advanced installation
options](./INSTALL-ADVANCED.md) document describes other possibilities. options](./INSTALL-ADVANCED.md#additional-dependencies) document describes other possibilities.
### balena ssh ### balena ssh

15
INSTALL-MAC.md
View File

@ -37,11 +37,11 @@ sudo /usr/local/lib/balena-cli/bin/uninstall
### build and deploy ### build and deploy
These commands require [Docker](https://docs.docker.com/install/overview/) or These commands require [Docker](https://docs.docker.com/install/overview/) or
[balenaEngine](https://www.balena.io/engine/) to be available (on a local or remote [balenaEngine](https://www.balena.io/engine/) to be available on a local or remote
machine). Most users will follow [Docker's installation machine. Most users will follow [Docker's installation
instructions](https://docs.docker.com/install/overview/) to install Docker on the same instructions](https://docs.docker.com/install/overview/) to install Docker on the same
workstation (laptop) as the balena CLI. The [advanced installation workstation as the balena CLI. The [advanced installation
options](./INSTALL-ADVANCED.md) document describes other possibilities. options](./INSTALL-ADVANCED.md#additional-dependencies) document describes other possibilities.
### balena ssh ### balena ssh
@ -60,12 +60,11 @@ command set can also be used to list and manage SSH keys: see `balena help -v`.
### balena preload ### balena preload
Like the `build` and `deploy` commands, the `preload` command requires Docker, with the additional Like the `build` and `deploy` commands, the `preload` command requires Docker.
restriction that Docker must be installed on the local machine (because Docker's bind mounting Preloading balenaOS images for some older device types (like the Raspberry
feature is used). Also, preloading balenaOS images for some older device types (like the Raspberry
Pi 3, but not the Raspberry 4) requires Docker to support the [AUFS storage Pi 3, but not the Raspberry 4) requires Docker to support the [AUFS storage
driver](https://docs.docker.com/storage/storagedriver/aufs-driver/). Unfortunately, Docker Desktop driver](https://docs.docker.com/storage/storagedriver/aufs-driver/). Unfortunately, Docker Desktop
for Windows or macOS dropped support for the AUFS filesystem in Docker CE versions greater than for Windows and macOS dropped support for the AUFS filesystem in Docker CE versions greater than
18.06.1. The present workarounds are to either: 18.06.1. The present workarounds are to either:
* Install the balena CLI on Linux (e.g. Ubuntu) with a virtual machine like VirtualBox. * Install the balena CLI on Linux (e.g. Ubuntu) with a virtual machine like VirtualBox.

17
INSTALL-WINDOWS.md
View File

@ -22,7 +22,7 @@ Selected operating system: **Windows**
* `balena help` - should print a list of available commands * `balena help` - should print a list of available commands
No further steps are required to run most CLI commands. The `balena ssh`, `scan`, `build`, No further steps are required to run most CLI commands. The `balena ssh`, `scan`, `build`,
`deploy`, `preload` and `os configure` commands may require additional software to be installed, as `deploy` and `preload` commands may require additional software to be installed, as
described below. described below.
## Additional Dependencies ## Additional Dependencies
@ -30,11 +30,11 @@ described below.
### build and deploy ### build and deploy
These commands require [Docker](https://docs.docker.com/install/overview/) or These commands require [Docker](https://docs.docker.com/install/overview/) or
[balenaEngine](https://www.balena.io/engine/) to be available (on a local or remote [balenaEngine](https://www.balena.io/engine/) to be available on a local or remote
machine). Most users will follow [Docker's installation machine. Most users will follow [Docker's installation
instructions](https://docs.docker.com/install/overview/) to install Docker on the same instructions](https://docs.docker.com/install/overview/) to install Docker on the same
workstation (laptop) as the balena CLI. The [advanced installation workstation as the balena CLI. The [advanced installation
options](./INSTALL-ADVANCED.md) document describes other possibilities. options](./INSTALL-ADVANCED.md#additional-dependencies) document describes other possibilities.
### balena ssh ### balena ssh
@ -59,12 +59,11 @@ Otherwise, Bonjour for Windows can be downloaded and installed from: https://sup
### balena preload ### balena preload
Like the `build` and `deploy` commands, the `preload` command requires Docker, with the additional Like the `build` and `deploy` commands, the `preload` command requires Docker.
restriction that Docker must be installed on the local machine (because Docker's bind mounting Preloading balenaOS images for some older device types (like the Raspberry
feature is used). Also, preloading balenaOS images for some older device types (like the Raspberry
Pi 3, but not the Raspberry 4) requires Docker to support the [AUFS storage Pi 3, but not the Raspberry 4) requires Docker to support the [AUFS storage
driver](https://docs.docker.com/storage/storagedriver/aufs-driver/). Unfortunately, Docker Desktop driver](https://docs.docker.com/storage/storagedriver/aufs-driver/). Unfortunately, Docker Desktop
for Windows or macOS dropped support for the AUFS filesystem in Docker CE versions greater than for Windows and macOS dropped support for the AUFS filesystem in Docker CE versions greater than
18.06.1. The present workarounds are to either: 18.06.1. The present workarounds are to either:
* Install the balena CLI on Linux (e.g. Ubuntu) with a virtual machine like VirtualBox. * Install the balena CLI on Linux (e.g. Ubuntu) with a virtual machine like VirtualBox.

17
doc/cli.markdown
View File

@ -2416,7 +2416,12 @@ a balenaOS splash screen, in a previously downloaded '.img' balenaOS image file
in the local disk (a zip file is only accepted for the Intel Edison device type). in the local disk (a zip file is only accepted for the Intel Edison device type).
After preloading, the balenaOS image file can be flashed to a device's SD card. After preloading, the balenaOS image file can be flashed to a device's SD card.
When the device boots, it will not need to download the application, as it was When the device boots, it will not need to download the application, as it was
preloaded. preloaded. This is usually combined with release pinning
(https://www.balena.io/docs/learn/deploy/release-strategy/release-policy/)
to avoid the device dowloading a newer release straight away, if one is available.
Check also the Preloading and Preregistering section of the balena CLI's advanced
masterclass document:
https://www.balena.io/docs/learn/more/masterclasses/advanced-cli/#5-preloading-and-preregistering
Applications may be specified by app name, slug, or numeric ID. App slugs Applications may be specified by app name, slug, or numeric ID. App slugs
are the recommended option, as they are unique and unambiguous. Slugs are the recommended option, as they are unique and unambiguous. Slugs
@ -2431,9 +2436,13 @@ Numeric app IDs are deprecated because they consist of an implementation detail
of the balena backend. We intend to remove support for numeric IDs at some point of the balena backend. We intend to remove support for numeric IDs at some point
in the future. in the future.
Warning: "balena preload" requires Docker to be correctly installed in Note that the this command requires Docker to be installed, as further detailed
your shell environment. For more information (including Windows support) in the balena CLI's installation instructions:
check: https://github.com/balena-io/balena-cli/blob/master/INSTALL.md https://github.com/balena-io/balena-cli/blob/master/INSTALL.md
The `--dockerHost` and `--dockerPort` flags allow a remote Docker engine to
be used, however the image file must be accessible to the remote Docker engine
on the same path given on the command line. This is because Docker's bind mount
feature is used to "share" the image with a container that performs the preload.
Examples: Examples:

17
lib/commands/preload.ts
View File

@ -63,13 +63,22 @@ export default class PreloadCmd extends Command {
in the local disk (a zip file is only accepted for the Intel Edison device type). in the local disk (a zip file is only accepted for the Intel Edison device type).
After preloading, the balenaOS image file can be flashed to a device's SD card. After preloading, the balenaOS image file can be flashed to a device's SD card.
When the device boots, it will not need to download the application, as it was When the device boots, it will not need to download the application, as it was
preloaded. preloaded. This is usually combined with release pinning
(https://www.balena.io/docs/learn/deploy/release-strategy/release-policy/)
to avoid the device dowloading a newer release straight away, if one is available.
Check also the Preloading and Preregistering section of the balena CLI's advanced
masterclass document:
https://www.balena.io/docs/learn/more/masterclasses/advanced-cli/#5-preloading-and-preregistering
${applicationIdInfo.split('\n').join('\n\t\t')} ${applicationIdInfo.split('\n').join('\n\t\t')}
Warning: "balena preload" requires Docker to be correctly installed in Note that the this command requires Docker to be installed, as further detailed
your shell environment. For more information (including Windows support) in the balena CLI's installation instructions:
check: https://github.com/balena-io/balena-cli/blob/master/INSTALL.md https://github.com/balena-io/balena-cli/blob/master/INSTALL.md
The \`--dockerHost\` and \`--dockerPort\` flags allow a remote Docker engine to
be used, however the image file must be accessible to the remote Docker engine
on the same path given on the command line. This is because Docker's bind mount
feature is used to "share" the image with a container that performs the preload.
`; `;
public static examples = [ public static examples = [