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

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

These are the main assets you'll use:

* `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)
* `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').

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

* `knife/`        - Chef and cloud configuration and their myriad attendant credential files.
* `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.

## Directory setup

We recommend you set up your 

    /path/to/{organization}-chefrepo
    │  
    ├── clusters
    │   └── { actual clusters }
    │  
    ├── roles
    │   ├── { roles }
    │   └── { symlinks into vendor/ironfan/roles }
    │  
    ├── site-cookbooks                  - directories holding internal cookbooks
    │   └── users
    │  
    ├── cookbooks                       - symlinks to externally maintained cookbooks
    │   ├── @vendor/opscode/...
    │   └── @vendor/ironfan/...
    │  
    ├── vendor
    │   ├── opscode
    │   │   └── cookbooks               - git submodule of https://github.com/opscode/cookbooks
    │   │  
    │   └── ironfan                - git submodule of https://github.com/infochimps-labs/ironfan
    │       ├── site-cookbooks          - systems:     hadoop, cassandra, provides_service, etc.
    │       ├── integration-cookbooks   - integration: connects systems together
    │       ├── meta-cookbooks          - utilities:   provides_service, system_params, can_haz
    │       │  
    │       ├── roles
    │       │  
    │       └── examples
    │           ├── clusters            - example clusters
    │           └── roles               - roles that go with the example clusters
    │  
    ├── certificates
    ├── config
    ├── data_bags
    └── environments

## Knife dir setup

    ~/.chef
    │  
    ├── knife.rb
    ├── knife-user-{user}.rb            - your user-specific knife customizations
    ├── {user}.pem                      - your chef client key
    ├── {organization}-validator.pem    - chef validator key, used to create client keys
    ├── {organization}-credentials.rb   - secret credentials: aws_secret_access_key, etc. Do not version.
    ├── {organization}-cloud.rb      .  - cloud assets: elastic IPs, AMI image ids, etc
    ├── {organization}-keypairs
    │   ├── bonobo.pem
    │   ├── gibbon.pem
    │   ├── client-bonobo-worker-0.pem
    │   └── client-bonobo-worker-0.pem
    └── .gitignore                      - make sure not to version the secret/user-specific stuff (*-keypairs, *-credentials.rb, knife-user-*.rb)

For example, I am user `mrflip` and my organization is `infochimps`, so my tree looks like:

    knife_dir
    │  
    ├── knife.rb
    ├── knife-user-mrflip.rb            
    ├── mrflip.pem                      
    ├── infochimps-validator.pem    
    ├── infochimps-credentials.rb   
    ├── infochimps-cloud.rb      .  
    ├── infochimps-keypairs
    │   ├── bonobo.pem
    │   ├── gibbon.pem
    │   ├── client-bonobo-master-0.pem
    │   └── client-bonobo-worker-1.pem
    └── .gitignore