Develop New Cookbooks

If you are creating new cookbooks that contain new Chef resources such as LWRPs, cookbooks, recipes, etc. that are currently not available in the other repositories, you should create a new repository from scratch. 

1. Create a new cookbook repository. Do not create the repository by forking an existing one. See the Intermediate 1 Chef Tutorial for details.
2. Clone and rename the ServerTemplate that you want to customize so that it can use resources defined in the new repository.
3. Clone and rename the ServerTemplate's RepoPath object.
4. Modify the custom (cloned) RepoPath object by adding a reference to each cookbook repository that you want to make available in your custom (cloned) ServerTemplate. (e.g. git://github.com/username/my_cookbooks.git) See Add a Repository to a RepoPath.
5. Under the new RepoPath's Cookbook Repos tab, drag-and-drop any custom repositories to the top of the list so that they take precedence over any of the cookbook repositories listed below. For example, your company might have a repository of generic cookbooks that can be used company-wide across all Chef projects while each development team may have a unique set of cookbooks that are specific to their project/application. In such cases, each application might have its own RepoPath object.
   
6. Go to the custom (cloned) ServerTemplate's Repos tab. Select the custom (cloned) RepoPath that you just created. Wait for the referenced repositories to be 100% completed before going to the next step. 
7. Go to the custom ServerTemplate's Scripts tab and add the new Chef recipes from the custom repository. Provide values for any required inputs.
8. Launch a test server and test your modifications to ensure that the correct configuration settings were applied.

Cookbook Overrides

If you only want to override a few files such as default settings of a Chef resource or modify a configuration file, it's recommended that you create a new repository where its contents only override the select file(s) that you want to modify. In the example diagram below, the contents within the C and D cookbooks of the repository of overrides (e.g. git://github.com/username/overrides.git) will take precendence over the contents of the C and D cookbooks located in the other repositories.

Important! The C and D cookbooks in the repository of overrides should only contain the files that will be overwritten in the other repositories. Paths must be respected, so a file must exist in the same directory as the file its going to override. Any unmodified files in the C and D cookbooks will still be retrieved from the original repositories.

In the example above, perhaps you want to modify the MySQL tuning parameters. By default, RightScale defines the MySQL tuning parameters in the 'my.cnf.erb' file by using values that are calculated based on an algorithm in the 'mysql_tuning.rb' file.

However, after testing your applications, you may want to hardcode certain MySQL tuning parameters instead of using RightScale's algorithm or maybe add additional MySQL tuning parameters that are not included by default. In such cases, you may want to override RightScale's 'my.cnf.erb' file with your own file that has optimized tuning parameters for your application.

In the example above, the modified version of the 'my.cnf.erb' file in your repository of overrides will be used instead of the file with the same name in RightScale's repository. It's important to always maintain the same file path location to ensure that you are going to override the correct file. The metadata files are also required to be present so that the cookbook's contents are properly retrieved from Repose and its contents will be listed in the RightScale Dashboard. Although the README.rdoc is technically not required, it is typically referenced in the header of the metadata, so if it's missing you will get an error. The metadata in the overrides cookbook only needs to contain information about any new inputs, recipes, etc. In the simple example above where no input is being introduced, the metadata would only need to include a basic header. 

Example (metadata.rb)

It's strongly recommended that you edit the header to include relevant information about yourself or your company as well as a comment about what files are being overwritten.

maintainer       "YOUR_COMPANY_NAME"
maintainer_email "YOUR_EMAIL"
license          "All rights reserved"
description      "Installs/Configures splunk"
long_description IO.read(File.join(File.dirname(__FILE__), 'README.md'))
version          "0.0.1"

# Includes a cookbook override for the 'templates/default/my.cnf.erb' file

Example (directory structure)

In the example above, the overrides repository would have the following directory structure.

/cookbooks/db_mysql/templates/default/my.cnf.erb

/cookbooks/db_mysql/metadata.rb

/cookbooks/db_mysql/metadata.json

/cookbooks/db_mysql/README.md

You can either create your own "overrides" cookbook from scratch or use RightScale's 'cookbooks_override' repository if you want to override some of the common configuration files used in many or RightScale's published LTS and Infinity ServerTemplates.

Contribute Bug Fixes or Enhancements

If you need to make a change to an existing cookbook repository such as a minor bug fix or enhancement that you may want to contribute back to the owner of the original repository via a Pull Request, add the changes to a fork of the repository, which will make it easier for the owner of the original repository to merge the submitted changes into the master branch. See Make a Pull Request on GitHub.

1. Fork the repository that you're going to modify. See Fork a Cookbook Repository.
2. Create a development branch on the forked repository using the release SHA of the published repository. Do not add changes to the "master" branch because they are more difficult to merge into the original repository when you make a Pull Request.
3. In the development branch, edit the file(s) that you want to modify. Add, commit, and push the changes to your forked repository. 
4. Clone and rename the ServerTemplate that you want to customize.
5. Clone and rename the ServerTemplate's RepoPath object.
6. Modify the custom (cloned) RepoPath object by adding a reference to your forked cookbook repository that you want to make available in your custom (cloned) ServerTemplate. See Add a Repository to a RepoPath.
7. Under the RepoPath's Cookbook Repos tab, replace the reference to the original repository (that you forked from) with the reference to the new forked repository. Place the forked repository before/after the repository it's going to replace before deleting the original one so that you maintain the cookbook repository hierarchy.
   
8. Go to the custom (cloned) ServerTemplate's Repos tab. Select the custom (cloned) RepoPath that you just created. Wait for the referenced repositories to be 100% completed before going to the next step. 
9. Go to the custom ServerTemplate's Scripts tab and add the new Chef recipes from the custom repository. Provide values for any required inputs.
10. Launch a test server and test your modifications to ensure that the correct configuration settings were applied.
11. When you are ready to submit your changes to the original repository, you can make a Pull Request. See Make a Pull Request on GitHub.