Ruby Installation with rbenv/RVM: Complete Guide for Linux Servers

Ruby is a dynamic, open-source programming language focused on simplicity and productivity. For system administrators and developers working with Ruby applications, managing multiple Ruby versions across different projects is a common challenge. This comprehensive guide explores the two most popular Ruby version managers: rbenv and RVM (Ruby Version Manager), providing detailed installation instructions, configuration best practices, and troubleshooting strategies.

Introduction

Ruby version management is essential for modern development environments where different applications may require different Ruby versions. While the system package manager can install Ruby, it typically provides only one version and may not offer the latest releases. Ruby version managers like rbenv and RVM solve this problem by allowing you to install and switch between multiple Ruby versions seamlessly.

Understanding rbenv vs RVM

rbenv is a lightweight Ruby version manager that intercepts Ruby commands using shim executables. It focuses on doing one thing well: switching Ruby versions. rbenv doesn't manage gem dependencies or provide built-in features for creating gemsets, making it simpler and more Unix-philosophy compliant.

RVM (Ruby Version Manager) is a more comprehensive solution that manages both Ruby versions and gemsets. It modifies your shell environment more aggressively and provides additional features like project-specific configurations, automatic switching, and integrated gemset management.

Both tools have their merits, and the choice often comes down to personal preference and specific project requirements. This guide covers both approaches comprehensively.

Prerequisites

Before installing rbenv or RVM, ensure your system meets the following requirements:

System Requirements

• A Linux distribution (Ubuntu, Debian, CentOS, Rocky Linux, or similar)
• Root or sudo access for installing dependencies
• At least 500MB of free disk space
• Active internet connection for downloading Ruby versions
• Basic command-line knowledge

Required Dependencies

Both rbenv and RVM require compilation tools to build Ruby from source. Install the appropriate dependencies for your distribution:

Ubuntu/Debian:

sudo apt update
sudo apt install -y build-essential libssl-dev libreadline-dev zlib1g-dev \
  libsqlite3-dev wget curl git-core libffi-dev libyaml-dev

CentOS/Rocky Linux/RHEL:

sudo yum groupinstall -y "Development Tools"
sudo yum install -y gcc-c++ patch readline readline-devel zlib zlib-devel \
  libyaml-devel libffi-devel openssl-devel make bzip2 autoconf automake \
  libtool bison sqlite-devel

Additional Considerations:

• For production servers, consider the security implications of compiling software
• Ensure your firewall allows outbound HTTPS connections for downloading Ruby versions
• Verify that your system has enough RAM for compilation (at least 1GB recommended)
• Consider using a dedicated user for application deployment rather than root

Installing rbenv

rbenv provides a clean, simple approach to Ruby version management. It's ideal for users who prefer minimal shell modifications and explicit control.

Step 1: Clone rbenv Repository

Install rbenv by cloning its Git repository to your home directory:

git clone https://github.com/rbenv/rbenv.git ~/.rbenv

Step 2: Configure Shell Environment

Add rbenv to your shell's PATH and initialize it automatically. The method varies by shell:

For Bash (~/.bashrc):

echo 'export PATH="$HOME/.rbenv/bin:$PATH"' >> ~/.bashrc
echo 'eval "$(rbenv init -)"' >> ~/.bashrc
source ~/.bashrc

For Zsh (~/.zshrc):

echo 'export PATH="$HOME/.rbenv/bin:$PATH"' >> ~/.zshrc
echo 'eval "$(rbenv init -)"' >> ~/.zshrc
source ~/.zshrc

Step 3: Install ruby-build Plugin

The ruby-build plugin provides the rbenv install command for installing Ruby versions:

mkdir -p "$(rbenv root)"/plugins
git clone https://github.com/rbenv/ruby-build.git "$(rbenv root)"/plugins/ruby-build

Step 4: Verify Installation

Confirm rbenv is properly installed:

rbenv --version
curl -fsSL https://github.com/rbenv/rbenv-installer/raw/main/bin/rbenv-doctor | bash

