This page describes how to manually set up a Chef Server. This is the only option if your platform does not have native Chef packages and your platform is not supported by the RubyGem installation bootstrap.

These procedures will assume installation of Chef is done with RubyGems, and commands are executed as root through sudo. If your system does not have sudo installed, we recommend it. Otherwise, login as root and run the command w/o sudo.

These instructions are deprecated This directions are only for Chef 10. If you want to install the Chef 11 or newer, go to the Chef Download Page.

Install Ruby and Chef

Chef-server is written in Ruby. Per Operating System directions for installing Ruby and Chef can be found at Installing Chef Client and Chef Solo.

Install CouchDB

Chef requires CouchDB version 0.9.1 or higher. If CouchDB 0.9.1+ is not available as a package on your platform, you'll need to install it from source. You may also need to install Erlang from source. See the CouchDB installation instructions for more information.

Once CouchDB is installed, you'll need to start it. If you installed it from a package for your platform, this might be done automatically. If you installed from source, check the source tarball for init scripts or instructions for your platform. You shouldn't need any other special configuration—Chef Server will create its database when it starts for the first time.

Install RabbitMQ

The Chef Indexer sends messages across an AMQP queue to get them indexed for search. We use RabbitMQ for this. You'll need to download and install RabbitMQ as appropriate for your platform, see their site.

Once RabbitMQ is installed, make sure the service is running.

Configure RabbitMQ

Once RabbitMQ is installed, you'll need to set up the queue. The following commands assume v1.6+ syntax.

Install Java

Chef 0.8.0+ uses SOLR for the search engine. You need to install Java for your platform. This is packaged for most common Linux distributions but may not be in the default repositories. For example, enable on Debian or Ubuntu:

• Debian: non-free
• Ubuntu: multiverse

This varies by platform.

OpenJDK May Work too! Some Linux distributions include OpenJDK, which may work for SOLR as well, but isn't as widely tested.

Install zlib and libxml

The SOLR search engine used in Chef 0.8.0+ also requires zlib and libxml. Make sure to install the development headers for these libraries on your system.

Install gecode

Install Using Deb Package

On Ubuntu lucid, maverick, or Debian lenny release, you can install gecode deb package from the Opscode APT repository.

Add the Opscode APT Repository

Create /etc/apt/sources.list.d/opscode.list.

If you would like to be able to download source packages, add an additional identical line, but change deb to deb-src line.

You can copy and paste these examples to create the necessary sources.list entry:

Debian users will likely need to run 'apt-get install sudo wget lsb-release' as root before pasting the examples.

Add the GPG Key and Update Index

Before you install the packages, make sure you add the Opscode GPG key to apt.

Issues downloading from gnupg.net? If you get an error when trying to download the key that states that the "keyserver timed out", try downloading the key directly from our apt repository instead: Afterwards you'll also want to run this command again:

Now, we update apt-get with the newly added Opscode repository:

Installing the opscode-keyring package will keep the key up-to-date:

Upgrade Existing Packages

To ensure you are using the latest versions of libraries that chef depends on, you may wish to update your existing packages:

Install deb package

Build and Install from Source

Install Chef Server

Install the chef-server gems.

Optionally install the WebUI.

Configure Chef Server

The server configuration file is /etc/chef/server.rb, and is what the chef-indexer will use by default as well. Here's a sample to get you started.

Replace chef.example.com with the proper FQDN for the server. Feel free to change the paths to fit your environment or your platform's preferences (for example, FHS on Linux).

The web_ui_admin_user_name and web_ui_admin_default_password settings are optional, the default admin user is 'admin', and the webui will instruct you how to change the password when you log in.

Start Chef Indexer

Again, we recommend runit for this, but if runit is not available for your platform or you're using init scripts or a different init scheme, you'll need to set it up to start at boot time. To get up and running quickly for testing, you can simply run the indexer program.

This runs as root to write to the file location specified by search_index_path.

Using chef 0.10.0 or greater? Since Chef 0.10.0, indexer has been replaced with chef-expander (http://www.opscode.com/blog/2011/05/02/chef-0-10-0-released/).

Start Chef SOLR Server

Next we need to start the SOLR search engine. You'll want to configure this as a service that starts at boot time for your system (runit, init script, etc).

Start Chef Server

To get running immediately, run the chef-server command. See above spiel for system startup methods.

The chef-server API and webui are separate, and the webui is optional. Set these up as system services like the others. By default these use the 'thin' web server adapter for merb.

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 shown in brackets by pressing <enter>.

First, create the ~/.chef directory and copy the required certificates created by the server.

Certificates Read Only Presumably you're running this as a normal non-privileged user. When the chef-server-api starts, it creates the validation and webui certificates as read/write only by the user that starts the process (chef).

Next run the knife configure command, and pass the -i flag so the initial client that will be used to authenticate with the API.

API Client creation must use an existing admin client's credentials to create the new account. On a brand new server, the chef-webui is created by chef-server-api startup. Use the default for the clientname, and specify the webui.pem copied above.

The "chef-validator" client is a special account used to auto-register new nodes. Use the default clientname, and specify the validation.pem copied above.

Finally, specify a location for the Chef Repository. This is used to configure knife to point to the directory where Cookbooks will be stored.

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 (your management workstation), 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:

You're now ready to use Knife Bootstrap to automatically set up systems to become new Chef Clients to the server.

Next?

You'll probably want to set up a Chef Repository for your configuration, or learn How to Proxy Chef Server with Apache, and then go to Cooking School.

Installation

Installing Chef Client and Chef Solo