Skip to content

Latest commit

 

History

History
1094 lines (890 loc) · 29.6 KB

README.md

File metadata and controls

1094 lines (890 loc) · 29.6 KB
Raw

rbenv Chef Cookbook

Build Status

Description

Manages rbenv and its installed Rubies. Several lightweight resources and providers (LWRPs) are also defined.

Usage

rbenv Installed System-Wide with Rubies

Most likely, this is the typical case. Include recipe[rbenv::system] in your run_list and override the defaults you want changed. See below for more details.

If your platform is the Mac, you may need to modify your profile.

rbenv Installed For A Specific User with Rubies

If you want a per-user install (like on a Mac/Linux workstation for development, CI, etc.), include recipe[rbenv::user] in your run_list and add a user hash to the user_installs attribute list. For example:

node.default['rbenv']['user_installs'] = [
  { 'user'    => 'tflowers',
    'rubies'  => ['1.9.3-p0', 'jruby-1.6.5'],
    'global'  => '1.9.3-p0',
    'gems'    => {
      '1.9.3-p0'    => [
        { 'name'    => 'bundler',
          'version' => '1.1.rc.5'
        },
        { 'name'    => 'rake' }
      ],
      'jruby-1.6.5' => [
        { 'name'    => 'rest-client' }
      ]
    }
  }
]

See below for more details.

rbenv Installed System-Wide and LWRPs Defined

If you want to manage your own rbenv environment with the provided LWRPs, then include recipe[rbenv::system_install] in your run_list to prevent a default rbenv Ruby being installed. See the Resources and Providers section for more details.

If your platform is the Mac, you may need to modify your profile.

rbenv Installed For A Specific User and LWRPs Defined

If you want to manage your own rbenv environment for users with the provided LWRPs, then include recipe[rbenv::user_install] in your run_list and add a user hash to the user_installs attribute list. For example:

node.default['rbenv']['user_installs'] = [
  { 'user' => 'tflowers' }
]

See the Resources and Providers section for more details.

Ultra-Minimal Access To LWRPs

Simply include recipe[rbenv] in your run_list and the LWRPs will be available to use in other cookbooks. See the Resources and Providers section for more details.

Other Use Cases

  • If node is running in a Vagrant VM, then including recipe[rbenv::vagrant] in your run_list can help with resolving the chef-solo binary on subsequent

Requirements

Chef

Tested on 11.4.4 but newer and older version should work just fine. File an issue if this isn't the case.

Platform

The following platforms have been tested with this cookbook, meaning that the recipes and LWRPs run on these platforms without error:

  • ubuntu (10.04/12.04)
  • debian (6.0)
  • freebsd
  • redhat
  • centos
  • fedora
  • amazon
  • scientific
  • suse
  • mac_os_x
  • gentoo

Please report any additional platforms so they can be added.

Cookbooks

There are no external cookbook dependencies. However, if you want to manage Ruby installations or use the rbenv_ruby LWRP then you will need to include the ruby_build cookbook.

Installation

Depending on the situation and use case there are several ways to install this cookbook. All the methods listed below assume a tagged version release is the target, but omit the tags to get the head of development. A valid Chef repository structure like the Opscode repo is also assumed.

Using Berkshelf

Berkshelf is a cookbook dependency manager and development workflow assistant. To install Berkshelf:

cd chef-repo
gem install berkshelf
berks init

To reference the Git version:

