bofh/ansible-role-rvm
9
0
Fork 0
Code Issues Pull Requests Releases Wiki Activity

Redo the readme to make it more clear

Browse Source
This commit is contained in:
Nick Janetakis
2014-09-20 12:15:44 -04:00
parent 2d15cea6ad
commit 2c6fd43313
1 changed files with 56 additions and 103 deletions
Download Patch File Download Diff File Expand all files Collapse all files

159
README.md
View File

@@ -1,130 +1,93 @@
## What is rvm1-ansible? [![Build Status](https://secure.travis-ci.org/rvm/rvm1-ansible.png)](http://travis-ci.org/rvm/rvm1-ansible)
It is an [ansible](http://www.ansible.com/home) role to install and manage ruby versions using rvm.
It is an [Ansible](http://www.ansible.com/home) role to install and manage ruby versions using rvm.
### What problem does it solve and why is it useful?
### Why should you use rvm?
I wasn't happy with any of the solutions that existed because they required you to either compile ruby on your server or they were not idempotent. Compiling ruby on a low end VPS/instance could easily take 10 minutes and during that time your CPU is going to be pegged at 100%.
In production it's useful because compiling a new version of ruby can easily
take upwards of 10 minutes. That's 10 minutes of your CPU being pegged at 100%.
rvm1-ansible solves this by using rvm to install 1 or more versions of ruby. It makes installing and upgrading ruby versions very easy.
rvm has pre-compiled binaries for a lot of operating systems. That means you can
install ruby in about 1 minute, even on a slow micro instance.
This role even adds the ruby binaries to your system path when doing a system
wide install. This allows you to access them as if they were installed without
using a version manager while still benefiting from what rvm has to offer.
## Installation
`$ ansible-galaxy install rvm_io.rvm1-ruby`
## Example playbook
For the sake of this example let's assume you have a group called **app** and you have a typical `site.yml` file.
To use this role edit your `site.yml` file to look something like this:
```
---
- name: ensure app servers are configured
hosts: app
roles:
# If you use the default rvm install location you must enable sudo
# because it will install to /usr/local/rvm.
#
# If you are installing to your user's home directory then you can drop sudo.
- { role: rvm_io.rvm1-ruby, tags: ruby, sudo: true }
```
Let's say you want to edit a few values, you can do this by opening or creating `group_vars/app.yml` which is located relative to your `inventory` directory and then making it look something like this:
```
---
# Let's install rvm locally to a user and install multiple versions of ruby.
# We can dump the rvm install script to /tmp.
rvm1_temp_download_path: '/tmp'
# If you're going to use the ~ shortcut and you have sudo enabled then make sure
# you set sudo_user on the role to the correct user or it will be root.
# ie. { role: rvm_io.rvm1-ruby, tags: ruby, sudo: true, sudo_user: '{{ rvm1_user }}' }
# Another option is just to not set sudo for the rvm role at all.
rvm1_install_path: '~/.rvm'
rvm1_rubies:
- 'ruby-2.1.0'
- 'ruby-2.1.2'
```
## Role variables
Below is a list of default values along with a description of what they do.
Below is a list of default values that you can configure:
```
# Install 1 or more versions of ruby, just add them to the list.
# The last version listed will be set as the default ruby.
# Change it to `ruby_rubies:` if you want no rubies installed.
---
# Install 1 or more versions of ruby
rvm1_rubies:
- 'ruby-2.1.2'
# Which version of ruby do you want to delete?
# Example: `rvm1_delete_ruby: ruby-2.1.0`
rvm1_delete_ruby: ''
# Delete a specific version of ruby (ie. ruby-2.1.0)
rvm1_delete_ruby:
# Which user should own all of rvm's files?
rvm1_user: '{{ ansible_ssh_user }}'
# Install path for rvm (defaults to system wide)
rvm1_install_path: '/usr/local/lib/rvm'
# Which group should rvm be installed to?
rvm1_group: 'rvm'
# Add or remove any install flags
# NOTE: If you are doing a USER BASED INSTALL then
# make sure you ADD the --user-install flag below
rvm1_install_flags: '--auto-dotfiles'
# Where should the rvm-installer and other temp files be downloaded to?
rvm1_temp_download_path: '/usr/local/src'
# Where should rvm be installed to?
rvm1_install_path: '/usr/local/rvm'
# Which url contains the rvm-installer script?
rvm1_rvm_latest_installer: 'https://raw.githubusercontent.com/wayneeseguin/rvm/master/binscripts/rvm-installer'
# Which url or value contains the stable version number of rvm?
# If you use a url, it must include http:// or https:// at the start.
# If you use a value, it should be something like 1.25.27 or any legal version number.
# If you want to lock rvm to a specific version you could enter in the version number
# that you have installed and the role would assume you always have the latest stable version.
rvm1_rvm_stable_version_number: 'https://raw.githubusercontent.com/wayneeseguin/rvm/master/VERSION'
# Force upgrade the rvm-installer to the latest version.
# Should rvm always be upgraded?
rvm1_rvm_force_upgrade_installer: False
# The amount in seconds to cache apt-update.
# URLs for the latest installer and version
rvm1_rvm_latest_installer: 'https://raw.githubusercontent.com/wayneeseguin/rvm/master/binscripts/rvm-installer'
rvm1_rvm_stable_version_number: 'https://raw.githubusercontent.com/wayneeseguin/rvm/master/VERSION'
# Time in seconds before re-running apt-get update
# This is only used to download the httplib library so Ansible's URI module works
apt_cache_valid_time: 86400
```
## Exposed variables
## Example playbook
You will likely want to use various ruby related commands in other roles. This role exposes a number of popular paths and variables that you can use.
```
---
- `rvm1_default_ruby_version`
- The default ruby version that is selected
- name: Configure servers with ruby support
hosts: all
- `rvm1`
- The path to the rvm binary
roles:
- { role: rvm_io.rvm1-ruby, tags: ruby, sudo: True }
```
- `rvm1_default_wrappers`:
- The path containing all of the wrapped ruby related binaries
#### System wide installation
- `rvm1_ruby`
- The path to the ruby binary
The above example would setup ruby system wide. It's very important that you
run the play with sudo because it will need to write to `/usr/local/rvm`.
- `rvm1_gem`
- The path to the gem binary
#### To the same user as `ansible_ssh_user`
- `rvm1_bundle`
- The path to the bundle binary
You do not need to include `sudo: True` in this case, just overwrite `rvm_install_path` and set the `--user-install` flag:
- `rvm1_rake`
- The path to the rake binary with bundle exec already applied
```
rvm1_install_flags: '--auto-dotfiles --user-install'
rvm_install_path: '/home/{{ ansible_ssh_user }}/.rvm'
```
### Example
#### To a user that is not `ansible_ssh_user`
If you wanted to run a database migration in rails you would use `{{ rvm1_rake }} db:migrate`.
You **will need sudo here** because you will be writing outside the ansible
user's home directory. Other than that it's the same as above, except you will
supply a different user account:
```
rvm1_install_flags: '--auto-dotfiles --user-install'
rvm_install_path: '/home/someuser/.rvm'
```
## Upgrading and removing old versions of ruby
@@ -134,19 +97,9 @@ A common work flow for upgrading your ruby version would be:
2. Run your application role so that bundle install re-installs your gems
3. Delete the previous version of ruby
You can delete a version of ruby with this role in 1 of 2 ways:
### Edit your inventory directly
You could overwrite `rvm1_delete_ruby: 'ruby-2.1.0'` and then run your play book. This would work but then you would have to go back and edit your inventory to make it an empty string afterwards.
The delete task is idempotent but it still requires you to make 2 edits.
### Leverage ansible's `--extra-vars`
Just add `--extra-vars 'rvm1_delete_ruby=ruby-2.1.0'` to the end of your play book command and that version will be removed without having to manually edit your inventory.
Not having to edit anything sure sounds better to me.
Just add `--extra-vars 'rvm1_delete_ruby=ruby-2.1.0'` to the end of your play book command and that version will be removed.
## Requirements