diff --git a/doc/cli.markdown b/doc/cli.markdown index cf085fca..a25ea22c 100644 --- a/doc/cli.markdown +++ b/doc/cli.markdown @@ -1377,28 +1377,32 @@ Docker host TLS key file ## push <applicationOrDevice> -This command can be used to start a build on the remote balena cloud builders, -or a local mode balena device. +This command can be used to start an image build on the remote balenaCloud build +servers, or on a local-mode balena device. -When building on the balena cloud the given source directory will be sent to the -balena builder, and the build will proceed. This can be used as a drop-in -replacement for git push to deploy. +When building on the balenaCloud servers, the given source directory will be +sent to the remote server. This can be used as a drop-in replacement for the +"git push" deployment method. -When building on a local mode device, the given source directory will be built -on the device, and the resulting containers will be run on the device. Logs will -be streamed back from the device as part of the same invocation. +When building on a local-mode device, the given source directory will be +built on the device, and the resulting containers will be run on the device. +Logs will be streamed back from the device as part of the same invocation. +The web dashboard can be used to switch a device to local mode: +https://www.balena.io/docs/learn/develop/local-mode/ The --registry-secrets option specifies a JSON or YAML file containing private Docker registry usernames and passwords to be used when pulling base images. Sample registry-secrets YAML file: - 'https://idx.docker.io/v1/': - username: mike - password: cze14 - 'myregistry.com:25000': + 'my-registry-server.com:25000': username: ann password: hunter2 - + '': # Use the empty string to refer to the Docker Hub + username: mike + password: cze14 + 'eu.gcr.io': # Google Container Registry + username: '_json_key' + password: '{escaped contents of the GCR keyfile.json file}' Examples: @@ -1693,7 +1697,7 @@ name of container to stop Use this command to build an image or a complete multicontainer project with the provided docker daemon in your development machine or balena device. (See also the `balena push` command for the option of building -images in balena's cloud builders.) +images in the balenaCloud build servers.) You must provide either an application or a device-type/architecture pair to use the balena Dockerfile pre-processor @@ -1705,6 +1709,20 @@ command will build each service defined in the compose file. If a compose file isn't found, the command will look for a Dockerfile, and if yet that isn't found, it will try to generate one. +The --registry-secrets option specifies a JSON or YAML file containing private +Docker registry usernames and passwords to be used when pulling base images. +Sample registry-secrets YAML file: + + 'my-registry-server.com:25000': + username: ann + password: hunter2 + '': # Use the empty string to refer to the Docker Hub + username: mike + password: cze14 + 'eu.gcr.io': # Google Container Registry + username: '_json_key' + password: '{escaped contents of the GCR keyfile.json file}' + Examples: $ balena build @@ -1792,7 +1810,7 @@ Use this command to deploy an image or a complete multicontainer project to an application, optionally building it first. The source images are searched for (and optionally built) using the docker daemon in your development machine or balena device. (See also the `balena push` command for the option of building -the image in balena's cloud builders.) +the image in the balenaCloud build servers.) Unless an image is specified, this command will look into the current directory (or the one specified by --source) for a compose file. If one is found, this @@ -1804,8 +1822,22 @@ generate one. To deploy to an app on which you're a collaborator, use `balena deploy /`. -Note: If building with this command, all options supported by `balena build` -are also supported with this command. +When --build is used, all options supported by `balena build` are also +supported by this command. + +The --registry-secrets option specifies a JSON or YAML file containing private +Docker registry usernames and passwords to be used when pulling base images. +Sample registry-secrets YAML file: + + 'my-registry-server.com:25000': + username: ann + password: hunter2 + '': # Use the empty string to refer to the Docker Hub + username: mike + password: cze14 + 'eu.gcr.io': # Google Container Registry + username: '_json_key' + password: '{escaped contents of the GCR keyfile.json file}' Examples: diff --git a/lib/actions/build.coffee b/lib/actions/build.coffee index 08c6a080..6152a397 100644 --- a/lib/actions/build.coffee +++ b/lib/actions/build.coffee @@ -3,6 +3,7 @@ Promise = require('bluebird') dockerUtils = require('../utils/docker') compose = require('../utils/compose') +{ registrySecretsHelp } = require('../utils/messages') ### Opts must be an object with the following keys: @@ -48,11 +49,11 @@ module.exports = signature: 'build [source]' description: 'Build a single image or a multicontainer project locally' primary: true - help: ''' + help: """ Use this command to build an image or a complete multicontainer project with the provided docker daemon in your development machine or balena device. (See also the `balena push` command for the option of building - images in balena's cloud builders.) + images in the balenaCloud build servers.) You must provide either an application or a device-type/architecture pair to use the balena Dockerfile pre-processor @@ -64,6 +65,8 @@ module.exports = isn't found, the command will look for a Dockerfile, and if yet that isn't found, it will try to generate one. + #{registrySecretsHelp} + Examples: $ balena build @@ -72,7 +75,7 @@ module.exports = $ balena build --application MyApp ./source/ $ balena build --docker '/var/run/docker.sock' $ balena build --dockerHost my.docker.host --dockerPort 2376 --ca ca.pem --key key.pem --cert cert.pem - ''' + """ options: dockerUtils.appendOptions compose.appendOptions [ { signature: 'arch' diff --git a/lib/actions/deploy.coffee b/lib/actions/deploy.coffee index ccdae53b..5a059c0e 100644 --- a/lib/actions/deploy.coffee +++ b/lib/actions/deploy.coffee @@ -3,6 +3,7 @@ Promise = require('bluebird') dockerUtils = require('../utils/docker') compose = require('../utils/compose') +{ registrySecretsHelp } = require('../utils/messages') ### Opts must be an object with the following keys: @@ -121,14 +122,14 @@ deployProject = (docker, logger, composeOpts, opts) -> module.exports = signature: 'deploy [image]' description: 'Deploy a single image or a multicontainer project to a balena application' - help: ''' + help: """ Usage: `deploy ([image] | --build [--source build-dir])` Use this command to deploy an image or a complete multicontainer project to an application, optionally building it first. The source images are searched for (and optionally built) using the docker daemon in your development machine or balena device. (See also the `balena push` command for the option of building - the image in balena's cloud builders.) + the image in the balenaCloud build servers.) Unless an image is specified, this command will look into the current directory (or the one specified by --source) for a compose file. If one is found, this @@ -140,15 +141,17 @@ module.exports = To deploy to an app on which you're a collaborator, use `balena deploy /`. - Note: If building with this command, all options supported by `balena build` - are also supported with this command. + When --build is used, all options supported by `balena build` are also + supported by this command. + + #{registrySecretsHelp} Examples: $ balena deploy myApp $ balena deploy myApp --build --source myBuildDir/ $ balena deploy myApp myApp/myImage - ''' + """ permission: 'user' primary: true options: dockerUtils.appendOptions compose.appendOptions [ diff --git a/lib/actions/push.ts b/lib/actions/push.ts index e5726018..9fe7160b 100644 --- a/lib/actions/push.ts +++ b/lib/actions/push.ts @@ -18,6 +18,8 @@ import { CommandDefinition } from 'capitano'; import { stripIndent } from 'common-tags'; import { BalenaSDK } from 'balena-sdk'; +import { registrySecretsHelp } from '../utils/messages'; + // An regex to detect an IP address, from https://www.regular-expressions.info/ip.html const IP_REGEX = new RegExp( /\b(?:(?:25[0-5]|2[0-4][0-9]|[01]?[0-9][0-9]?)\.){3}(?:25[0-5]|2[0-4][0-9]|[01]?[0-9][0-9]?)\b/, @@ -111,28 +113,20 @@ export const push: CommandDefinition< description: 'Start a remote build on the balena cloud build servers or a local mode device', help: stripIndent` - This command can be used to start a build on the remote balena cloud builders, - or a local mode balena device. + This command can be used to start an image build on the remote balenaCloud build + servers, or on a local-mode balena device. - When building on the balena cloud the given source directory will be sent to the - balena builder, and the build will proceed. This can be used as a drop-in - replacement for git push to deploy. + When building on the balenaCloud servers, the given source directory will be + sent to the remote server. This can be used as a drop-in replacement for the + "git push" deployment method. - When building on a local mode device, the given source directory will be built - on the device, and the resulting containers will be run on the device. Logs will - be streamed back from the device as part of the same invocation. - - The --registry-secrets option specifies a JSON or YAML file containing private - Docker registry usernames and passwords to be used when pulling base images. - Sample registry-secrets YAML file: - - 'https://idx.docker.io/v1/': - username: mike - password: cze14 - 'myregistry.com:25000': - username: ann - password: hunter2 + When building on a local-mode device, the given source directory will be + built on the device, and the resulting containers will be run on the device. + Logs will be streamed back from the device as part of the same invocation. + The web dashboard can be used to switch a device to local mode: + https://www.balena.io/docs/learn/develop/local-mode/ + ${registrySecretsHelp.split('\n').join('\n\t\t')} Examples: diff --git a/lib/utils/messages.ts b/lib/utils/messages.ts index 3a3e3d1a..72473b57 100644 --- a/lib/utils/messages.ts +++ b/lib/utils/messages.ts @@ -19,3 +19,18 @@ export const balenaAsciiArt = `\ | |_) | (_) || || ___/| | | || (_) | |_.__/ \\__,_||_| \\____/|_| |_| \\__,_| `; + +export const registrySecretsHelp = `\ +The --registry-secrets option specifies a JSON or YAML file containing private +Docker registry usernames and passwords to be used when pulling base images. +Sample registry-secrets YAML file: + + 'my-registry-server.com:25000': + username: ann + password: hunter2 + '': # Use the empty string to refer to the Docker Hub + username: mike + password: cze14 + 'eu.gcr.io': # Google Container Registry + username: '_json_key' + password: '{escaped contents of the GCR keyfile.json file}'`;