If your Chef Server is the Opscode Platform, please see the Getting Started guide on the Opscode Support Site for more information. If you are only using chef-solo, proceed to the Chef Solo page to learn more about configuring Chef Solo. Bootstrap Introduction "Configuring my chef server with chef - it doesn't get any more meta than this" - bbrowning Bootstrap in the context of this document refers to the initial configuration of a Chef Server for your infrastructure, or of a Chef Client that will talk to a server you have configured already. The bootstrap install works using chef-solo to run chef recipes that install a full Chef Server. The bootstrap install does this because RubyGems does not have a way to handle several things package management systems do easily: Create configuration files. Create system-level init scripts. Start new services from init scripts. Install non-Ruby programs/libraries. This bootstrap is handled by two special recipes in the Opscode Chef Cookbook, chef::bootstrap_server and chef::bootstrap_client. This page will describe the basics of how to use these recipes. The documentation for the cookbook, including the details of the settings available to configure these recipes, is in the README of the cookbook. Runs as Root These recipes are going to be run as root. You should read the Chef Cookbook README to understand what it is doing.

Table of Contents Bootstrap Introduction Before you Start Supported Platforms You Must Have a Fully Qualified Domain Name Install Ruby On Debian and Ubuntu On Red Hat and CentOS Install RubyGems from Source Install Chef Gem Chef Solo Configuration Chef Solo Configuration File: solo.rb Chef Solo Attributes Configuration: chef.json Bootstrap Chef Server Run chef-solo For RHEL/CentOS Systems Verify That All Components are Running Configure the Command Line Client Verify Your Knife Client Configuration Create a Knife Client for Your Laptop/Desktop

Before you Start

Supported Platforms

The bootstrap installation has been tested for setting up clients and servers on several platforms.

Server

The platforms supported for a Chef Server with the bootstrap recipes are limited due to the server's dependency availability. The server recipe may work for other platforms, but if not you may need to manually set up the server.

• Ubuntu 8.10 through 10.04
• Debian 5.0 (stable, testing, unstable)
• CentOS 5.x (should work on RHEL 5.x, too)

Client

These instructions have been tested on the following Client platforms. That is, the client was correctly configured to connect to a specified Chef Server.

• Ubuntu 8.04+
• Debian 5.0+
• CentOS 5.3+
• Red Hat 5.3+
• Fedora 10+
• OpenBSD 4.6+
• FreeBSD 7.1+
• Gentoo 1.12.11.1+

You Must Have a Fully Qualified Domain Name

Chef and the Opscode Cookbooks make heavy use of fully qualified domain names. In particular, for the Chef Server's hostname in URLs, and for clients' default node names when authenticating. You should verify that you have a fully qualified domain name set, even if it is "hostname".localdomain. You can check if an FQDN is set with the hostname command, or with Ohai (2).

Attribute domain is not defined! (ArgumentError)

If you're getting this error message, it's because you don't have the FQDN set on your host.

Install Ruby

Ruby 1.8.6, 1.8.7, 1.9.1 or 1.9.2 with SSL bindings and development tools to build RubyGems with native extensions is required. You will need to install the appropriate packages for your operating system.

On Debian and Ubuntu

(We need wget as well for the next step)

On Red Hat and CentOS

Enable EPEL repository:

Enable ELFF repository to get Ruby 1.8.6.

(Modify the release to match your local system for EPEL and ELFF)

Install Ruby and development tools:

Install RubyGems from Source

We prefer to install RubyGems from source rather than use the OS-provided version (if any), as it is cross platform, so we know what to expect.

Install Chef Gem

Now we'll install the Chef RubyGem. This also installs Chef's dependencies.

Chef Solo Configuration

You need to give chef-solo a minimal configuration before it can run the bootstrap recipes. You need to configure two parts: chef-solo's own configuration file (/etc/chef/solo.rb by default) tells chef-solo where to store its files, and a JSON attributes file gives chef-solo the values it uses to configure your Chef Server.

Chef Solo Configuration File: solo.rb

We're going to use Chef Solo to run the bootstrap recipes, so it needs to be configured to point the right locations. The following configuration file will be used on both Clients and Servers. Save it as /etc/chef/solo.rb.

Chef Solo Attributes Configuration: chef.json