The rbenv-doctor script checks your installation and reports any issues.

Step 5: Install Ruby Versions

List available Ruby versions:

rbenv install -l

Install a specific Ruby version (e.g., Ruby 3.2.2):

rbenv install 3.2.2

The compilation process may take several minutes. Once complete, verify the installation:

rbenv versions

Step 6: Set Default Ruby Version

Set a global default Ruby version:

rbenv global 3.2.2

Or set a local version for a specific directory:

cd /path/to/project
rbenv local 3.1.4

This creates a .ruby-version file in the directory, automatically switching to that Ruby version when you enter the directory.

Step 7: Verify Ruby Installation

Check that Ruby is working correctly:

ruby --version
which ruby
gem --version

Installing RVM

RVM provides a more feature-rich environment with integrated gemset management and additional automation capabilities.

Step 1: Import GPG Keys

RVM requires GPG keys for security verification:

gpg --keyserver keyserver.ubuntu.com --recv-keys 409B6B1796C275462A1703113804BB82D39DC0E3 7D2BAF1CF37B13E2069D6956105BD0E739499BDB

If the keyserver is unavailable, try an alternative:

gpg --keyserver hkp://keyserver.ubuntu.com:80 --recv-keys 409B6B1796C275462A1703113804BB82D39DC0E3 7D2BAF1CF37B13E2069D6956105BD0E739499BDB

Step 2: Install RVM

Install RVM with the latest stable Ruby version:

curl -sSL https://get.rvm.io | bash -s stable --ruby

Or install RVM without Ruby (to manually install versions later):

curl -sSL https://get.rvm.io | bash -s stable

Step 3: Load RVM Environment

Source the RVM script to load it into your current shell:

source ~/.rvm/scripts/rvm

To load RVM automatically in new shell sessions, add this to your shell configuration:

For Bash (~/.bashrc):

echo 'source ~/.rvm/scripts/rvm' >> ~/.bashrc

For Zsh (~/.zshrc):

echo 'source ~/.rvm/scripts/rvm' >> ~/.zshrc

Step 4: Verify RVM Installation

Check that RVM is properly installed:

rvm --version
type rvm | head -n 1

The output should indicate that rvm is a function.

Step 5: Install Ruby Versions

List available Ruby versions:

rvm list known

Install a specific Ruby version:

rvm install 3.2.2

Install multiple versions:

rvm install 3.2.2 3.1.4 2.7.8

Step 6: Set Default Ruby Version

Set a default Ruby version:

rvm use 3.2.2 --default

Switch between installed versions:

rvm use 3.1.4

Step 7: Working with Gemsets

RVM's gemset feature allows isolated gem environments for different projects:

Create a new gemset:

rvm gemset create myproject

Use a specific Ruby version with a gemset:

rvm use 3.2.2@myproject

List all gemsets:

rvm gemset list

Set a project-specific Ruby version and gemset by creating .ruby-version and .ruby-gemset files:

echo "3.2.2" > .ruby-version
echo "myproject" > .ruby-gemset

Configuration

rbenv Configuration

rbenv configuration is minimal by design. Key configuration aspects include:

Global Ruby Version

The global Ruby version is stored in ~/.rbenv/version:

cat ~/.rbenv/version

Local Ruby Versions

Project-specific versions are defined in .ruby-version files:

echo "3.2.2" > /path/to/project/.ruby-version

rbenv Plugins

Enhance rbenv with additional plugins:

rbenv-vars (for environment variables):

git clone https://github.com/rbenv/rbenv-vars.git "$(rbenv root)"/plugins/rbenv-vars

rbenv-update (for easy updates):

git clone https://github.com/rkh/rbenv-update.git "$(rbenv root)"/plugins/rbenv-update

RVM Configuration

RVM offers extensive configuration options through its configuration files.

RVM Configuration File

RVM's main configuration file is located at ~/.rvmrc or /etc/rvmrc for system-wide settings.

Example configuration:

# Auto-cleanup old Ruby versions
export rvm_auto_clean=1

