This page is an install guide that describes how to get up and running with Hosted Chef as quickly as possible and ends with a fast demonstration on how to work with cookbooks.

In order to make this as quick as possible, we make some assumptions. If your system does not meet these assumptions, you will need to use the Installation instructions that apply for the "flavor" of Chef you are installing.

Hosted Chef

We're using Hosted Chef so we can get started right away without setting up a Chef Server. If you want to set up your own server instead, head over to the Installation page.

Operating System

Chef runs on many popular Unix and Linux platforms as well as Max OSX and Windows. We will describe how to set up using CentOS 6.0 as a workstation and a client, but these are general directions that apply to most installations.

There is a Fast Start Guide for Ubuntu and a Fast Start Guide for Windows which goes over these same directions for Ubuntu 10.04 and Windows 2008 R2. For other OS specific instructions, go to the section of Installation that applies to the "flavor" of Chef you are installing, and proceed from there.

Management Workstation as a Client

In this guide we will be setting up a management workstation as a client. This means that the one node we setup here can be used to both manage your cookbooks and configuration in Hosted Chef, as well as use chef-client to run recipes on it. (If you already have a workstation configured and just want to add a client node, see the Client Bootstrap Fast Start Guide .)

We will be setting up the client node as both in this guide.

• Once you add more nodes you will not need to set them all up as workstations.
• You do however need at least one management workstation to manage your client nodes.

You don't however have to set up your management workstation to be a chef-client. If you prefer not to:

• Follow this guide through Step 4, and then
• use the Client Bootstrap Fast Start Guide to configure a client node separately.

This guide is going to direct you through the following steps:

1. Create a Hosted Chef account
2. Install and Update dependencies - ruby, ruby gems, ruby-dev and git-core
3. Install Chef and create the needed directories
4. Connect to Hosted Chef
5. Configure the workstation as a client
6. Download a Cookbook from the Community Site
7. Upload the cookbook to Hosted Chef
8. Add the Cookbook to the run_list
9. Run chef-client with the new Cookbook

At the end of this guide you will have a workstation setup with chef-client installed, a recipe downloaded and added to the node's run_list. These steps end with the recipe being run on the node by Chef.

Step 1: Create a Hosted Chef account

Working with a Chef is primarily done from a local workstation. Changes are made locally and uploaded to the Chef Server. Since we're using Hosted Chef as the Chef Server, you'll need to sign up for an account if you haven't already. (Don't worry! We won't charge you to use Hosted Chef for this guide - you can setup up to 5 nodes for free.)

Sign up for a Hosted Chef account. You will get an email validation shortly after you sign up. After you complete the sign-up, create an organization in the Console page, and then download the following files:

• Your Organization validation key. This is used to automatically register new Chef Clients (like servers you manage).
• The Knife configuration file.
• Your User key. This is used to authenticate your user with Hosted Chef.

The private keys are not stored by Hosted Chef. Download them to your local system, we'll use them in Step #5.

Step 2: Install and Update Dependencies

We're going to use Ruby 1.8.7, the default available on our chosen operating systems. We also need to install the ruby-devel package, as well as git and a few other dependencies. We will install RubyGems from source.

Below is an example of how you would install these in CentOS 6.0. For OS specific instructions, see the Installation page.

Chef 0.10 Note There are open issues with Chef 0.10.x and Ruby 1.8.6. If you are using Chef 0.10.x, you should get 1.8.7, 1.9.1, or 1.9.2 with SSL bindings.

Install Git

Git isn't needed to setup a node as a client, but it will be needed to setup a node as a workstation and follow the steps on this page. Workstations are able to download recipes from the Community Site, edit them, and them upload them to Hosted Chef. Once they are uploaded to the server any node that has been setup as a client or workstation will be able to use them. Clients do not need git installed but are unable to directly edit the recipes or upload changes to Hosted Chef without it. You will want at least one workstation setup to manage your organization. These directions walk you through setting up a workstation, for specific instructions on setting up a client instead, see the Installation page.

First you will want to install the rpm from the Extra Packages for Enterprise Linux (EPEL) yum repository:

Then you can use yum to install git:

Install RubyGems 1.3.7+

First, check to see if your operating system already has RubyGems installed and is at least version 1.3.7 by running the following:

If you're using CentOS, we recommend installing RubyGems from source rather than use the OS-provided version (if any), as it is cross platform, so we know what to expect. If you have 1.3.7 installed already, you have completed installing the dependencies needed for chef-client and you can move on to Step 3: Install Chef.

If you have an older version

You will need to update rubygems if you have a version older than 1.3.7, this can be done with this command:

Installing RubyGems from Source

If you do not have RubyGems installed at all, install it from source. (why?)

Step 3: Install Chef and create the needed directories

Now that all the dependancies are installed, you can install the chef-client with this command:

NOTE: as the message says, this could take a while. Be patient.

You can verify the installation was successful with:

