rbenv Chef Cookbook

[TOC]

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".

rvm_download/enable

Makes the rbenv_ruby LWRP to download ruby binaries instead of compiling them.

The default is true.

rvm_download/git_url

The Git URL which is used to install rvm-download.

The default is "git://github.com/garnieretienne/rvm-download.git".

rvm_download/git_ref

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

node.default['rbenv']['rvm_download']['git_ref'] = "v1.2.3"

The default is "master".

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⁽¹⁾ for more details.	Yes

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⁽¹⁾ 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.

ruby-build readme

Attributes

Attribute	Description	Default Value
definition	Name attribute: the name of a built-in definition⁽¹⁾ or the name of the ruby installed by a ruby-build defintion file⁽²⁾	`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`

built-in definition
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

Source hosted at GitHub
Report issues/Questions/Feature requests on GitHub Issues

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)

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.

Name		Name	Last commit message	Last commit date
Latest commit History 178 Commits
attributes		attributes
libraries		libraries
providers		providers
recipes		recipes
resources		resources
templates/default		templates/default
test		test
.gitignore		.gitignore
.kitchen.yml		.kitchen.yml
.rspec		.rspec
.travis.yml		.travis.yml
Berksfile		Berksfile
CHANGELOG.md		CHANGELOG.md
Gemfile		Gemfile
Gemfile.lock		Gemfile.lock
Guardfile		Guardfile
README.md		README.md
Rakefile		Rakefile
metadata.rb		metadata.rb

aminin/chef-rbenv

Folders and files

Latest commit

History

Repository files navigation

rbenv Chef Cookbook

Description

Usage

rbenv Installed System-Wide with Rubies

rbenv Installed For A Specific User with Rubies

rbenv Installed System-Wide and LWRPs Defined

rbenv Installed For A Specific User and LWRPs Defined

Ultra-Minimal Access To LWRPs

Other Use Cases

Requirements

Chef

Platform

Cookbooks

Installation

Using Berkshelf

Using Librarian-Chef

From the Community Site

Recipes

default

system_install

system

user_install

user

vagrant

Attributes

git_url

git_ref

upgrade

root_path

rvm_download/enable

rvm_download/git_url

rvm_download/git_ref

rubies

user_rubies

gems

user_gems

plugins

user_plugins

vagrant/system_chef_solo

create_profiled

Resources and Providers

rbenv_global

Actions

Attributes

Examples

Set A Ruby As Global

Set System Ruby As Global

Set A Ruby As Global For A User

rbenv_script

Actions

Attributes

Examples

Run A Rake Task

rbenv_gem

Actions

Attributes

Examples

Install A Gem

Install A Gem From A Local File

Keep A Gem Up To Date

Remove A Gem

rbenv_plugin

Attributes

Install a plugin

rbenv_rehash

Actions

Attributes

Examples

Rehash A System-Wide rbenv

Rehash A User's rbenv

rbenv_ruby

Actions

Attributes

Examples

Install Ruby From ruby-build

Packages