This installation guide describes how to get up and running with Chef as quickly as possible, and will walk you through adding a client node to your organization in Hosted Chef.

You can run your own Chef Server, but for this guide we will use Hosted Chef as the Chef Server, so you don't have to set one up.

• Clients are able to run chef-client, but will be unable to download, edit, and upload recipes with knife.
• Management Workstations are able to download, edit and upload recipes, and can be setup to work as clients as well so they can run chef-client.

You can find directions for setting up workstations in the Fast Start Guides:

• Fast Start Guide for Ubuntu
• Fast Start Guide for CentOS
• Fast Start Guide for Windows

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 Ubuntu 10.04 as a client, but these are general directions that apply to most installations. For OS specific instructions, go to the Installation page.

You already have a Management Workstation setup

In this guide we will be setting up a node as a client. We assume you already have another node setup as your Management Workstation.

If you do not already have a workstation setup, you can find directions in the Fast Start Guides:

• Fast Start Guide for Ubuntu
• Fast Start Guide for CentOS
• Fast Start Guide for Windows

You'll want to follow one of these guides through at least step 4 and confirmed the knife commands worked properly. Once this is completed, you can return to this guide to setup another node as a client.

All of the commands in this guide will be ran from the Management Workstation by using knife commands to configure the client node remotely.

We will complete the following steps from the Management Workstation:

1. Bootstrap the client node
2. Verify the install completed
3. Manage recipes on the new client node
4. Run chef-client on the new client node remotely
5. Running chef-client as a daemon

When you are done with this guide you will have a node added as a client to the Hosted Chef organization, and the getting-started recipe will of been ran on it. You will also have a basic understanding of how you can manage this new client node remotely from your workstation.

Using Amazon's EC2 for your clients? The EC2 Bootstrap Fast Start Guide goes over these same steps, and includes some additional steps that are specific to bootstrapping EC2 instances.

Step 1: Bootstrap the Ubuntu system

Use Knife Bootstrap to set up the target Ubuntu 10.04 client node with Ruby, Chef, and run Chef automatically. All of the steps in this guide are done from the management workstation you've already setup, the node must be accessible from the workstation via SSH. The base OS installation assumes that a user named ubuntu is created and has permission to run sudo. (See the Knife Bootstrap page for more information on how the sub-command works and other options available.)

Substitute IP_ADDRESS for the IP you want knife to SSH to, and PASSWORD for the sudo password for the ubuntu user:

You should see the current version of chef in the output of this command, Chef 0.10.10. Now chef-client has been installed on the node and it is ready for recipes to be added to it. The rest of this guide will explain how to add and run a recipe remotely.

Using a private key for SSH authentication? You can specify that you want to use a private key with the -i switch instead of sending it -P. For example you could use a command like this: With Chef 0.10.6+, you can also allow knife bootstrap to prompt you for a password. More information on the other options available with the knife bootstrap command can be found on the Knife Bootstrap wiki page.

Step 2: Verify the install completed

Now that the client has registered with Hosted Chef, it should show up on the node list. You can use knife to display a list of nodes:

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 client. The next steps explain how to add a recipe and run it on this node remotely from the workstation, as well as run the client as a daemon. 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 3: Manage recipes on the new client node

Now that your client is setup, you'll need to know how to add a recipe to it so you can start configuring it. This step will walk you through adding the getting-started recipe to it as an example. These steps are also ran from the management workstation.

We will need to download the getting-started cookbook from the Community Site:

And then upload the recipe to Hosted Chef so it is available for our nodes:

Once this is completed, you can add this new recipe to the new nodes run list:

Step 4: Run chef-client on the new client node

You can just SSH into the node at this point and run sudo chef-client, but it may be easier to run this command remotely from the workstation with knife. This way, once you have multiple nodes added you can run chef-client on all of them at once if needed by using a wildcard (*) as the NODENAME.

You can run chef-client remotely from the management workstation with knife with the SSH subcommand:

If the node doesn't have a fully qualified domain name (FQDN) and is only accessible through a private IP address, you may need to specify that it uses the IP to SSH instead of the FQDN:

For more information on the knife SSH subcommand, review the Knife Built In Subcommands.

Running chef-client will run the getting-started recipe you've added to the client node's run_list. The getting-started recipe added a template to the client node in ~/chef-getting-started.txt. Once Chef has completed on the client, you can log into the client and look at the template:

Your output will of course be dependent on the data we have stored about your node.

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

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

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

Step 5: Running chef-client as a daemon

You can setup chef-client to run as a daemon, so it will periodically run chef-client and get any updates you have submitted without needing to SSH to it every time. The easiest way to do this is with the chef-client cookbook. This will setup the chef-client as a daemon and add a time splay, you can add it the same way you added the getting-started recipe:

Once it is added you'll need to run chef-client on the node once more for the recipe to configure the server:

Next time you bootstrap a new client node, you can include the chef-client cookbook in the Knife Bootstrap command from Step 1 if desired. This will add it to the run_list for the node and run it when installing Chef. You can do this with the -r switch:

You can read the cookbook's README to get more information on altering the default attributes.

It only takes a small change to a dependency or environment to cause these instructions to not be exact. If something goes wrong, first check the Installation page and refer to documents specific to your OS. If this doesn't help, head over to the Support page for information on where and how to find help from Opscode and the rest of the Chef community.

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