Chef can use JSON data passed to Solo or the Client to specify a certain list of recipes to run and specific Attributes to configure on the system. We're going to configure the node with a JSON file particular to whether it will be a Chef Server or a Chef Client. Create the file ~/chef.json with the applicable contents below.

Chef Server with no webui:

Chef Server with the webui installed and enabled:

Chef Clients connecting to the server.

There are a lot of other attributes available to configure for the Chef Server and Chef Clients. See the Chef Cookbook README for complete details.

Bootstrap Chef Server

This procedure will set up the chef-server to run the chef-server-api Merb slice on port 4000 using the thin adapter, and optionally the chef-server-webui on port 4040. SSL encryption can be provided by proxying with Apache.

The webui is now separate from the API, so it is now optional. Setting the attribute webui_enabled to true will install and configure it.

Run chef-solo

If you would like to use a different version of the bootstrap cookbook, substitute the version number for "latest", e.g. bootstrap-0.9.8.tar.gz.

This command will bring up the Chef Server by doing the following:

• Bootstrap the system as a Client (see section below for what this entails).
• Install RabbitMQ if possible (see below).
• Install CouchDB if possible (see below).
• Install development libraries zlib and xml, for chef-solr.
• Install the chef-server, chef-server-api, chef-solr gems.
• Optionally (if webui_enabled) install chef-server-webui gem.
• Create the server configuration file, /etc/chef/server.rb.
• Create some directories the server needs.
• If init_style is "runit", set up chef-solr-indexer, chef-solr, chef-server (API) as runit services. If webui_enabled, it chef-server-webui will be added as a runit service as well. If "init", copy the init scripts for these services from the installed Chef gem for the current platform (Debian and Red Hat families supported). If "bsd", display a hint about startup commands. Otherwise, display a message about manual setup.

The services configured here will be running:

For RHEL/CentOS Systems

Some manual steps are required to complete the installation:

Verify That All Components are Running

Now that you have Chef Server installed, you should have the following processes running.

Configure the Command Line Client

Once you've verified that all of Chef's components are working, it's time to configure the knife command line tool. On your Chef Server, run knife configure -i to interactively configure your knife client and create an admin account on the server. You can accept the default responses by pressing <enter>.

A client is like a user, except it has a RSA private key instead of a password. What you're picking here is the username for the client you're creating:

knife configure -i has to use an existing admin client's credentials to create your account. On a brand new server, the Web UI is the only admin client. So just use the defaults here:

The "chef-validator" client is a special account used to auto-register new nodes. The defaults should be fine here.

Verify Your Knife Client Configuration

You can now run some basic knife commands to verify that you can communicate with the server:

Create a Knife Client for Your Laptop/Desktop

Create Your Client Account

When working with chef, you will spend a lot of time editing recipes and other files, and you'll find it much more convenient to edit them on your laptop/desktop, where you have your editor configured just to your liking. To facilitate this mode of working, we recommend you create a knife client to use knife on your development machine.

Make sure you've configured knife on your chef server as described above before proceeding with this step.

This command creates the client and writes its private key to /tmp/my-username.pem. To verify the operation, use the knife client show command:

Copy Your Key and Configure Knife

Now you need to copy the key you just created to your development machine using scp (or some other file copy mechanism).

In order to use knife on your laptop, you'll need to install the chef-client. If your laptop's OS comes with rubygems (Mac OS X, for example) you can run sudo gem install chef; otherwise, check out the client installation instructions for your OS. Once you have chef installed, you can use knife's interactive configuration on your laptop (note we're not using the -i option here):

Knife looks for its configuration in HOME/.chef/knife.rb by default:

Now, enter your client name, exactly as you did when running knife client create above:

For these next settings, you can accept the defaults for now and update them later by editing your knife.rb file. The validation client name and key are used with knife's cloud computing commands:

We'll also leave the path to the chef repository blank for now. After you've created a chef repository, you'll want to configure it by editing knife.rb

Verify Your Configuration

You can run some list and show commands to verify everything is working:

Next Steps

Now that you have a working Chef installation, it's time to start configuring your infrastructure:

• Read up on Chef's concepts and terminology
• Get a repository to organize your work
• Learn how to write cookbooks