repo="fnichol/chef-rbenv"
latest_release=$(curl -s https://api.github.com/repos/$repo/git/refs/tags \
| ruby -rjson -e '
  j = JSON.parse(STDIN.read);
  puts j.map { |t| t["ref"].split("/").last }.sort.last
')
cat >> Berksfile <<END_OF_BERKSFILE
cookbook 'rbenv',
  :git => 'git://github.com/$repo.git', :branch => '$latest_release'
END_OF_BERKSFILE
berks install

Using Librarian-Chef

Librarian-Chef is a bundler for your Chef cookbooks. To install Librarian-Chef:

cd chef-repo
gem install librarian
librarian-chef init

To reference the Git version:

repo="fnichol/chef-rbenv"
latest_release=$(curl -s https://api.github.com/repos/$repo/git/refs/tags \
| ruby -rjson -e '
  j = JSON.parse(STDIN.read);
  puts j.map { |t| t["ref"].split("/").last }.sort.last
')
cat >> Cheffile <<END_OF_CHEFFILE
cookbook 'rbenv',
  :git => 'git://github.com/$repo.git', :ref => '$latest_release'
END_OF_CHEFFILE
librarian-chef install

From the Community Site

This cookbook is not currently available on the site due to the flat namespace for cookbooks.

Recipes

default

Installs the rbenv gem and initializes Chef to use the Lightweight Resources and Providers (LWRPs).

Use this recipe explicitly if you only want access to the LWRPs provided.

system_install

Installs the rbenv codebase system-wide (that is, into /usr/local/rbenv). This recipe includes default.

Use this recipe by itself if you want rbenv installed system-wide but want to handle installing Rubies, invoking LWRPs, etc..

system

Installs the rbenv codebase system-wide (that is, into /usr/local/rbenv) and installs rubies driven off attribute metadata. This recipe includes default and system_install.

Use this recipe by itself if you want rbenv installed system-wide with rubies installed.

user_install

Installs the rbenv codebase for a list of users (selected from the node['rbenv']['user_installs'] hash). This recipe includes default.

Use this recipe by itself if you want rbenv installed for specific users in isolation but want each user to handle installing Rubies, invoking LWRPs, etc.

user

Installs the rbenv codebase for a list of users (selected from the node['rbenv']['user_installs'] hash) and installs rubies driven off attribte metadata. This recipe includes default and user_install.

Use this recipe by itself if you want rbenv installed for specific users in isolation with rubies installed.

vagrant

An optional recipe if Chef is installed in a non-rbenv Ruby in a [Vagrant][vagrant] virtual machine. This recipe installs a chef-solo wrapper script so Chef doesn't need to be re-installed in the global rbenv Ruby.

Attributes

git_url

The Git URL which is used to install rbenv.

The default is "git://github.com/sstephenson/rbenv.git".

git_ref

A specific Git branch/tag/reference to use when installing rbenv. For example, to pin rbenv to a specific release:

node.default['ruby_build']['git_ref'] = "v0.2.1"

The default is "v0.4.0".

upgrade

Determines how to handle installing updates to the rbenv. There are currently 2 valid values:

  • "none", false, or nil: will not update rbenv and leave it in its current state.
  • "sync" or true: updates rbenv to the version specified by the git_ref attribute or the head of the master branch by default.

The default is "none".

root_path

The path prefix to rbenv in a system-wide installation.

The default is "/usr/local/rbenv".

rubies

A list of additional system-wide rubies to be built and installed using the ruby_build cookbook. You must include recipe[ruby_build] in your run_list for the rbenv_ruby LWRP to work properly. For example:

node.default['rbenv']['rubies'] = [ "1.9.3-p0", "jruby-1.6.5" ]

The default is an empty array: [].

Additional environment variables can be passed to ruby_build via the environment variable. For example:

node.default['rbenv']['rubies'] = [ "1.9.3-p0", "jruby-1.6.5",
  {
  :name => '1.9.3-327',
  :environment => { 'CFLAGS' => '-march=native -O2 -pipe' }
  }
]

user_rubies

A list of additional system-wide rubies to be built and installed (using the ruby_build cookbook) per-user when not explicitly set. For example:

node.default['rbenv']['user_rubies'] = [ "1.8.7-p352" ]

The default is an empty array: [].

Additional environment variables can be passed to ruby_build via the environment variable. For example:

node.default['rbenv']['user_rubies'] = [ "1.8.7-p352",
  {
  :name => '1.9.3-327',
  :environment => { 'CFLAGS' => '-march=native -O2 -pipe' }
  }
]

gems

A hash of gems to be installed into arbitrary rbenv-managed rubies system wide. See the rbenv_gem resource for more details about the options for each gem hash and target Ruby environment. For example:

node.default['rbenv']['gems'] = {
  '1.9.3-p0' => [
    { 'name'    => 'vagrant' },
    { 'name'    => 'bundler'
      'version' => '1.1.rc.5'
    }
  ],
  '1.8.7-p352' => [
    { 'name'    => 'nokogiri' }
  ]
}

The default is an empty hash: {}.

user_gems

A hash of gems to be installed into arbitrary rbenv-managed rubies for each user when not explicitly set. See the rbenv_gem resource for more details about the options for each gem hash and target Ruby environment. See the gems attribute for an example.

The default is an empty hash: {}.

plugins

A list of plugins to be installed system-wide. See the rbenv_plugin resource for details about the options.

node.default['rbenv']['plugins'] = [
  { 'name' => 'rbenv-vars',
    'git_url' => 'https://github.com/sstephenson/rbenv-vars.git' },
  { 'name' => 'rbenv-gem-rehash',
    'git_url' => 'https://github.com/sstephenson/rbenv-gem-rehash.git',
    'git_ref' => '4d7b92de4' }
]

The default is an empty array: [].

user_plugins

As with user_gems, a list of plugins to be installed for each user when not explicitly set.

The default is an empty array: [].

vagrant/system_chef_solo

If using the vagrant recipe, this sets the path to the package-installed chef-solo binary.

The default is "/opt/ruby/bin/chef-solo".

create_profiled

The user's shell needs to know about rbenv's location and set up the PATH environment variable. This is handled in the system_install and user_install recipes by dropping off /etc/profile.d/rbenv.sh. However, this requires root privilege, which means that a user cannot use a "user install" for only their user.

Set this attribute to false to skip creation of the /etc/profile.d/rbenv.sh template. For example:

node.default['rbenv']['create_profiled'] = false

The default is true.

Resources and Providers

rbenv_global

This resource sets the global version of Ruby to be used in all shells, as per the rbenv global docs.

Actions

Action Description Default
create Sets the global version of Ruby to be used in all shells. See 3.1 rbenv global(1) for more details. Yes
  1. 3.1 rbenv global

Attributes

Attribute Description Default Value
rbenv_version Name attribute: a version of Ruby being managed by rbenv. Note: the version of Ruby must already be installed--this LWRP will not install it automatically. nil
user A users's isolated rbenv installation on which to apply an action. The default value of nil denotes a system-wide rbenv installation is being targeted. Note: if specified, the user must already exist. nil
root_path The path prefix to rbenv installation, for example: /opt/rbenv. nil

Examples

Set A Ruby As Global
rbenv_global "1.8.7-p352"
Set System Ruby As Global
rbenv_global "system"
Set A Ruby As Global For A User
rbenv_global "jruby-1.7.0-dev" do
  user "tflowers"
end

rbenv_script

This resource is a wrapper for the script resource which wraps the code block in an rbenv-aware environment. See the Opscode script resource page and the rbenv shell documentation for more details.

Actions

Action Description Default
run Run the script Yes
nothing Do not run this command  

Use action :nothing to set a command to only run if another resource notifies it.

Attributes

Attribute Description Default Value
name Name attribute: Name of the command to execute. name
rbenv_version A version of Ruby being managed by rbenv. nil
root_path The path prefix to rbenv installation, for example: /opt/rbenv. nil
code Quoted script of code to execute. nil
creates A file this command creates - if the file exists, the command will not be run. nil
cwd Current working director to run the command from. nil
environment A has of environment variables to set before running this command. nil
group A group or group ID that we should change to before running this command. nil
path An array of paths to use when searching for the command. nil, uses system path
returns The return value of the command (may be an array of accepted values) - this resource raises an exception if the return value(s) do not match. 0
timeout How many seconds to let the command run before timing out. nil
user A users's isolated rbenv installation on which to apply an action. The default value of nil denotes a system-wide rbenv installation is being targeted. Note: if specified, the user must already exist. nil
umask Umask for files created by the command. nil

Examples

Run A Rake Task
rbenv_script "migrate_rails_database" do
  rbenv_version "1.8.7-p352"
  user          "deploy"
  group         "deploy"
  cwd           "/srv/webapp/current"
  code          %{rake RAILS_ENV=production db:migrate}
end

rbenv_gem

This resource is a close analog of the gem_package resource/provider which is rbenv-aware. See the Opscode package resource and gem package options pages for more details.

Actions

Action Description Default
install Install a gem - if version is provided, install that specific version. Yes
Upgrade a gem - if version is provided, upgrade to that specific version.  
remove Remove a gem.  
purge Purge a gem.  

Attributes

Attribute Description Default Value
package_name Name attribute: the name of the gem to install. nil
rbenv_version A version of Ruby being managed by rbenv. "global"
root_path The path prefix to rbenv installation, for example: /opt/rbenv. nil
version The specific version of the gem to install/upgrade. nil
options Add additional options to the underlying gem command. nil
source Provide an additional source for gem providers (such as RubyGems). This can also include a file system path to a .gem file such as /tmp/json-1.5.1.gem. nil
user A users's isolated rbenv installation on which to apply an action. The default value of nil denotes a system-wide rbenv installation is being targeted. Note: if specified, the user must already exist. nil

Examples

Install A Gem
rbenv_gem "thor" do
  rbenv_version   "1.8.7-p352"
  action          :install
end

rbenv_gem "json" do
  rbenv_version   "1.8.7-p330"
end

rbenv_gem "nokogiri" do
  rbenv_version   "jruby-1.5.6"
  version         "1.5.0.beta.4"
  action          :install
end

Note: the install action is default, so the second example is a more common usage.

Install A Gem From A Local File
rbenv_gem "json" do
  rbenv_version   "ree-1.8.7-2011.03"
  source          "/tmp/json-1.5.1.gem"
  version         "1.5.1"
end
Keep A Gem Up To Date
rbenv_gem "homesick" do
  action :upgrade
end

Note: the global rbenv Ruby will be targeted if no rbenv_version attribute is given.

Remove A Gem
rbenv_gem "nokogiri" do
  rbenv_version   "jruby-1.5.6"
  version         "1.4.4.2"
  action          :remove
end

rbenv_plugin

Installs rbenv plugins.

Attributes

Attribute Description Default Value
name Name attribute: the name of the plugin to install. nil
root_path The path prefix to rbenv installation, for example: /opt/rbenv. nil
git_url The git URL of the plugin repository to clone. nil
git_ref The git revision (branch name or SHA) of the repository to checkout. 'master'
user A users's isolated rbenv installation on which to apply an action. The default value of nil denotes a system-wide rbenv installation is being targeted. Note: if specified, the user must already exist. nil
Install a plugin
rbenv_plugin 'rbenv-vars' do
  git_url 'https://github.com/sstephenson/rbenv-vars.git'
  user 'deploy'
end

rbenv_rehash

This resource installs shims for all Ruby binaries known to rbenv, as per the rbenv rehash docs.

Actions

Action Description Default
run Run the script Yes
nothing Do not run this command  

Use action :nothing to set a command to only run if another resource notifies it.

Attributes

Attribute Description Default Value
name Name attribute: Name of the command to execute. name
user A users's isolated rbenv installation on which to apply an action. The default value of nil denotes a system-wide rbenv installation is being targeted. Note: if specified, the user must already exist. nil
root_path The path prefix to rbenv installation, for example: /opt/rbenv. nil

Examples

Rehash A System-Wide rbenv
rbenv_rehash "Doing the rehash dance"
Rehash A User's rbenv
rbenv_rehash "Rehashing tflowers' rbenv" do
  user  "tflowers"
end

rbenv_ruby

This resource uses the ruby-build framework to build and install Ruby versions from definition files.

Note: this LWRP requires the ruby_build cookbook to be in the run list to perform the builds.

Actions

Action Description Default
install Build and install a Ruby from a definition file. See the ruby-build readme(1) for more details. Yes
reinstall Force a recompiliation of the Ruby from source. The :install action will skip a build if the target install directory already exists.  
  1. ruby-build readme

Attributes

Attribute Description Default Value
definition Name attribute: the name of a built-in definition(1) or the name of the ruby installed by a ruby-build defintion file(2) nil
definition_file The path to a ruby-build definition file. nil
user A users's isolated rbenv installation on which to apply an action. The default value of nil denotes a system-wide rbenv installation is being targeted. Note: if specified, the user must already exist. nil
root_path The path prefix to rbenv installation, for example: /opt/rbenv. nil
  1. built-in definition
  2. the recipe checks for the existence of the naming attribute under the root_path, and if not found invokes ruby-build with the definition file as an argument

Examples

Install Ruby From ruby-build
rbenv_ruby "ree-1.8.7-2011.03" do
  action :install
end

rbenv_ruby "jruby-1.6.5"

Note: the install action is default, so the second example is a more common usage.

Reinstall Ruby
rbenv_ruby "ree-1.8.7-2011.03" do
  action :reinstall
end
Install a custom ruby
rbenv_ruby "2.0.0p116" do
  definition_file "/usr/local/rbenv/custom/2.0.0p116"
end

System-Wide Mac Installation Note

This cookbook takes advantage of managing profile fragments in an /etc/profile.d directory, common on most Unix-flavored platforms. Unfortunately, Mac OS X does not support this idiom out of the box, so you may need to modify your user profile.

Development

Pull requests are very welcome! Make sure your patches are well tested. Ideally create a topic branch for every separate change you make.

License and Author

Author:: Fletcher Nichol (fnichol@nichol.ca) endorse

Copyright 2011, Fletcher Nichol

Licensed under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at

http://www.apache.org/licenses/LICENSE-2.0

Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License.