Every Chef installation has a Chef Repository - it's the place where we install cookbooks, configuration files, and other information needed to use Chef and manage Chef clients. While you can structure this how ever you like (it is after all, your repository) we have provided a bare repository skeleton that you can use to get yourself started. We consider this to be the canonical best practice, especially when using the Opscode Cookboks. In flux! We are still working on getting repository management as smooth as we want. We have some upcoming services that are going to make this More Awesome. In the meantime, this is how we manage our own stuff - it should work well for you too.

Table of Contents Cloning the chef-repo If you don't want Git... Chef Repository Structure Configuring Rake Tasks Running Rake Tasks Catching Syntax Errors Install the latest Cookbooks Create new Cookbooks Node Roles Create Self-Signed SSL Certificates Update your Repository A typical workflow Next Steps

Cloning the chef-repo

To bootstrap your own repository, start by cloning chef-repo from Opscode's GitHub repository. You'll need to install Git of course. If you don't want to install Git, you can download a tarball.

We recommend storing your repository in version control, and we (obviously) prefer Git. If you want to wipe out the history and start fresh, feel free to remove the .git directory after you clone. Then you can initialize a new git repository, or create a subversion (or mercurial, or bazaar) repository. See the update rake task below for more information.

If you don't want Git...

We can't imagine why you wouldn't , but you can grab the tarball directly off GitHub:

You'll need to extract the tarball, and move the directory it creates (by default, username-project-commit/) to chef-repo. The commit ID may be different than this.

Download Projects You can do this for any project on GitHub, to directly download the tarball of the current master.

Chef Repository Structure

In the repository, you'll find:

• certificates/ - This directory contains SSL certificates generated with the rake ssl_cert task which you can put in cookbooks where needed.
• config/ - Top-level directory for general config files to configure the repository or support your own local environment. For example, openldap.ldif to bootstrap an LDAP directory.
  • config/client.rb.example - Sample Chef client config file. If you use the Opscode cookbooks, you should use the Chef cookbook to manage the Chef client itself.
  • config/server.rb.example - Sample Chef server config file. As with client, only use this if you're not going to configure your Chef server with the Opscode cookbooks.
  • config/rake.rb - Configuration file used by the Rake tasks. See Configuring Rake Tasks below for details.
  • config/solo.rb.example - Example solo file. Uncommon, but we don't manage the solo.rb in the Opscode Chef cookbook.
• cookbooks/ - Upstream and/or shared cookbooks.
• Rakefile - Sets up the rake tasks for managing the repository. Gets tasks from chef_repo.rake provided with the Chef gem (as of v0.7.0). See below for more information.
• roles/ - You can define node roles here. Note that these will always win, so if you create a role with the same name in the webui, the role from this directory will be used instead. This is a new feature of Chef 0.7.0 and not used in previous versions.
• site-cookbooks/ - Your local site's cookbooks. Modify parts of upstream cookbooks (like overriding templates), or add cookbooks specific to your organization.

For more about client.rb, server.rb and solo.rb, see the Configuring Chef page.

Configuring Rake Tasks

You can configure several options used by the Rake tasks. Edit config/rake.rb to get started.

There are some other options, but the comments should be sufficient explanation.

Running Rake Tasks

Now you have a Chef repository created, configured and ready to work for you. But how?

Through Rake tasks, of course. You can see a list of available Rake tasks and a short description by running rake -T. Let's take an in depth look at each and discuss usage, in order that they appear in rake -T output.

Catching Syntax Errors

The default task is test. Since Chef recipes are Ruby, we can verify they are syntactically valid by running the test task.

As of the chef-repo release after Chef 0.7.0, this will also check for syntax errors in ERB templates (Ruby syntax only) and also cache the mtime of the file so it will only check files that changed. This is actually handled with two tasks, test_recipes and test_templates, and you can modify the test task if you don't want to test templates.

Install the latest Cookbooks

Since we're assuming you keep the repository in your home directory, you'll want to install them to the Chef Server.

This task runs the update, test, metadata and roles tasks. It copies the cookbooks and site-cookbooks to the location specified in config/rake.rb - typically under /srv/chef.

Create new Cookbooks

We provide a task that will create a new cookbook for you. It takes two environment parameters.

• COOKBOOK: required, name of the cookbook.
• CB_PREFIX: optional, whether to put it in a specific 'cookbooks' directory. See example.

For example, to create a new cookbook titled 'apache', from the top of the repository:

A skeletal cookbook, complete with default recipe file (containing a license preamble), a README.rdoc and a default Metadata file, will be created in the cookbooks directory, or if you specified the CB_PREFIX as site-, in site-cookbooks.

Node Roles

A new feature of Chef 0.7.0 is Roles. You can create Ruby or JSON files in roles/, this task converts the Ruby into JSON.

This task is automatically run by the install task. You can read more about how to create roles on the Roles page.

Create Self-Signed SSL Certificates

Because you need them all the time, the Chef Repo Rakefile knows how to create self-signed certificates for SSL. Just give it an fully qualified domain name via FQDN, and it will drop off all the SSL artifacts in the certificates directory.

You can distribute these via recipes, and put them in your Cookbooks.

Update your Repository

Assuming you are collaborating with an upstream repository (say, SVN or Git), the Rakefile can update it for you automatically. (This is handy when you want to install the latest Cookbooks on your Chef Server).

A typical workflow

As you work with Chef, a typical workflow will be:

1. Clone/checkout the repository (its now stored in Git or SVN right? ) on your workstation, or your home directory on the Chef Server.
2. Create or update Cookbooks.
3. Commit your changes and update your shared repository.
4. Run rake install from your clone/checkout on the Chef Server
5. Test!

Next Steps

If you are following the Installation walk through we recommend the Cookbook Quick Start section next to create an example cookbook with recipes and applying it to a client.