Customizing Your Environment Using Overlay Chef Recipes

Under the V5 stack, it is possible to override how our chef recipe works by writing an overlay recipe. The overlay recipe can override part, or all, of our main chef recipes under the cookbooks directory. In the overlay recipe, you only need to include the parts of the main recipe that you will override; parts that will not be changed can be excluded from the overlay recipe.

Example

Let's illustrate this with an example. Our passenger5 recipe installs version 5.0.29 by default. Let's say you want to run the latest version, which is 5.1.5 as of this writing.

The version that will be installed by our passenger5 recipe is set in cookbooks/passenger5/attributes/passenger5.rb. To override that part of the passenger5 recipe, just add an empty passenger5 recipe with the overriden attributes/passenger5.rb file.

Your overlay passenger5 recipe will look like this:

- passenger5
  +- attributes/passenger5.rb

attributes/passenger5.rb will look like the original attributes/passenger5.rb file, with your changes added in:

default['passenger5']['version'] = '5.1.5'
default['passenger5']['port'] = "8000"

NOTE: Even if you're only modifying the line specifying the version, you need to include the whole file, otherwise you may run into chef errors. In this example, if you omit the line default['passenger5']['port'] = "8000", then default['passenger5']['port'] will be uninitialized and that will result in a chef error.

During the chef run, your passenger5/attributes/passenger5.rb recipe will be overlaid with the rest of our passenger5 recipe.

NOTE: You do not need to add the overlaid recipe to ey-custom/recipes/after-main.rb.

Experimenting with changes

If you have a running instance and you just want to experiment with chef changes on just that instance, you can directly edit the chef recipes in /etc/chef/recipes/cookbooks and then run chef with sudo PATH=/usr/local/ey_resin/bin:$PATH /home/ey/bin/chef-solo -j /etc/chef/dna.json -c /etc/chef/solo.rb. This will be slightly faster than doing an ey-core recipes upload --apply because it skips uploading your recipes to S3 and then downloading the recipes from S3 to the instance.

Common Customizations

Below is a partial list of common customizations you can perform using overlay recipes.

• Nginx version
• OpenSSL version
• Passenger version
• php.ini
• sshd_config
• Yarn version

Set the Nginx version

Edit cookbooks/nginx/attributes/default.rb:

default['nginx']['version'] = '1.12.1'

https://github.com/engineyard/ey-cookbooks-stable-v5/blob/next-release/cookbooks/nginx/attributes/default.rb#L3

To see the list of available versions, ssh to an instance and run eix www-servers/nginx.

Set the OpenSSL version

Edit cookbooks/openssl/attributes/openssl.rb:

default.openssl.using_metadata = !!node.engineyard.metadata("openssl_ebuild_version",nil)
default.openssl.version = node.engineyard.metadata('openssl_ebuild_version','1.0.2j')

https://github.com/engineyard/ey-cookbooks-stable-v5/blob/next-release/cookbooks/openssl/attributes/openssl.rb#L2

To see the list of available versions, ssh to an instance and run eix dev-libs/openssl.

Set the Passenger version

Edit cookbooks/passenger5/attributes/passenger5.rb:

default['passenger5']['version'] = '5.0.29'
default['passenger5']['port'] = "8000"

https://github.com/engineyard/ey-cookbooks-stable-v5/blob/next-release/cookbooks/passenger5/attributes/passenger5.rb#L1

NOTE: Our chef recipes do not restart Passenger, as doing this in a chef run can result in a simultaneous restart across all application instances, causing downtime. However, a restart is needed to run the newer Passenger version. To restart Passenger, please run sudo monit restart passenger_APPNAME_8000 on all app instances. We recommend doing this on a staggered basis to avoid downtime.

Override php.ini

Edit cookbooks/php/files/default/php.ini. You can get the default php.ini from https://raw.githubusercontent.com/engineyard/ey-cookbooks-stable-v5/next-release/cookbooks/php/files/default/php.ini)

After the chef run, you will need to run sudo monit restart php-fpm on all application instances to have PHP-FPM load the new values in php.ini.

Override sshd_config

Edit cookbooks/ey-monitor/files/default/sshd_config. You can get the default sshd_config from https://raw.githubusercontent.com/engineyard/ey-cookbooks-stable-v5/next-release/cookbooks/ey-monitor/files/default/sshd_config.

Set version of Yarn to be installed

• Edit cookbooks/node/attributes/yarn.rb to reflect the version you want, for example '1.2.1'.
• Copy cookbooks/node/files/default/yarn-0.21.3.ebuild to cookbooks/node/files/default/yarn-<your_version>.ebuild
• Edit cookbooks/node/files/default/yarn-1.2.0.ebuild and change S="${WORKDIR}/dist" to be S="${WORKDIR}/yarn-v${PV}"