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
|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.
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.
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.
Once RabbitMQ is installed, you'll need to set up the queue. The following commands assume v1.6+ syntax.
|Commands Run as Root|
Commands that require root privileges are run with
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:
This varies by platform.
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 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
If you would like to be able to download source packages, add an additional identical line, but change
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.
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
Optionally install the WebUI.
Configure Chef Server
The server configuration file is
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
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
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
First, create the ~/.chef directory and copy the required certificates created by the server.
Next run the
API Client creation must use an existing admin client's credentials to create the new account. On a brand new server, the
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.
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
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
Knife looks for its configuration in
Now, enter your client name, exactly as you did when running
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
You're now ready to use Knife Bootstrap to automatically set up systems to become new Chef Clients to the server.