First of all, every Chef installation needs a Chef Homebase. Chef Homebase is the place where cookbooks, roles, config files and other artifacts for managing systems with Chef will live. Store this homebase in a version control system such as Git and treat it like source code.

### Conventions

In all of the below,

* `{homebase}`: is the directory that holds your Chef cookbooks, roles and so forth. For example, this file is in `{homebase}/README.md`.

* `{username}`: identifies your personal Chef client name: the thing you use to log into the Chef WebUI.

* `{organization}`: identifies the credentials set and cloud settings to use.  If your Chef server is on the Opscode platform (Try it! It's super-easy), use your organization name (the last segment of your chef_server url). If not, use an identifier you deem sensible.

Ironfan Installation Instructions
============

_Before you begin, fork the repo as you'll be making changes to personalize it for your platform._

1. Clone the repo. It will produce the directory we will call `homebase` from now on:

        git clone https://github.com/infochimps-labs/ironfan-homebase homebase
        cd homebase
        git submodule foreach git checkout master
        git submodule update --init

2. Install the Ironfan gem (you may need to use `sudo`):

        gem install ironfan

3. Set up your [knife.rb](http://wiki.opscode.com/display/chef/Knife#Knife-ConfiguringYourSystemForKnife) file.

  

Go to the [Knife Plugins](http://wiki.opscode.com/display/chef/Knife+Plugins) in the Chef Wiki for additional information.


__________________________________________________________________________


Installing the [knife.rb](http://wiki.opscode.com/display/chef/Knife#Knife-ConfiguringYourSystemForKnife) file when using Ironfan has proven exceedingly useful -- it leaves you in good shape to avoid problems with credential management, importing 3rd-party cookbooks, and other things down the road.

## <a name="knife-configuration" />Standard Knife Configuration

### Set up 

_Note_: If your local username differs from your Opscode Chef username, then you should `export CHEF_USER={username}` using your Opscode username (e.g. from your .bashrc) before you run any knife commands.

1. So that Knife finds its configuration files, symlink the `{homebase}/knife` directory (the one holding this file) to be your `~/.chef` folder.

        cd {homebase} 
        ln -sni $CHEF_HOMEBASE/knife ~/.chef

**HEY @MRFLIP MAKE SURE THAT THIS WORKS WITHOUT THE CHEF HOMEBASE VARIABLE SET**

### <a name="credentials" />Credentials

All the keys and settings specific to your organization are held in a directory named `credentials/`, versioned and distributed independently of the homebase. 

To set up your credentials directory, visit `{homebase}/knife` and duplicate the example, naming it `credentials`:

        cd $CHEF_HOMEBASE/knife 
        rm credentials
        cp -a example-credentials credentials
        cd credentials
        git init ; git add .
        git commit -m "New credentials universe for $CHEF_ORGANIZATION" .
        
### User / Cloud config

Edit the following places in your new `credentials`:

* Organization-specific settings are in `knife/{organization}-credentials/knife-org.rb`:
  - _organization_:             Your organization name 
  - _chef server url_:          Edit the lines for your `chef_server_url` and `validator`. 

If you are an Opscode platform user, you can skip this step -- your `chef_server_url` defaults to `https://api.opscode.com/organizations/#{organization}` and your validator to `{organization}-validator.pem`.
  
- Cloud-specific settings, if you are targeting a cloud provider, add account information and configuration here. 

* User-specific settings are in `knife/credentials/knife-user-{username}.rb`. (You can duplicate and rename the one in `knife/example-credentials/knife-user-example.rb`)
  - for example, if you're using Amazon EC2 you should set your access keys:

          Chef::Config.knife[:aws_access_key_id]      = "XXXX"
          Chef::Config.knife[:aws_secret_access_key]  = "XXXX"
          Chef::Config.knife[:aws_account_id]         = "XXXX"
        
* Chef user key is in `{credentials_path}/{username}.pem`

* Organization validator key in `{credentials_path}/{organization}-validator.pem`

* If you have existing Amazon machines, place their keypairs in `{credentials_path}/ec2_keys` 

__________________________________________________________________________

## Try it out

You should now be able to use Knife.

        $ knife client list
        chef-webui
        cocina-chef_server-0
        cocina-sandbox-0
        cocina-validator

        $ knife cluster list
        +--------------------+---------------------------------------------------+ 
        | cluster            | path                                              |
        +--------------------+---------------------------------------------------+
        | burninator         | /cloud/clusters/burninator.rb                     |
        | el_ridiculoso      | /cloud/clusters/el_ridiculoso.rb                  |
        | elasticsearch_demo | /cloud/clusters/elasticsearch_demo.rb             |
        | hadoop_demo        | /cloud/clusters/hadoop_demo.rb                    |
        | sandbox            | /cloud/clusters/sandbox.rb                        |
        +--------------------+---------------------------------------------------+

Launching a cluster in the cloud should now be this easy!

        knife cluster launch sandbox:simple --bootstrap
__________________________________________________________________________

**SYAFLAG: Not sure where the stuff below, before getting to Next is supposed to go.  Here?**

To get started with Knife and Chef, follow the [Chef Fast Start Guide](http://wiki.opscode.com/display/chef/Fast+Start+Guide). We use the hosted Chef service and are happy, we are sure you'll be happy with it too (there are instructions in the wiki to set up a Chef server, if that's what you prefer). Stop when you get to "Bootstrap the Ubuntu system" -- Ironfan makes that much easier. **SYAFLAG: "Bootstrap the Ubuntu System is the 1st step in the EC2 Bootstrap Fast Start Guide, so should we include EC2 Bootstrap Fast Start Guide?**

* [Launch Cloud Instances with Knife](http://wiki.opscode.com/display/chef/Launch+Cloud+Instances+with+Knife)
* [EC2 Bootstrap Fast Start Guide](http://wiki.opscode.com/display/chef/EC2+Bootstrap+Fast+Start+Guide) (**Wow, we do everything in that page in _one_ command.**)


### Next

The README file in each of the subdirectories for more information about what goes in those directories. If you are bored of reading, go customize one of the files in the 'clusters/ directory'. Or, if you're a fan of ridiculous things and have ever pondered how many things you can fit in one box, launch el_[ridiculoso:](http://www.spanishdict.com/translate/ridiculoso). It contains every single recipe we have ever made stacked on top of one another. 

        knife cluster launch el_ridiculoso-gordo --bootstrap


For more information about configuring Knife, see the [Knife documentation](http://wiki.opscode.com/display/chef/knife).