Tools to make CI Packer builds awesome
Latest commit 227c547 Feb 3, 2017 @dgreene-r7 dgreene-r7 committed on GitHub Merge pull request #102 from rapid7/add-ruby-version
Bumped version because CI doesn't have 2.3.1 installed (whyyyy???)
Failed to load latest commit information.
bin Spelling in a comment, remove check for bundler environment in bin/build Jan 20, 2016
docs Updated documentation for post_processors. Feb 1, 2017
lib Implemented ECR repository lookup helper. Feb 1, 2017
spec Left in a pp Feb 1, 2017
template Add provisioner collection. Jan 31, 2017
.gitignore Add vagrant, berkshelf, and builderator state files as well as VERSIO… Dec 3, 2015
.rspec First pass at adding RSpec tests Dec 2, 2015
.rubocop.yml Fix lots of lint issues Dec 10, 2015
.rubocop_todo.yml lint lint lint Jan 20, 2016
.ruby-version Bumped version because CI doesn't have 2.3.1 installed (whyyyy???) Feb 3, 2017
Buildfile Add a Buildfile to enable tag creation for the Builderator project Jan 20, 2016
LICENSE.txt Starting Gem Jun 25, 2015 Documents how to debug cookbook dependency resolution issues. Jun 14, 2016
Rakefile Adds Rakefile to run specs Mar 11, 2016
Thorfile Add first packer tasks, seperate shared logic from tasks, complete am… Jul 6, 2015
builderator.gemspec Fix bundler version constraint Sep 23, 2016


Orchestration and configuration of the code development life-cycle.


Run build help for a complete enumeration of Builderator's commands.

local [PROFILE = default]

Provision a local VM using Vagrant and, by default, VirtualBox. Uses Berkshelf to fetch cookbooks, and Chef to provision the VM.

ec2 [PROFILE = default]

Provision an EC2 VM using Vagrant. Same workflow as local using the vagrant-aws plugin.

image [PROFILE = default]

Use Packer to build an image(s) for the specified profile.

By default, the generated images are copied to their respective ami_regions and tagged. Supply the --no-copy flag to keep the new image from being automatically copied to its configured regions.


Configuration can be loaded from DSL files as well as JSON and command line arguments. By default, Builderator searches in your home directory ($HOME/.builderator/Buildfile) and the working directory (./Builderator) for DSL files. Configuration sources are layered and flattened into a single DSL in the following order:

  • Global defaults defined in the Builderator sources
  • Config.defaults set by plugins, tasks, etc. in code
  • $HOME/.builderator/Buildfile
  • ./Buildfile
  • Config.overrides set by plugins, tasks, etc. in code
  • CLI arguments loaded from Thor

Additional documentation describes the configuration DSL interface.


Builderator integrates with other tools, including Berkshelf, Vagrant, and Packer, to orchestrate workflows by generating Berksfiles, Vagrantfiles, and JSON strings for Packer. This means that you can replace all of these files in your project with a single Buildfile.


The Berkshelf integration generates a Berksfile. The following configuration values are supported.


The generated Berksfile uses the :gecode dependency resolver by default. To use the :ruby solver, add this snippet to your Buildfile.

berkshelf do |berks|
  berks.solver :ruby

For help debugging cookbook dependency issues, you can set the DEBUG_RESOLVER environment variable and use the --debug flag when running build berks sucommands.

build berks vendor --debug


The Packer integration generates a Packer JSON configuration and passes it to STDIN of packer build -.


Builderator shells out to Vagrant to provision VMs on demand. Run

build vagrant plugins

to install required plugins for Builderator.


Builderator can automatically detect versions from SCM tags, increment the latest version of an SCM branch by a variety of steps, and create new SCM tags for new versions.

If the SCM has no version tags, Builderator will try to read the version from a VERSION file in the repository.

Additional documentation describes CLI commands, configuration, and detailed behavior.


Builderator includes a task to generate common project trees from configuration definitions and templates.

Each type of project is configurable via the project collection in the generator namespace:

generator.project :default do |default|
  default.ruby.version '2.1.5'
  default.builderator.version '~> 1.0'

  default.vagrant do |vagrant|
    vagrant.install false
    vagrant.version 'v1.8.0'

    vagrant.plugin 'vagrant-aws'
    vagrant.plugin 'vagrant-omnibus'

  default.resource :berksfile do |berksfile|
    berksfile.path 'Berksfile', 'Berksfile.lock'
    berksfile.action :rm

  default.resource :buildfile do |buildfile|
    buildfile.path 'Buildfile'
    buildfile.action :create
    buildfile.template 'template/Buildfile.erb'

  # ...

Valid actions for resources include :ignore, :create (update only if missing), :sync (create or update with prompt), and :rm. :create and :sync actions require a valid template source.

By default, the generator subcommand includes a default project which removes Vagrant, Berkshelf, and Packer configurations.


Builderator includes two utilities to search for and clean up EC2 resources.


The build-clean command prunes old EC2 resources in a region. The cleaner utility has configurable limits. For complete usage, run build-clean help.


The build-data utility is a command line interface for Builderator's internal resource lookup API. It has a limited query interface that allows filters to be constructed from a trailing list of argument:

build-data image architecture x86_64 virtualization-type hvm ...

Pre-defined filters can also be applied with the -f FILTER flag. These currently include

  • ubuntu-14.04-daily
  • windows-server2012-r2
  • windows-server2012-r2-core

Run build-data help for a complete listing of commands and arguments.