Ironfan Homebase Layout
=======================

Your Chef Homebase contains several directories, and each contains a README.md file describing its purpose and use in greater detail.

This directory structure came out of a *lot* of trial and error, and is working very well where many others didn't. This homebase makes it easy to pull in third-party pantries (cookbook collections) and track upstream changes without being locked in.

## Main Directories

The main assets you'll use are:

* `clusters/`   - Clusters fully describe your machines, from its construction ('an 8-core machine on the Amazon EC2 cloud') to its roles ('install Cassandra, Ganglia for monitoring, and silverware to manage its logs and firewall').
* `cookbooks/`  - Cookbooks you download or create. Cookbooks install components, for example `cassandra` or `java`.
* `roles/`      - Roles organize cookbooks and attribute overrides to describe the specific composition of your system. For example, you install Cassandra attaching the `cassandra_server` role to your machine. (.rb or .json files)

These folders hold supporting files. You're less likely to visit here regularly.

* `knife/`        - Chef and cloud configuration, and their myriad attendant credentials.
* `environments/` - Organization-wide attribute values. (.json or .rb files)
* `data_bags/`    - Data bags are an occasionally-useful alternative to node metadata for distributing information to your machines. (.json files)
* `certificates/` - SSL certificates generated by `rake ssl_cert` live here.
* `tasks/`        - Rake tasks for common administrative tasks.
* `vendor/`       - cookbooks are checked out to `vendor`; symlinks in the `cookbooks/` directory select which ones will be deployed to chef server. The vendor directory comes with the Ironfan, Opscode and (should you be a lucky customer) Ironfan Enterprise chef pantries.
* `notes/`        - a submoduled copy of the [ironfan wiki](http://github.com/infochimps-labs/ironfan/wiki`

## Directory setup

The core structure of the homebase is as follows ("├─*" means "git submodule'd"):

    homebase
    ├── clusters                        - cluster definition files
    │   └── ( clusters )
    ├── cookbooks                       - symlinks to cookbooks
    │   ├── @vendor/ironfan-pantry/cookbooks/...
    │   ├── @vendor/opscode/cookbooks/...
    │   └── @vendor/org-pantry/cookbooks/...
    ├── environments                    - environment definition files
    │   └── ( environments )
    ├── data_bags                       - symlinks to data_bags
    │   ├── @vendor/ironfan-pantry/roles/...
    │   └── @vendor/org-pantry/roles/...
    ├── roles                           - symlinks to roles
    │   ├── @vendor/ironfan-pantry/roles/...
    │   └── @vendor/org-pantry/roles/...
    ├── vendor
    │   ├─* ironfan-pantry              - git submodule of https://github.com/infochimps-labs/ironfan-pantry
    │   │   ├── cookbooks
    │   │   ├── data_bags
    │   │   ├── roles
    │   │   └── tasks
    │   ├─* ironfan-enterprise          - git submodule of ironfan-enterprise, if you're a lucky customer
    │   │   ├── cookbooks
    │   │   ├── data_bags
    │   │   ├── roles
    │   │   └── tasks
    │   ├── opscode
    │   │   └─* cookbooks               - git submodule of https://github.com/infochimps-labs/opscode_cookbooks; itself a closely-tracked fork of https://github.com/opscode/cookbooks
    │   └── org-pantry                  - organization specific roles, cookbooks, etc.
    │       ├── cookbooks
    │       ├── data_bags
    │       ├── roles
    │       └── tasks
    ├── knife                           - credentials (see below)
    ├── certificates
    ├── config
    ├─* notes
    ├── tasks
    └── vagrants                        - vagrant files (when using ironfan-ci)

The `vendor/opscode/cookbooks` and `vendor/ironfan-pantry` directories are actually [git submodules](http://help.github.com/submodules/). This makes it easy to track upstream changes in each collection while still maintaining your own modifications.

We recommend you place your cookbooks in `vendor/org-pantry`. If you have cookbooks &c from other pantries that have significant changes, you can duplicate it into this `vendor/org-pantry` and simply change the symlink in homebase/cookbooks/.

## Knife dir setup

We recommend you version your credentials directory separately from your homebase. You will want to place it under version control, but you should not place it into a central git repository -- this holds the keys to the kingdom.

We exclude the chef user key (`(user).pem`) and user-specific knife settings (`knife-user-(user).rb`) from the repo as well. Each user has their own revokable client key, and their own cloud credentials set, and those live nowhere but their own computers.

    knife/
    ├── knife.rb
    ├── credentials -> (organization)-credentials
    ├── (organization)-credentials
    │   ├── knife-org.rb                - org-specific stuff, and cloud assets (elastic IPs, AMI image ids, etc)
    │   ├── (user).pem                  - your chef client key *GITIGNORED*
    │   ├── knife-user-(user).rb        - your user-specific knife customizations *GITIGNORED*
    │   ├── (organization)-validator.pem- chef validator key, used to create client keys
    │   ├── client_keys
    │   │   └── (transient client keys) - you can delete these at will; only useful if you're debugging a bad bootstrap
    │   ├── ec2_keys
    │   │   └── (transient client keys) - ssh keys for cloud machines (in EC2 parlance, the private half of your keypair)
    │   ├── certificates
    │   ├── data_bag_keys
    │   └── ec2_certs
    ├── bootstrap                       - knife cluster bootstrap scripts
    ├── plugins
    │   └── knife
    │       └── (knife plugins)         - knife plugins
    └── .gitignore                      - make sure not to version the secret/user-specific stuff (*-keypairs, *-credentials.rb, knife-user-*.rb)

    
(You can safely ignore the directories above that aren't annotated; they're useful in certain advanced contexts but not immediately)