# Set default Ruby version
export rvm_default_ruby=ruby-3.2.2

# Trust project-specific .rvmrc files automatically
export rvm_trust_rvmrcs_flag=1

Project-Specific Configuration

Create a .rvmrc file in your project directory:

rvm use 3.2.2@myproject --create

Or use the modern approach with .ruby-version and .ruby-gemset files as shown earlier.

System-Wide Installation

For production servers with multiple users, consider system-wide installation:

rbenv (multi-user):

sudo git clone https://github.com/rbenv/rbenv.git /usr/local/rbenv
sudo git clone https://github.com/rbenv/ruby-build.git /usr/local/rbenv/plugins/ruby-build

# Add to /etc/profile.d/rbenv.sh
sudo tee /etc/profile.d/rbenv.sh << 'EOF'
export RBENV_ROOT=/usr/local/rbenv
export PATH="$RBENV_ROOT/bin:$PATH"
eval "$(rbenv init -)"
EOF

RVM (multi-user):

curl -sSL https://get.rvm.io | sudo bash -s stable
sudo usermod -a -G rvm username

Practical Examples

Example 1: Rails Application Development

Setting up a development environment for a Rails application:

Using rbenv:

cd ~/projects
git clone https://github.com/yourname/rails-app.git
cd rails-app

# Set Ruby version
rbenv local 3.2.2

# Install bundler
gem install bundler

# Install application dependencies
bundle install

# Verify environment
ruby --version
rails --version

Using RVM:

cd ~/projects
git clone https://github.com/yourname/rails-app.git
cd rails-app

# Create and use project-specific gemset
rvm use 3.2.2@rails-app --create
echo "3.2.2" > .ruby-version
echo "rails-app" > .ruby-gemset

# Install dependencies
gem install bundler
bundle install

# Verify environment
ruby --version
rvm current

Example 2: Multiple Applications with Different Ruby Versions

Managing multiple applications with different requirements:

# Application 1 (Ruby 3.2.2)
cd ~/apps/modern-app
rbenv local 3.2.2
gem install bundler
bundle install

# Application 2 (Ruby 2.7.8 - legacy)
cd ~/apps/legacy-app
rbenv local 2.7.8
gem install bundler -v 2.3.26
bundle install

# Verify both environments
cd ~/apps/modern-app && ruby --version  # Ruby 3.2.2
cd ~/apps/legacy-app && ruby --version  # Ruby 2.7.8

Example 3: Production Deployment Script

Automated deployment script using rbenv:

#!/bin/bash
# deploy.sh

set -e

APP_DIR="/var/www/myapp"
RUBY_VERSION="3.2.2"

cd "$APP_DIR"

# Set Ruby version
export PATH="$HOME/.rbenv/bin:$PATH"
eval "$(rbenv init -)"
rbenv local "$RUBY_VERSION"

# Update code
git pull origin main

# Install dependencies
gem install bundler
bundle install --deployment --without development test

# Precompile assets
bundle exec rake assets:precompile RAILS_ENV=production

# Restart application
sudo systemctl restart myapp

echo "Deployment complete!"

Example 4: Installing Specific Ruby Patch Versions

Installing and testing multiple patch versions:

# Install multiple patch versions
rbenv install 3.2.0
rbenv install 3.2.1
rbenv install 3.2.2

# Test application with each version
for version in 3.2.0 3.2.1 3.2.2; do
  echo "Testing with Ruby $version"
  rbenv shell $version
  ruby --version
  bundle exec rspec
done

# Set the working version
rbenv local 3.2.2

Verification

After installation and configuration, verify your Ruby environment thoroughly.

Basic Verification

# Check Ruby version
ruby --version

# Verify Ruby executable location
which ruby

# Check gem version
gem --version

# Verify bundler
gem install bundler
bundle --version

rbenv-Specific Verification

# List installed versions
rbenv versions

# Show current version
rbenv version

# Verify shims
rbenv shims

# Check rbenv status
rbenv doctor

