build-steps-notes.md

Instructions

1. Configure Local Machine

• To authenticate your machine with Cloud API, use the drush ac-api-login command or download drush aliases from Acquia Cloud. This will save your credentials to ~/.acquia/cloudapi.conf.
• Next, use buildsteps login to authenticate with buildsteps.

2. Add a site to buildsteps via buildsteps add-site <site-name>

• <site-name> is the machine name of your acquia subscription.

3. Create .acquia.yml in your local project's root directory

• @see https://docs.acquia.com/build-steps/yaml#animated for example file
• Commit new file and push changes to Acquia Cloud

4. Execute buildsteps build.

• Without any additional arguments, this trigger a build using .acquia.yml file on the remote copy of the current local branch.
• You may alternatively specify the site and remote git branch, buildsteps build --site-name bolted8 --vcs-path 8.x. This would trigger Build Steps to initiate a build using the .acquia.yml file on the remote 8.x branch.

5. Check status of build using buildsteps status <site-name>

• Quickly determine if task has failed using buildsteps status <site-name> | grep 'Exit Code'. Only returns results if an error code was returned.

Feedback

• Instructions need clarification
  • Rename buildsteps.phar to buildsteps
  • Setup instructions do not specify need to run buildsteps login
  • Acceptable values of <site-name> should be specified. Is this the machine name of my Acquia subscription?
  • --vcs-path is very unclear. Is this the git branch or tag? If so, it should be git-branch, git-tag, or something of that nature.
  • It is unclear what happens when buildsteps build <site-name> is executed. Does it use a local acquia.yml file for instructions? Does it use the .acquia.yml file from the specified branch? If so, instructions should indicate that .acquia.yml needs to be committed, pushed, and then buildsteps build should be executed.
• Technical Issues:
  • buildsteps status <site-name> does not indicate status code in a reliable way. Also does not use color formatting for log.
  • composer selfupdate fails: Composer update failed: the "/usr/local/bin/composer" file could not be written. This is a frequently used debugging step.
  • buildsteps status <site-name> only permits querying the most recent task. It should accept params to display specific task ids, and perhaps X most recent tasks.
  • nvm package should be available to that users can specify version of NodeJS to use.
  • Attempting to install npm packages globally (as recommended by nmp for Grunt-based workflows) causes many errors, likely due to insufficient permissions. @see https://docs.npmjs.com/getting-started/fixing-npm-permissions. E.g., npm install -g gulp causes:

    npm ERR! tar.unpack untar error /home/local/.npm/gulp/3.9.0/package.tgz
    npm ERR! Linux 4.1.10-17.31.amzn1.x86_64
    npm ERR! argv "/usr/bin/node" "/usr/bin/npm" "install" "-g" "gulp"
    npm ERR! node v0.12.9
    npm ERR! npm  v2.14.9
    npm ERR! path /usr/lib/node_modules/gulp
    npm ERR! code EACCES
    npm ERR! errno -13
    
    npm ERR! Error: EACCES, mkdir '/usr/lib/node_modules/gulp'
    npm ERR!     at Error (native)
    npm ERR!  { [Error: EACCES, mkdir '/usr/lib/node_modules/gulp']
    npm ERR!   errno: -13,
    npm ERR!   code: 'EACCES',
    npm ERR!   path: '/usr/lib/node_modules/gulp',
    npm ERR!   fstream_type: 'Directory',
    npm ERR!   fstream_path: '/usr/lib/node_modules/gulp',
    npm ERR!   fstream_class: 'DirWriter',
    npm ERR!   fstream_stack:
    npm ERR!    [ '/usr/lib/node_modules/npm/node_modules/fstream/lib/dir-writer.js:35:25',
    npm ERR!      '/usr/lib/node_modules/npm/node_modules/mkdirp/index.js:47:53',
    npm ERR!      'FSReqWrap.oncomplete (fs.js:95:15)' ] }
    npm ERR!
    npm ERR! Please try running this command again as root/Administrator.
    

  • There is no way to handle a task that has stalled. Provide commands to cancel or restart a task? I have already run into scenarios where task does not start for 20+ min.