From 73f49765ec8ddeb58aefa6f0f22dcd1b7a7e671f Mon Sep 17 00:00:00 2001 From: Paulo Castro Date: Tue, 8 Sep 2020 15:30:41 +0100 Subject: [PATCH 1/2] push: Reformat help output to fit in 80 characters Connects-to: #1858 Change-type: patch --- doc/cli.markdown | 108 ++++++++++++++++++++------------------ lib/actions-oclif/push.ts | 64 +++++++++++----------- lib/utils/messages.ts | 21 ++++---- 3 files changed, 98 insertions(+), 95 deletions(-) diff --git a/doc/cli.markdown b/doc/cli.markdown index 03427967..9f61b9b3 100644 --- a/doc/cli.markdown +++ b/doc/cli.markdown @@ -2091,17 +2091,18 @@ this file will be used instead. DOCKERIGNORE AND GITIGNORE FILES By default, the balena CLI will use a single ".dockerignore" file (if any) at the project root (--source directory) in order to decide which source files to -exclude from the "build context" (tar stream) sent to balenaCloud, Docker daemon -or balenaEngine. In a microservices (multicontainer) application, the source -directory is the directory that contains the "docker-compose.yml" file. +exclude from the "build context" (tar stream) sent to balenaCloud, Docker +daemon or balenaEngine. In a microservices (multicontainer) application, the +source directory is the directory that contains the "docker-compose.yml" file. -The --multi-dockerignore (-m) option may be used with microservices (multicontainer) -applications that define a docker-compose.yml file. When this option is used, -each service subdirectory (defined by the `build` or `build.context` service -properties in the docker-compose.yml file) is filtered separately according to -a .dockerignore file defined in the service subdirectory. If no .dockerignore -file exists in a service subdirectory, then only the default .dockerignore -patterns (see below) apply for that service subdirectory. +The --multi-dockerignore (-m) option may be used with microservices +(multicontainer) applications that define a docker-compose.yml file. When +this option is used, each service subdirectory (defined by the `build` or +`build.context` service properties in the docker-compose.yml file) is +filtered separately according to a .dockerignore file defined in the service +subdirectory. If no .dockerignore file exists in a service subdirectory, then +only the default .dockerignore patterns (see below) apply for that service +subdirectory. When the --multi-dockerignore (-m) option is used, the .dockerignore file (if any) defined at the overall project root will be used to filter files and @@ -2139,8 +2140,8 @@ adding counter patterns to the applicable .dockerignore file(s), for example - https://docs.docker.com/engine/reference/builder/#dockerignore-file - https://www.npmjs.com/package/@balena/dockerignore -Note: --service and --env flags must come after the applicationOrDevice parameter, -as per examples. +Note: the --service and --env flags must come after the applicationOrDevice +parameter, as per examples. Examples: @@ -2167,7 +2168,8 @@ application name, or device address (for local pushes) #### -s, --source SOURCE -Source directory to be sent to balenaCloud or balenaOS device (default: current working dir) +Source directory to be sent to balenaCloud or balenaOS device +(default: current working dir) #### -f, --emulated @@ -2179,11 +2181,12 @@ Alternative Dockerfile name/path, relative to the source folder #### -c, --nocache -Don't use cached layers of previously built images for this project. This ensures -that the latest base image and packages are pulled. Note that build logs may still -display the message _"Pulling previous images for caching purposes" (as the cloud -builder needs previous images to compute delta updates), but the logs will not -display the "Using cache" lines for each build step of a Dockerfile. +Don't use cached layers of previously built images for this project. This +ensures that the latest base image and packages are pulled. Note that build +logs may still display the message _"Pulling previous images for caching +purposes" (as the cloud builder needs previous images to compute delta +updates), but the logs will not display the "Using cache" lines for each +build step of a Dockerfile. #### --noparent-check @@ -2191,23 +2194,24 @@ Disable project validation check of 'docker-compose.yml' file in parent folder #### -R, --registry-secrets REGISTRY-SECRETS -Path to a local YAML or JSON file containing Docker registry passwords used to pull base images. -Note that if registry-secrets are not provided on the command line, a secrets configuration -file from the balena directory will be used (usually $HOME/.balena/secrets.yml|.json) +Path to a local YAML or JSON file containing Docker registry passwords used +to pull base images. Note that if registry-secrets are not provided on the +command line, a secrets configuration file from the balena directory will be +used (usually $HOME/.balena/secrets.yml|.json) #### --nolive -Don't run a live session on this push. The filesystem will not be monitored, and changes -will not be synchronized to any running containers. Note that both this flag and --detached -and required to cause the process to end once the initial build has completed. +Don't run a live session on this push. The filesystem will not be monitored, +and changes will not be synchronized to any running containers. Note that both +this flag and --detached and required to cause the process to end once the +initial build has completed. #### -d, --detached -When pushing to the cloud, this option will cause the build to start, then return execution -back to the shell, with the status and release ID (if applicable). - -When pushing to a local mode device, this option will cause the command to not tail application logs when the build -has completed. +When pushing to the cloud, this option will cause the build to start, then +return execution back to the shell, with the status and release ID (if +applicable). When pushing to a local mode device, this option will cause +the command to not tail application logs when the build has completed. #### --service SERVICE @@ -2249,8 +2253,8 @@ No-op (default behavior) since balena CLI v12.0.0. See "balena help push". #### -g, --gitignore Consider .gitignore files in addition to the .dockerignore file. This reverts -to the CLI v11 behavior/implementation (deprecated) if compatibility is required -until your project can be adapted. +to the CLI v11 behavior/implementation (deprecated) if compatibility is +required until your project can be adapted. # Settings @@ -2358,17 +2362,18 @@ this file will be used instead. DOCKERIGNORE AND GITIGNORE FILES By default, the balena CLI will use a single ".dockerignore" file (if any) at the project root (--source directory) in order to decide which source files to -exclude from the "build context" (tar stream) sent to balenaCloud, Docker daemon -or balenaEngine. In a microservices (multicontainer) application, the source -directory is the directory that contains the "docker-compose.yml" file. +exclude from the "build context" (tar stream) sent to balenaCloud, Docker +daemon or balenaEngine. In a microservices (multicontainer) application, the +source directory is the directory that contains the "docker-compose.yml" file. -The --multi-dockerignore (-m) option may be used with microservices (multicontainer) -applications that define a docker-compose.yml file. When this option is used, -each service subdirectory (defined by the `build` or `build.context` service -properties in the docker-compose.yml file) is filtered separately according to -a .dockerignore file defined in the service subdirectory. If no .dockerignore -file exists in a service subdirectory, then only the default .dockerignore -patterns (see below) apply for that service subdirectory. +The --multi-dockerignore (-m) option may be used with microservices +(multicontainer) applications that define a docker-compose.yml file. When +this option is used, each service subdirectory (defined by the `build` or +`build.context` service properties in the docker-compose.yml file) is +filtered separately according to a .dockerignore file defined in the service +subdirectory. If no .dockerignore file exists in a service subdirectory, then +only the default .dockerignore patterns (see below) apply for that service +subdirectory. When the --multi-dockerignore (-m) option is used, the .dockerignore file (if any) defined at the overall project root will be used to filter files and @@ -2579,17 +2584,18 @@ this file will be used instead. DOCKERIGNORE AND GITIGNORE FILES By default, the balena CLI will use a single ".dockerignore" file (if any) at the project root (--source directory) in order to decide which source files to -exclude from the "build context" (tar stream) sent to balenaCloud, Docker daemon -or balenaEngine. In a microservices (multicontainer) application, the source -directory is the directory that contains the "docker-compose.yml" file. +exclude from the "build context" (tar stream) sent to balenaCloud, Docker +daemon or balenaEngine. In a microservices (multicontainer) application, the +source directory is the directory that contains the "docker-compose.yml" file. -The --multi-dockerignore (-m) option may be used with microservices (multicontainer) -applications that define a docker-compose.yml file. When this option is used, -each service subdirectory (defined by the `build` or `build.context` service -properties in the docker-compose.yml file) is filtered separately according to -a .dockerignore file defined in the service subdirectory. If no .dockerignore -file exists in a service subdirectory, then only the default .dockerignore -patterns (see below) apply for that service subdirectory. +The --multi-dockerignore (-m) option may be used with microservices +(multicontainer) applications that define a docker-compose.yml file. When +this option is used, each service subdirectory (defined by the `build` or +`build.context` service properties in the docker-compose.yml file) is +filtered separately according to a .dockerignore file defined in the service +subdirectory. If no .dockerignore file exists in a service subdirectory, then +only the default .dockerignore patterns (see below) apply for that service +subdirectory. When the --multi-dockerignore (-m) option is used, the .dockerignore file (if any) defined at the overall project root will be used to filter files and diff --git a/lib/actions-oclif/push.ts b/lib/actions-oclif/push.ts index f6236e7b..50e47051 100644 --- a/lib/actions-oclif/push.ts +++ b/lib/actions-oclif/push.ts @@ -84,8 +84,8 @@ export default class PushCmd extends Command { ${dockerignoreHelp.split('\n').join('\n\t\t')} - Note: --service and --env flags must come after the applicationOrDevice parameter, - as per examples. + Note: the --service and --env flags must come after the applicationOrDevice + parameter, as per examples. `; public static examples = [ @@ -115,8 +115,9 @@ export default class PushCmd extends Command { public static flags: flags.Input = { source: flags.string({ - description: - 'Source directory to be sent to balenaCloud or balenaOS device (default: current working dir)', + description: stripIndent` + Source directory to be sent to balenaCloud or balenaOS device + (default: current working dir)`, char: 's', }), emulated: flags.boolean({ @@ -129,38 +130,39 @@ export default class PushCmd extends Command { }), nocache: flags.boolean({ description: stripIndent` - Don't use cached layers of previously built images for this project. This ensures - that the latest base image and packages are pulled. Note that build logs may still - display the message _"Pulling previous images for caching purposes" (as the cloud - builder needs previous images to compute delta updates), but the logs will not - display the "Using cache" lines for each build step of a Dockerfile.`, - + Don't use cached layers of previously built images for this project. This + ensures that the latest base image and packages are pulled. Note that build + logs may still display the message _"Pulling previous images for caching + purposes" (as the cloud builder needs previous images to compute delta + updates), but the logs will not display the "Using cache" lines for each + build step of a Dockerfile.`, char: 'c', }), 'noparent-check': flags.boolean({ - description: `Disable project validation check of 'docker-compose.yml' file in parent folder`, + description: stripIndent` + Disable project validation check of 'docker-compose.yml' file in parent folder`, }), 'registry-secrets': flags.string({ description: stripIndent` - Path to a local YAML or JSON file containing Docker registry passwords used to pull base images. - Note that if registry-secrets are not provided on the command line, a secrets configuration - file from the balena directory will be used (usually $HOME/.balena/secrets.yml|.json)`, + Path to a local YAML or JSON file containing Docker registry passwords used + to pull base images. Note that if registry-secrets are not provided on the + command line, a secrets configuration file from the balena directory will be + used (usually $HOME/.balena/secrets.yml|.json)`, char: 'R', }), nolive: flags.boolean({ description: stripIndent` - Don't run a live session on this push. The filesystem will not be monitored, and changes - will not be synchronized to any running containers. Note that both this flag and --detached - and required to cause the process to end once the initial build has completed.`, + Don't run a live session on this push. The filesystem will not be monitored, + and changes will not be synchronized to any running containers. Note that both + this flag and --detached and required to cause the process to end once the + initial build has completed.`, }), detached: flags.boolean({ description: stripIndent` - When pushing to the cloud, this option will cause the build to start, then return execution - back to the shell, with the status and release ID (if applicable). - - When pushing to a local mode device, this option will cause the command to not tail application logs when the build - has completed.`, - + When pushing to the cloud, this option will cause the build to start, then + return execution back to the shell, with the status and release ID (if + applicable). When pushing to a local mode device, this option will cause + the command to not tail application logs when the build has completed.`, char: 'd', }), service: flags.string({ @@ -210,8 +212,8 @@ export default class PushCmd extends Command { gitignore: flags.boolean({ description: stripIndent` Consider .gitignore files in addition to the .dockerignore file. This reverts - to the CLI v11 behavior/implementation (deprecated) if compatibility is required - until your project can be adapted.`, + to the CLI v11 behavior/implementation (deprecated) if compatibility is + required until your project can be adapted.`, char: 'g', exclusive: ['multi-dockerignore'], }), @@ -328,15 +330,9 @@ export default class PushCmd extends Command { break; default: - throw new ExpectedError( - stripIndent` - Build target not recognized. Please provide either an application name or device address. - - The only supported device addresses currently are IP addresses. - - If you believe your build target should have been detected, and this is an error, please - create an issue.`, - ); + throw new ExpectedError(stripIndent` + Build target not recognized. Please provide either an application name or + device IP address.`); } } diff --git a/lib/utils/messages.ts b/lib/utils/messages.ts index 49cbb501..e443c3f3 100644 --- a/lib/utils/messages.ts +++ b/lib/utils/messages.ts @@ -71,17 +71,18 @@ export const dockerignoreHelp = `\ DOCKERIGNORE AND GITIGNORE FILES By default, the balena CLI will use a single ".dockerignore" file (if any) at the project root (--source directory) in order to decide which source files to -exclude from the "build context" (tar stream) sent to balenaCloud, Docker daemon -or balenaEngine. In a microservices (multicontainer) application, the source -directory is the directory that contains the "docker-compose.yml" file. +exclude from the "build context" (tar stream) sent to balenaCloud, Docker +daemon or balenaEngine. In a microservices (multicontainer) application, the +source directory is the directory that contains the "docker-compose.yml" file. -The --multi-dockerignore (-m) option may be used with microservices (multicontainer) -applications that define a docker-compose.yml file. When this option is used, -each service subdirectory (defined by the \`build\` or \`build.context\` service -properties in the docker-compose.yml file) is filtered separately according to -a .dockerignore file defined in the service subdirectory. If no .dockerignore -file exists in a service subdirectory, then only the default .dockerignore -patterns (see below) apply for that service subdirectory. +The --multi-dockerignore (-m) option may be used with microservices +(multicontainer) applications that define a docker-compose.yml file. When +this option is used, each service subdirectory (defined by the \`build\` or +\`build.context\` service properties in the docker-compose.yml file) is +filtered separately according to a .dockerignore file defined in the service +subdirectory. If no .dockerignore file exists in a service subdirectory, then +only the default .dockerignore patterns (see below) apply for that service +subdirectory. When the --multi-dockerignore (-m) option is used, the .dockerignore file (if any) defined at the overall project root will be used to filter files and From 93e18bea27cb494ea7e37a5fea044047a95c6414 Mon Sep 17 00:00:00 2001 From: Paulo Castro Date: Tue, 8 Sep 2020 14:55:56 +0100 Subject: [PATCH 2/2] push (local device): Add --pull option to force pulling base images again Connects-to: #1584 Change-type: minor --- doc/cli.markdown | 5 +++++ lib/actions-oclif/push.ts | 7 +++++++ lib/utils/device/deploy.ts | 2 ++ 3 files changed, 14 insertions(+) diff --git a/doc/cli.markdown b/doc/cli.markdown index 9f61b9b3..c01f6ada 100644 --- a/doc/cli.markdown +++ b/doc/cli.markdown @@ -2188,6 +2188,11 @@ purposes" (as the cloud builder needs previous images to compute delta updates), but the logs will not display the "Using cache" lines for each build step of a Dockerfile. +#### --pull + +When pushing to a local device, force the base images to be pulled again. +Currently this option is ignored when pushing to the balenaCloud builders. + #### --noparent-check Disable project validation check of 'docker-compose.yml' file in parent folder diff --git a/lib/actions-oclif/push.ts b/lib/actions-oclif/push.ts index 50e47051..e4fb13ff 100644 --- a/lib/actions-oclif/push.ts +++ b/lib/actions-oclif/push.ts @@ -33,6 +33,7 @@ interface FlagsDef { emulated: boolean; dockerfile?: string; // DeviceDeployOptions.dockerfilePath (alternative Dockerfile) nocache?: boolean; + pull?: boolean; 'noparent-check'?: boolean; 'registry-secrets'?: string; gitignore?: boolean; @@ -138,6 +139,11 @@ export default class PushCmd extends Command { build step of a Dockerfile.`, char: 'c', }), + pull: flags.boolean({ + description: stripIndent` + When pushing to a local device, force the base images to be pulled again. + Currently this option is ignored when pushing to the balenaCloud builders.`, + }), 'noparent-check': flags.boolean({ description: stripIndent` Disable project validation check of 'docker-compose.yml' file in parent folder`, @@ -310,6 +316,7 @@ export default class PushCmd extends Command { registrySecrets, multiDockerignore: options['multi-dockerignore'] || false, nocache: options.nocache || false, + pull: options.pull || false, nogitignore, noParentCheck: options['noparent-check'] || false, nolive: options.nolive || false, diff --git a/lib/utils/device/deploy.ts b/lib/utils/device/deploy.ts index 222ee5ea..a4494176 100644 --- a/lib/utils/device/deploy.ts +++ b/lib/utils/device/deploy.ts @@ -58,6 +58,7 @@ export interface DeviceDeployOptions { nogitignore: boolean; noParentCheck: boolean; nolive: boolean; + pull: boolean; detached: boolean; services?: string[]; system: boolean; @@ -526,6 +527,7 @@ async function assignDockerBuildOpts( t: generateImageName(task.serviceName), nocache: opts.nocache, forcerm: true, + pull: opts.pull, }; if (task.external) { task.dockerOpts.authconfig = await getAuthConfigObj(