RVM-Specific Verification

# List installed Rubies
rvm list

# Show current Ruby and gemset
rvm current

# Verify RVM function
type rvm | head -n 1

# Check gemset
rvm gemset list

Testing Ruby Installation

Create a simple test script to verify Ruby functionality:

# test_ruby.rb
puts "Ruby version: #{RUBY_VERSION}"
puts "Platform: #{RUBY_PLATFORM}"
puts "Gem paths:"
puts Gem.path

require 'openssl'
puts "OpenSSL version: #{OpenSSL::OPENSSL_VERSION}"

require 'json'
data = { test: 'success', ruby: RUBY_VERSION }
puts "JSON test: #{data.to_json}"

Run the test:

ruby test_ruby.rb

Troubleshooting

Common issues and their solutions when working with rbenv and RVM.

Issue 1: Command Not Found After Installation

Symptom: rbenv: command not found or rvm: command not found

Solution:

Ensure the PATH is correctly configured:

# For rbenv
echo 'export PATH="$HOME/.rbenv/bin:$PATH"' >> ~/.bashrc
echo 'eval "$(rbenv init -)"' >> ~/.bashrc
source ~/.bashrc

# For RVM
source ~/.rvm/scripts/rvm
echo 'source ~/.rvm/scripts/rvm' >> ~/.bashrc

Issue 2: Ruby Version Not Changing

Symptom: Running rbenv local or rvm use doesn't change the Ruby version

Solution for rbenv:

# Rehash shims after installing gems
rbenv rehash

# Check for conflicting .ruby-version files
find ~ -name .ruby-version

# Verify rbenv is properly initialized
rbenv init

Solution for RVM:

# Reload RVM
rvm reload

# Check for shell conflicts
echo $SHELL
rvm get stable --auto-dotfiles

Issue 3: Compilation Failures

Symptom: Ruby installation fails with compilation errors

Solution:

Ensure all dependencies are installed:

# Ubuntu/Debian
sudo apt install -y build-essential libssl-dev libreadline-dev zlib1g-dev

# CentOS/Rocky Linux
sudo yum groupinstall -y "Development Tools"
sudo yum install -y openssl-devel readline-devel zlib-devel

For OpenSSL-related errors:

# rbenv
RUBY_CONFIGURE_OPTS="--with-openssl-dir=/usr/local/openssl" rbenv install 3.2.2

# RVM
rvm install 3.2.2 --with-openssl-dir=/usr/local/openssl

Issue 4: Permission Denied Errors

Symptom: Permission errors when installing gems or Ruby versions

Solution:

Never use sudo with rbenv or RVM:

# Wrong
sudo gem install rails

# Correct
gem install rails

If you encounter permission errors, fix ownership:

# For rbenv
sudo chown -R $(whoami) ~/.rbenv

# For RVM
sudo chown -R $(whoami) ~/.rvm

Issue 5: Slow Ruby Installation

Symptom: Ruby compilation takes an extremely long time

Solution:

Use pre-compiled Ruby binaries when available:

# RVM can use pre-compiled binaries
rvm install 3.2.2 --disable-binary

# Or explicitly use binary
rvm install 3.2.2 --binary

Enable parallel compilation:

# Set MAKE_OPTS for parallel builds
export MAKE_OPTS="-j 4"
rbenv install 3.2.2

Issue 6: Gemset Not Found (RVM)

Symptom: Gemset 'projectname' does not exist

Solution:

# Create the gemset
rvm gemset create projectname

# Use it with current Ruby
rvm use @projectname

# Or create project files
echo "3.2.2" > .ruby-version
echo "projectname" > .ruby-gemset
cd . # Trigger RVM to create gemset

Best Practices

Security Best Practices

1. Verify Downloads: Always verify GPG signatures when installing RVM
2. Regular Updates: Keep rbenv/RVM and Ruby versions updated for security patches
3. Minimal Installation: On production servers, only install required Ruby versions
4. User Permissions: Never run Ruby applications as root
5. Gem Security: Use bundle audit to check for vulnerable dependencies

