Ruby on Rails Deployment & Usage Guide

Prerequisites

• Ruby 3.0 or higher (check .ruby-version in your app for specific version)
• Bundler (gem install bundler)
• SQLite3 (default for development) or PostgreSQL/MySQL (for production)
• Node.js 16+ and Yarn (required for JavaScript bundling/Webpacker/ESBuild)
• Git
• Redis (optional, required for Action Cable, caching, or Active Job)

Installation

1. Install Rails Globally

gem install rails

2. Create New Application

# Default with SQLite
rails new myapp

# With specific database
rails new myapp --database=postgresql

# With specific JavaScript bundler
rails new myapp --javascript=esbuild --css=tailwind

3. Install Dependencies

cd myapp
bundle install
yarn install  # If using JavaScript bundling

4. Database Setup

bin/rails db:create db:migrate

Configuration

Database Configuration

Edit config/database.yml for your environment:

development:
  adapter: postgresql
  encoding: unicode
  database: myapp_development
  pool: 5
  username: <%= ENV['DB_USERNAME'] %>
  password: <%= ENV['DB_PASSWORD'] %>
  host: localhost

production:
  adapter: postgresql
  encoding: unicode
  database: myapp_production
  pool: <%= ENV.fetch("RAILS_MAX_THREADS") { 5 } %>
  url: <%= ENV['DATABASE_URL'] %>

Credentials & Environment Variables

Rails uses encrypted credentials for secrets:

# Edit credentials (opens editor defined in EDITOR env var)
bin/rails credentials:edit

# For environment-specific variables, use:
bin/rails credentials:edit --environment production

Store environment variables in .env file (requires dotenv-rails gem in Gemfile):

# .env
DATABASE_URL=postgresql://user:pass@localhost/myapp_production
RAILS_MASTER_KEY=your_master_key_here
REDIS_URL=redis://localhost:6379/0

Cache Configuration

Configure caching backend in config/environments/production.rb:

# Redis cache store (requires redis gem)
config.cache_store = :redis_cache_store, { url: ENV['REDIS_URL'] }

# Or Memcached
config.cache_store = :mem_cache_store, ENV['MEMCACHED_SERVERS'].split(',')

# Memory store for simple deployments
config.cache_store = :memory_store, { size: 64.megabytes }

Build & Run

Development Server

# Standard Rails server
bin/rails server

# Or use Procfile-based dev server (if using jsbundling/cssbundling)
bin/dev

# Access at http://localhost:3000

Console & Tasks

# Interactive console
bin/rails console

# Run database migrations
bin/rails db:migrate

# Run tests
bin/rails test
# or
bundle exec rspec

Production Build Steps

# Precompile assets
RAILS_ENV=production bin/rails assets:precompile

# Clean old assets
RAILS_ENV=production bin/rails assets:clean

Deployment

Option 1: Heroku (Platform-as-a-Service)

# Install Heroku CLI and login
heroku create myapp
heroku addons:create heroku-postgresql:mini
heroku addons:create heroku-redis:mini

# Set environment variables
heroku config:set RAILS_MASTER_KEY=$(cat config/master.key)

# Deploy
git push heroku main

# Run migrations
heroku run bin/rails db:migrate

Option 2: Docker Deployment

Create Dockerfile:

FROM ruby:3.2-slim
RUN apt-get update -qq && apt-get install -y build-essential libpq-dev nodejs
WORKDIR /rails
COPY Gemfile Gemfile.lock ./
RUN bundle install
COPY . .
RUN bin/rails assets:precompile
EXPOSE 3000
CMD ["bin/rails", "server", "-b", "0.0.0.0"]

Build and run:

docker build -t myapp .
docker run -e RAILS_MASTER_KEY=$RAILS_MASTER_KEY -e DATABASE_URL=$DATABASE_URL -p 3000:3000 myapp

Option 3: Traditional VPS (Ubuntu/Capistrano)

1. Install Ruby, PostgreSQL, Nginx, Passenger
2. Configure config/deploy.rb with Capistrano
3. Deploy with cap production deploy

Option 4: Kamal (Rails 8+ Default)

# Initialize Kamal configuration
kamal init

# Deploy to Docker host
kamal setup
kamal deploy

Troubleshooting

Bundle Install Failures

Issue: Native extension compilation errors
Solution:

# Ubuntu/Debian
sudo apt-get install build-essential libpq-dev libsqlite3-dev

# macOS
brew install postgresql libyaml

Database Connection Errors

Issue: ActiveRecord::ConnectionNotEstablished
Solution:

• Verify config/database.yml credentials
• Check PostgreSQL/MySQL service is running: sudo service postgresql status
• For production, ensure DATABASE_URL is set

Asset Compilation Failures

Issue: Webpacker::Manifest::MissingEntryError or cssbundling-rails errors
Solution:

yarn install
bin/rails assets:clobber
bin/rails assets:precompile

Port Already in Use

Issue: Address already in use - bind(2) for "127.0.0.1" port 3000
Solution:

# Find and kill process
lsof -i :3000
kill -9 <PID>

# Or use different port
bin/rails server -p 3001

Connection Pool Exhaustion

Issue: ActiveRecord::ConnectionTimeoutError
Solution: Increase pool size in config/database.yml:

production:
  pool: 25  # Default is 5

Master Key Missing

Issue: Missing master key to decrypt credentials
Solution:

• Ensure config/master.key exists (do not commit to git)
• Or set RAILS_MASTER_KEY environment variable

Cache Deserialization Errors

Issue: ActiveSupport::Cache::DeserializationError
Solution: Clear cache after Rails upgrades:

bin/rails runner 'Rails.cache.clear'