{section}
{column:width=70%}
Every Chef installation needs a Chef Repository. This is the place where cookbooks, roles, config files and other artifacts for managing systems with Chef will live. We strongly recommend storing this repository in a version control system such as Git and treat it like source code.
While we prefer Git, and make this repository available via GitHub, you are welcome to download a tar or zip archive and use your favorite version control system to manage the code.
h1. Chef Terms used on this page
----
We use some terms regarding the Chef Repository that have further explanation on their own pages.
* [Knife] - Chef's command-line API tool.
* [Cookbooks] - Unit of code distribution in Chef.
* [Roles] - Describe what a node should be / do.
* [Data Bags] - Arbitrary stores of data about the environment / infrastructure.
h1. Getting the [chef-repo|http://github.com/opscode/chef-repo]
----
To create your own repository, start by cloning Opscode's {{chef-repo}} from GitHub. You'll need to install Git of course. If you don't want to install Git, you can download a tarball.
{code:bash|linenos=false|title=Git Clone chef-repo}
git clone git://github.com/opscode/chef-repo.git
{code}
If you want to wipe out the existing 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.
h2. If you don't want Git...
You can grab the tarball directly off GitHub:
{code:bash|linenos=false|title=Grab Tarball of Chef Repo}
wget http://github.com/opscode/chef-repo/tarball/master
{code}
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.
{code:bash|linenos=false|title=Extract Tarball}
tar -zxf opscode-chef-repo-cfeed8506ffc32cf76cf089b71975e90931486dc.tar.gz
mv opscode-chef-repo-cfeed8506ffc32cf76cf089b71975e90931486dc chef-repo
{code}
We still strongly recommend you use some kind of version control tool to manage the source code in your chef-repo, so use your favorite tool to initialize the repository for tracking.
{column}
{column:width=30%}
{panel:title=Table of Contents}
{toc:minLevel=1|maxLevel=2}
{panel}
{column}
{section}
h1. Repository Directories
----
This repository contains several directories, and each directory contains a README file that describes what it is for in greater detail, and how to use it for managing your systems with Chef.
* {{config/}} - Contains the Rake configuration file, {{rake.rb}}.
* {{cookbooks/}} - Cookbooks you download or create.
* {{data_bags/}} - Store data bags and items in .json in the repository.
* {{roles/}} - Store roles in .rb or .json in the repository.
* {{certificates/}} - SSL certificates generated by {{rake ssl_cert}} live here.
h2. config
Contains the Rake config file. See [#Configuration] below.
h2. cookbooks
This directory contains the [cookbooks|Cookbooks] used to configure systems in your infrastructure with Chef.
Configure knife to use your preferred copyright holder, email contact and license. Add the following lines to {{~/chef-repo/.chef/knife.rb}}.
{code}
cookbook_copyright "Example, Com."
cookbook_email "cookbooks@example.com"
cookbook_license "apachev2"
{code}
Supported values for {{cookbook_license}} are "apachev2" or "none". These settings are used to prefill comments in the default recipe, and the corresponding values in the metadata.rb. You are free to change these in those files.
Create new cookbooks in this directory with Knife.
{code}
knife cookbook create COOKBOOK
{code}
This will create all the cookbook directory components. You don't need to use them all, and can delete the ones you don't need. It also creates a README file, metadata.rb and default recipe.
You can also download cookbooks directly from the Opscode Cookbook Site. There are two subcommands to help with this depending on what your preference is.
The first and recommended method is to use a vendor branch if you're using Git. This is automatically handled with Knife.
{code}
knife cookbook site vendor COOKBOOK
{code}
This will:
* Download the cookbook tarball from cookbooks.opscode.com.
* Ensure its on the git master branch.
* Checks for an existing vendor branch, and creates if it doesn't.
* Checks out the vendor branch (chef-vendor-COOKBOOK).
* Removes the existing (old) version.
* Untars the cookbook tarball it downloaded in the first step.
* Adds the cookbook files to the git index and commits.
* Creates a tag for the version downloaded.
* Checks out the master branch again.
* Merges the cookbook into master.
The last step will ensure that any local changes or modifications you have made to the cookbook are preserved, so you can keep your changes through upstream updates.
If you're not using Git, use the site download subcommand to download the tarball.
{code}
knife cookbook site download COOKBOOK
{code}
This creates the COOKBOOK.tar.gz from in the current directory (e.g., {{~/chef-repo}}). We recommend following a workflow similar to the above for your version control tool.
h2. data_bags
This directory contains directories of the various data bags you create for your infrastructure. Each subdirectory corresponds to a data bag on the Chef Server, and contains JSON files of the items that go in the bag.
First, create a directory for the data bag.
{code}
mkdir data_bags/BAG
{code}
Then create the JSON files for items that will go into that bag.
{code}
$EDITOR data_bags/BAG/ITEM.json
{code}
The JSON for the ITEM must contain a key named "id" with a value equal to "ITEM". For example,
{code:javascript}
{
"id": "foo"
}
{code}
Next, create the data bag on the Chef Server.
{code}
knife data bag create BAG
{code}
Then upload the items in the data bag's directory to the Chef Server.
{code}
knife data bag from file BAG ITEM.json
{code}
h2. roles
Create roles here, in either the Role Ruby DSL (.rb) or JSON (.json) files. To install roles on the server, use knife.
For example, create {{roles/base_example.rb}}:
{code}
name "base_example"
description "Example base role applied to all nodes."
# List of recipes and roles to apply. Requires Chef 0.8, earlier versions use 'recipes()'.
#run_list()
# Attributes applied if the node doesn't have it set already.
#default_attributes()
# Attributes applied no matter what the node has set already.
#override_attributes()
{code}
Then upload it to the Chef Server:
{code}
knife role from file roles/base_example.rb
{code}
h2. certificates
Creating SSL certificates is a common task done in web application infrastructures, so a rake task is provided to generate certificates. These certificates are stored here by the ssl_cert task.
Configure the values used in the SSL certificate by modifying {{config/rake.rb}}.
To generate a certificate set for a new monitoring server, for example:
{code}
rake ssl_cert FQDN=monitoring.example.com
{code}
Once the certificates are generated, copy them into the cookbook(s) where you want to use them.
{code}
cp certificates/monitoring.example.com.* cookbooks/COOKBOOK/files/default
{code}
In the recipe for that cookbook, create a [cookbook_file resource|Resources#Cookbook File] to configure a resource that puts them in place on the destination server.
{code:ruby}
cookbook_file '/etc/apache2/ssl/monitoring.example.com.pem'
owner 'root'
group 'root'
mode 0600
end
{code}
h1. Rake Tasks
----
The repository contains a {{Rakefile}} that includes tasks that are installed with the Chef libraries. To view the tasks available with in the repository with a brief description, run {{rake \-T}}.
The default task ({{default}}) is run when executing {{rake}} with no arguments. It will call the task {{test_cookbooks}}.
The following tasks are not directly replaced by knife sub-commands.
* {{bundle_cookbook[cookbook]}} - Creates cookbook tarballs in the {{pkgs/}} dir.
* {{install}} - Calls {{update}}, {{roles}} and {{upload_cookbooks}} Rake tasks.
* {{ssl_cert}} - Create self-signed SSL certificates in {{certificates/}} dir.
* {{update}} - Update the repository from source control server, understands git and svn.
The following tasks duplicate functionality from knife and may be removed in a future version of Chef.
* {{metadata}} - replaced by {{knife cookbook metadata \-a}}.
* {{new_cookbook}} - replaced by {{knife cookbook create}}.
* {{role[role_name]}} - replaced by {{knife role from file}}.
* {{roles}} - iterates over the roles and uploads with {{knife role from file}}.
* {{test_cookbooks}} - replaced by {{knife cookbook test \-a}}.
* {{test_cookbook[cookbook]}} - replaced by {{knife cookbook test COOKBOOK}}.
* {{upload_cookbooks}} - replaced by {{knife cookbook upload \-a}}.
* {{upload_cookbook[cookbook]}} - replaced by {{knife cookbook upload COOKBOOK}}.
h1. Configuration
----
The repository uses two configuration files.
* config/rake.rb
* .chef/knife.rb
The first, {{config/rake.rb}} configures the Rakefile in two sections.
* Constants used in the {{ssl_cert}} task for creating the certificates.
* Constants that set the directory locations used in various tasks.
If you use the {{ssl_cert}} task, change the values in the {{config/rake.rb}} file appropriately. These values were also used in the {{new_cookbook}} task, but that task is replaced by the {{knife cookbook create}} command which can be configured below.
The second config file, {{.chef/knife.rb}} is a repository specific configuration file for knife. If you're using the Opscode Platform, you can download one for your organization from the management console. If you're using the Open Source Chef Server, you can generate a new one with {{knife configure}}. For more information about configuring Knife, see the [Knife documentation|http://help.opscode.com/faqs/chefbasics/knife].
h1. Next Steps
----
Learn more about [Chef Basics] or get started on working with [Cookbooks] at the [Cookbook Quick Start].
{column:width=70%}
Every Chef installation needs a Chef Repository. This is the place where cookbooks, roles, config files and other artifacts for managing systems with Chef will live. We strongly recommend storing this repository in a version control system such as Git and treat it like source code.
While we prefer Git, and make this repository available via GitHub, you are welcome to download a tar or zip archive and use your favorite version control system to manage the code.
h1. Chef Terms used on this page
----
We use some terms regarding the Chef Repository that have further explanation on their own pages.
* [Knife] - Chef's command-line API tool.
* [Cookbooks] - Unit of code distribution in Chef.
* [Roles] - Describe what a node should be / do.
* [Data Bags] - Arbitrary stores of data about the environment / infrastructure.
h1. Getting the [chef-repo|http://github.com/opscode/chef-repo]
----
To create your own repository, start by cloning Opscode's {{chef-repo}} from GitHub. You'll need to install Git of course. If you don't want to install Git, you can download a tarball.
{code:bash|linenos=false|title=Git Clone chef-repo}
git clone git://github.com/opscode/chef-repo.git
{code}
If you want to wipe out the existing 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.
h2. If you don't want Git...
You can grab the tarball directly off GitHub:
{code:bash|linenos=false|title=Grab Tarball of Chef Repo}
wget http://github.com/opscode/chef-repo/tarball/master
{code}
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.
{code:bash|linenos=false|title=Extract Tarball}
tar -zxf opscode-chef-repo-cfeed8506ffc32cf76cf089b71975e90931486dc.tar.gz
mv opscode-chef-repo-cfeed8506ffc32cf76cf089b71975e90931486dc chef-repo
{code}
We still strongly recommend you use some kind of version control tool to manage the source code in your chef-repo, so use your favorite tool to initialize the repository for tracking.
{column}
{column:width=30%}
{panel:title=Table of Contents}
{toc:minLevel=1|maxLevel=2}
{panel}
{column}
{section}
h1. Repository Directories
----
This repository contains several directories, and each directory contains a README file that describes what it is for in greater detail, and how to use it for managing your systems with Chef.
* {{config/}} - Contains the Rake configuration file, {{rake.rb}}.
* {{cookbooks/}} - Cookbooks you download or create.
* {{data_bags/}} - Store data bags and items in .json in the repository.
* {{roles/}} - Store roles in .rb or .json in the repository.
* {{certificates/}} - SSL certificates generated by {{rake ssl_cert}} live here.
h2. config
Contains the Rake config file. See [#Configuration] below.
h2. cookbooks
This directory contains the [cookbooks|Cookbooks] used to configure systems in your infrastructure with Chef.
Configure knife to use your preferred copyright holder, email contact and license. Add the following lines to {{~/chef-repo/.chef/knife.rb}}.
{code}
cookbook_copyright "Example, Com."
cookbook_email "cookbooks@example.com"
cookbook_license "apachev2"
{code}
Supported values for {{cookbook_license}} are "apachev2" or "none". These settings are used to prefill comments in the default recipe, and the corresponding values in the metadata.rb. You are free to change these in those files.
Create new cookbooks in this directory with Knife.
{code}
knife cookbook create COOKBOOK
{code}
This will create all the cookbook directory components. You don't need to use them all, and can delete the ones you don't need. It also creates a README file, metadata.rb and default recipe.
You can also download cookbooks directly from the Opscode Cookbook Site. There are two subcommands to help with this depending on what your preference is.
The first and recommended method is to use a vendor branch if you're using Git. This is automatically handled with Knife.
{code}
knife cookbook site vendor COOKBOOK
{code}
This will:
* Download the cookbook tarball from cookbooks.opscode.com.
* Ensure its on the git master branch.
* Checks for an existing vendor branch, and creates if it doesn't.
* Checks out the vendor branch (chef-vendor-COOKBOOK).
* Removes the existing (old) version.
* Untars the cookbook tarball it downloaded in the first step.
* Adds the cookbook files to the git index and commits.
* Creates a tag for the version downloaded.
* Checks out the master branch again.
* Merges the cookbook into master.
The last step will ensure that any local changes or modifications you have made to the cookbook are preserved, so you can keep your changes through upstream updates.
If you're not using Git, use the site download subcommand to download the tarball.
{code}
knife cookbook site download COOKBOOK
{code}
This creates the COOKBOOK.tar.gz from in the current directory (e.g., {{~/chef-repo}}). We recommend following a workflow similar to the above for your version control tool.
h2. data_bags
This directory contains directories of the various data bags you create for your infrastructure. Each subdirectory corresponds to a data bag on the Chef Server, and contains JSON files of the items that go in the bag.
First, create a directory for the data bag.
{code}
mkdir data_bags/BAG
{code}
Then create the JSON files for items that will go into that bag.
{code}
$EDITOR data_bags/BAG/ITEM.json
{code}
The JSON for the ITEM must contain a key named "id" with a value equal to "ITEM". For example,
{code:javascript}
{
"id": "foo"
}
{code}
Next, create the data bag on the Chef Server.
{code}
knife data bag create BAG
{code}
Then upload the items in the data bag's directory to the Chef Server.
{code}
knife data bag from file BAG ITEM.json
{code}
h2. roles
Create roles here, in either the Role Ruby DSL (.rb) or JSON (.json) files. To install roles on the server, use knife.
For example, create {{roles/base_example.rb}}:
{code}
name "base_example"
description "Example base role applied to all nodes."
# List of recipes and roles to apply. Requires Chef 0.8, earlier versions use 'recipes()'.
#run_list()
# Attributes applied if the node doesn't have it set already.
#default_attributes()
# Attributes applied no matter what the node has set already.
#override_attributes()
{code}
Then upload it to the Chef Server:
{code}
knife role from file roles/base_example.rb
{code}
h2. certificates
Creating SSL certificates is a common task done in web application infrastructures, so a rake task is provided to generate certificates. These certificates are stored here by the ssl_cert task.
Configure the values used in the SSL certificate by modifying {{config/rake.rb}}.
To generate a certificate set for a new monitoring server, for example:
{code}
rake ssl_cert FQDN=monitoring.example.com
{code}
Once the certificates are generated, copy them into the cookbook(s) where you want to use them.
{code}
cp certificates/monitoring.example.com.* cookbooks/COOKBOOK/files/default
{code}
In the recipe for that cookbook, create a [cookbook_file resource|Resources#Cookbook File] to configure a resource that puts them in place on the destination server.
{code:ruby}
cookbook_file '/etc/apache2/ssl/monitoring.example.com.pem'
owner 'root'
group 'root'
mode 0600
end
{code}
h1. Rake Tasks
----
The repository contains a {{Rakefile}} that includes tasks that are installed with the Chef libraries. To view the tasks available with in the repository with a brief description, run {{rake \-T}}.
The default task ({{default}}) is run when executing {{rake}} with no arguments. It will call the task {{test_cookbooks}}.
The following tasks are not directly replaced by knife sub-commands.
* {{bundle_cookbook[cookbook]}} - Creates cookbook tarballs in the {{pkgs/}} dir.
* {{install}} - Calls {{update}}, {{roles}} and {{upload_cookbooks}} Rake tasks.
* {{ssl_cert}} - Create self-signed SSL certificates in {{certificates/}} dir.
* {{update}} - Update the repository from source control server, understands git and svn.
The following tasks duplicate functionality from knife and may be removed in a future version of Chef.
* {{metadata}} - replaced by {{knife cookbook metadata \-a}}.
* {{new_cookbook}} - replaced by {{knife cookbook create}}.
* {{role[role_name]}} - replaced by {{knife role from file}}.
* {{roles}} - iterates over the roles and uploads with {{knife role from file}}.
* {{test_cookbooks}} - replaced by {{knife cookbook test \-a}}.
* {{test_cookbook[cookbook]}} - replaced by {{knife cookbook test COOKBOOK}}.
* {{upload_cookbooks}} - replaced by {{knife cookbook upload \-a}}.
* {{upload_cookbook[cookbook]}} - replaced by {{knife cookbook upload COOKBOOK}}.
h1. Configuration
----
The repository uses two configuration files.
* config/rake.rb
* .chef/knife.rb
The first, {{config/rake.rb}} configures the Rakefile in two sections.
* Constants used in the {{ssl_cert}} task for creating the certificates.
* Constants that set the directory locations used in various tasks.
If you use the {{ssl_cert}} task, change the values in the {{config/rake.rb}} file appropriately. These values were also used in the {{new_cookbook}} task, but that task is replaced by the {{knife cookbook create}} command which can be configured below.
The second config file, {{.chef/knife.rb}} is a repository specific configuration file for knife. If you're using the Opscode Platform, you can download one for your organization from the management console. If you're using the Open Source Chef Server, you can generate a new one with {{knife configure}}. For more information about configuring Knife, see the [Knife documentation|http://help.opscode.com/faqs/chefbasics/knife].
h1. Next Steps
----
Learn more about [Chef Basics] or get started on working with [Cookbooks] at the [Cookbook Quick Start].