# Install bundler-audit
gem install bundler-audit

# Check for vulnerabilities
bundle audit check --update

Performance Best Practices

1. Use Latest Ruby: Newer Ruby versions often include performance improvements
2. Enable JIT: Ruby 3.x includes MJIT compiler for better performance

# Enable MJIT
export RUBY_MJIT_ENABLE=1
ruby --jit your_script.rb

3. Optimize Gem Installation: Use bundle's parallel installation

bundle install --jobs=4

4. Cache Gems: In CI/CD environments, cache the gem directory

# Add to CI configuration
cache:
  paths:
    - vendor/bundle

Development Best Practices

1. Version Lock Files: Always commit .ruby-version to version control
2. Document Dependencies: Maintain an updated Gemfile and Gemfile.lock
3. Test Multiple Versions: Use CI to test against multiple Ruby versions
4. Isolated Environments: Use gemsets (RVM) or bundle's deployment mode (rbenv)

# Bundle deployment mode
bundle install --deployment

5. Clean Old Versions: Regularly remove unused Ruby versions

# rbenv
rbenv uninstall 3.1.0

# RVM
rvm remove 3.1.0

Production Best Practices

1. Stability Over Features: Use stable Ruby versions, not development releases
2. Consistent Environments: Ensure development and production use identical Ruby versions
3. Automated Deployments: Use deployment tools like Capistrano or custom scripts
4. Monitoring: Monitor Ruby process performance and memory usage
5. Backup Configurations: Keep backups of .ruby-version, .ruby-gemset, and Gemfiles

Example Capistrano configuration:

# config/deploy.rb
set :rbenv_type, :user
set :rbenv_ruby, '3.2.2'
set :rbenv_prefix, "RBENV_ROOT=#{fetch(:rbenv_path)} RBENV_VERSION=#{fetch(:rbenv_ruby)} #{fetch(:rbenv_path)}/bin/rbenv exec"
set :rbenv_map_bins, %w{rake gem bundle ruby rails}

Team Collaboration Best Practices

1. Document Tool Choice: Clearly document whether the project uses rbenv or RVM
2. Standardize Versions: Ensure all team members use the same Ruby version
3. Share Configuration: Commit version files to repository
4. Update Documentation: Keep setup instructions current in README files

Example README section:

## Development Setup

This project uses Ruby 3.2.2 managed with rbenv.

### Initial Setup

1. Install rbenv: https://github.com/rbenv/rbenv
2. Install Ruby: `rbenv install 3.2.2`
3. Install dependencies: `bundle install`
4. Run tests: `bundle exec rspec`

Conclusion

Ruby version management is a critical skill for developers and system administrators working with Ruby applications. Both rbenv and RVM provide robust solutions for managing multiple Ruby versions, each with distinct advantages.

Choose rbenv if you:

• Prefer minimal shell modifications
• Want a simple, Unix-philosophy approach
• Don't need integrated gemset management
• Value explicit control over your environment

Choose RVM if you:

• Need integrated gemset management
• Want automatic environment switching
• Prefer feature-rich tools with built-in automation
• Work with multiple projects requiring isolated gem environments

Regardless of your choice, following the best practices outlined in this guide will ensure a stable, secure, and efficient Ruby development environment. Regular updates, proper testing, and adherence to security guidelines will maintain the health of your Ruby installations over time.

The Ruby ecosystem continues to evolve with each release bringing performance improvements, security enhancements, and new features. By mastering Ruby version management with rbenv or RVM, you establish a solid foundation for developing and deploying Ruby applications successfully in any environment.

Remember that the choice between rbenv and RVM isn't permanent—you can switch between them if your needs change. What matters most is understanding how to leverage these tools effectively to maintain consistent, reproducible Ruby environments across development, staging, and production systems.

With the knowledge gained from this comprehensive guide, you're now equipped to install, configure, and troubleshoot Ruby installations confidently, enabling you to focus on building great applications rather than fighting environment issues.