Soloist lets you quickly and easily converge Chef recipes using chef-solo. It does not require a Chef server, but can exploit community cookbooks, github-hosted cookbooks and locally-sourced cookbooks through Librarian.

Soloist was originally built to support the Pivotal Labs Workstation Cookbook, now known as Sprout.

Let's say you want to converge the Pivotal Labs Workstation default recipe and install Sublime Text 2.

1. You'll need to have Soloist installed:

    $ gem install soloist
   

2. You'll need a Cheffile in your home directory that points Librarian to all the cookbooks you've included:

    $ cat /Users/pivotal/Cheffile
    site "http://community.opscode.com/api/v1"
    cookbook "pivotal_workstation",
             :git => "https://github.com/pivotal/pivotal_workstation"
   

3. You'll need to create a soloistrc file in your home directory to tell Chef which recipes to converge:

    $ cat /Users/pivotal/soloistrc
    recipes:
      - pivotal_workstation::default
      - pivotal_workstation::sublime_text
   

4. You'll need to run soloist for anything to happen:

    $ soloist
   

Here's an example of a soloistrc:

cookbook_paths:
  - /opt/beans
recipes:
  - beans::chili
  - beans::food_fight
  - napkins

This tells Soloist to search in both /opt/beans and ./cookbooks (relative to the soloistrc) for cookbooks to run. Then, it attempts to converge the beans::chili, beans::food_fight and napkins recipes.

Soloist lets you override node attributes. Let's say we've got a bash::prompt recipe for which we want to set node['bash']['prompt']['color']='p!nk'. No problem!

recipes:
  - bash::prompt
node_attributes:
  bash:
    prompt:
      color: p!nk

Soloist allows conditionally switching on environment variables. Let's say we only want to include the embarrassment::parental recipe when the MEGA_PRODUCTION environment variable is set to juggalos. Here's the soloistrc:

cookbook_paths:
  - /fresno
recipes:
  - disaster
env_variable_switches:
  MEGA_PRODUCTION:
    juggalos:
      recipes:
        - embarrassment::parental

So now, this is the result of our Soloist run:

$ MEGA_PRODUCTION=juggalos soloist
Installing disaster (1.0.0)
Installing embarrassment (1.0.0)
… chef output …
INFO: Run List expands to [disaster, embarrassment::parental, faygo]
… chef output …

If we set MEGA_PRODUCTION=godspeed, the embarrassment::parental recipe is not converged.

Soloist can also run one-off recipes:

$ soloist run_recipe lice::box
Installing lice (1.0.0)
… chef output …
INFO: Run List expands to [lice::box]
… chef output …

This just runs the lice::box recipe from your current set of cookbooks. It still uses all the node_attributes and env_variable_switches logic.

Soloist runs chef-solo at log level info by default, which is helpful when you need to see what your Chef run is doing. If you need more information, you can set the LOG_LEVEL environment variable:

$ LOG_LEVEL=debug soloist

See LICENSE for details.