Building infrastructure with Chef is like managing source code, so one of the first things we need to do is build the repository you'll use. You will need git installed to follow this step.

Knife reads configuration from the .chef directory, we'll need to create that one as well:

Copy the keys and knife configuration you downloaded earlier into this directory:

Replace USERNAME above with your Hosted Chef Username, and ORGANIZATION with the short-name you provided when you signed up.

Step 4: Connect to Hosted Chef

Run the following command to confirm knife is working with the Hosted Chef API.

The Workstation part of the install is now complete

You should now have a fully functional Management Workstation from which to interact with Chef and automate your infrastructure. The workstation is now able to download and upload recipes, and manage nodes with knife.

At this point you have two options. You can either continue this guide and configure this workstation as a client so it can run recipes as well, or you can setup chef-client on a separate node and use the workstation you just created to manage it remotely.

If you'd like to setup a separate node as a client so you can manage it remotely, please follow the Client Bootstrap Fast Start Guide. The rest of this guide assumes that you want to configure this workstation as a client.

Step 5: Configure the workstation as a client

You can configure chef-client with these commands:

You'll now have a client-config directory in your local repository:

To configure your workstation as a chef client, you just need to copy this directory to /etc/chef. First, make the directory:

Then copy the files from client-config into this new directory:

You will now need to run chef-client for the first time, so your node is added to the client list:

Once this is done, you can confirm this node was added with knife:

Instead of NODENAME you should see the name of your node here.

The Client install is now complete

At this point, your node is now configured as a management workstation and a client. The next steps explain how to add a recipe and run it on this node. If you are already familiar with Chef, you can skip the rest of the guide and it will have no impact on your install.

Step 6: Download a Cookbook from the Community Site

Now that Chef is installed, we can add a recipe to the run list and run it on this node. We're going to use the getting-started cookbook as an example.

First, download the getting-started cookbook from the Community Site, and add it to the local repository in the cookbooks directory. The knife cookbook site install sub-command does this for you.

Step 7: Upload a Cookbook to Hosted Chef

Next, upload the cookbook to Hosted Chef so it is available for systems that run the chef-client.

Step 8: Add a Cookbook to the run_list

Now you will want to add this cookbook to the run_list for this node. The run_list is a list of the recipes and roles that chef-client will run on the node.

You can add it with this command, substitute the name of your node for NODENAME:

Step 9: Run chef-client

You can now run the chef-client on this node and it will run the recipe you've added:

The first thing Chef did was download the getting-started cookbook. Then it ran the default recipe, which then wrote out our template. Lets look at what it wrote:

Your output will of course be dependent on the data we have stored about your node. You can also find this file it created by going to your home directory and opening chef-getting-started.txt.

You can also see what code the recipe contained by opening it with a text editor:

When you are ready to start configuring this node, you can remove this test recipe from the run_list with this command:

(For more information on editing and creating recipes, see the Cookbook Fast Start Guide.)

When you run chef-client, do you receive the error below?

You can resolve this by running the command as root. See Running Chef Client with Elevated Privileges for how to accomplish this.

Another fast start...

Cookbook Fast Start Guide

Cookbooks are how things are distributed and shared in Chef. Continue on the fast start path and visit this page for a quick guide to writing and using Chef Cookbooks.

Perhaps detail on Chef and its use...

Chef Basics

Learn some of the central concepts of configuration management benefits for your infrastructure.

1. We begin with an Architecture Introduction, covering the basic functions of the Chef Server, Nodes, and Chef Workstations and how these components communicate.
2. Then an overview of the Core Components, which introduces all of the aspects and components of modeling your infrastructure, Configuring Nodes and Managing Chef.
3. Onward to Cooking School and begin an Introduction to Cookbooks and More. Cookbooks are Chef's fundamental units of distribution, the way Chef users package up, distribute and share configuration information. Recipes, Resources, Attributes, Roles and more are also introduced.
4. The final basic section is an Introduction to Search and Data Bags, two of Chef's most powerful features allowing you to dynamically change the configuration of your infrastructure based on data.

Chef Architecture

With all that under your belt, it's time to tackle the dirty secrets of what's happening behind the scenes with Chef Architecture. We'll give you the scoop on Chef's Authentication and Authorization system and go over the Anatomy of a Chef Run, where we go in-depth with the process by which your systems get configured. From there we'll review all the executable parts of Chef - Chef Client, Chef Solo, Chef Server, Chef Indexer, and Server API and Cookbook Site API interaction.

Or view video tutorials and training...

Guides

We have a number of Walkthrough Guides available on the building of common stacks - including: Rails, Java, LAMP, and more. There are also How To Guides such as Deploying OpenStack with Chef, Guide to Creating A Cookbook and Writing A Recipe, and more - as well as a full 2.25 hour Webcast of a Chef Tutorial Session. These should be good resources for you as you move forward in the automation of your infrastructure.

Installation

Cookbook Fast Start Guide