Merge pull request #1119 from balena-io/registry-secrets-help-msg-build-deploy

Add registry-secrets help documentation for the build and deploy commands

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,
+This command can be used to start an image build on the remote balenaCloud build
-or a local mode balena device.
+servers, or on a local-mode balena device.
 
-When building on the balena cloud the given source directory will be sent to the
+When building on the balenaCloud servers, the given source directory will be
-balena builder, and the build will proceed. This can be used as a drop-in
+sent to the remote server. This can be used as a drop-in replacement for the
-replacement for git push to deploy.
+"git push" deployment method.
 
-When building on a local mode device, the given source directory will be built
+When building on a local-mode device, the given source directory will be
-on the device, and the resulting containers will be run on the device. Logs will
+built on the device, and the resulting containers will be run on the device.
-be streamed back from the device as part of the same invocation.
+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/':
+	'my-registry-server.com:25000':
-		username: mike
-		password: cze14
-	'myregistry.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 <appOwnerUsername>/<appName>`.
 
-Note: If building with this command, all options supported by `balena build`
+When --build is used, all options supported by `balena build` are also
-are also supported with this command.
+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:
 

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'

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 <appName> [image]'
 	description: 'Deploy a single image or a multicontainer project to a balena application'
-	help: '''
+	help: """
 		Usage: `deploy <appName> ([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 <appOwnerUsername>/<appName>`.
 
-		Note: If building with this command, all options supported by `balena build`
+		When --build is used, all options supported by `balena build` are also
-		are also supported with this command.
+		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 [

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,
+		This command can be used to start an image build on the remote balenaCloud build
-		or a local mode balena device.
+		servers, or on a local-mode balena device.
 
-		When building on the balena cloud the given source directory will be sent to the
+		When building on the balenaCloud servers, the given source directory will be
-		balena builder, and the build will proceed. This can be used as a drop-in
+		sent to the remote server. This can be used as a drop-in replacement for the
-		replacement for git push to deploy.
+		"git push" deployment method.
 
-		When building on a local mode device, the given source directory will be built
+		When building on a local-mode device, the given source directory will be
-		on the device, and the resulting containers will be run on the device. Logs will
+		built on the device, and the resulting containers will be run on the device.
-		be streamed back from the device as part of the same invocation.
+		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:
-		The --registry-secrets option specifies a JSON or YAML file containing private
+		https://www.balena.io/docs/learn/develop/local-mode/
-		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
 
+		${registrySecretsHelp.split('\n').join('\n\t\t')}
 
 		Examples:
 

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}'`;