diff --git a/README.md b/README.md index e974521..c311c89 100644 --- a/README.md +++ b/README.md @@ -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