How to Use Capistrano for Deployment in Ruby on Rails

Use Capistrano by adding it to your Rails project, configuring the deploy.rb and stage files, then run cap production deploy to deploy your app. Capistrano automates SSH commands to update your server with your Rails app code.

Syntax

Capistrano uses a Capfile and configuration files to define deployment tasks. The main syntax involves running commands like cap [stage] [task], where stage is your environment (e.g., production) and task is the action (e.g., deploy).

The deploy.rb file sets global deployment settings, and stage files (like production.rb) specify server details.

ruby

lock '~> 3.17.0'

set :application, 'my_app_name'
set :repo_url, '[e-mail]:username/my_app.git'

set :deploy_to, '/var/www/my_app_name'

append :linked_files, 'config/database.yml', 'config/master.key'
append :linked_dirs, 'log', 'tmp/pids', 'tmp/cache', 'tmp/sockets', 'public/system'

namespace :deploy do
  after :finishing, 'deploy:cleanup'
end

Example

This example shows a basic Capistrano setup for deploying a Rails app to a production server. It includes the Capfile, deploy.rb, and a production stage file.

ruby

# Capfile
require 'capistrano/setup'
require 'capistrano/deploy'
require 'capistrano/rails'
require 'capistrano/bundler'
require 'capistrano/rbenv'
require 'capistrano/puma'

# config/deploy.rb
lock '~> 3.17.0'

set :application, 'my_app'
set :repo_url, '[e-mail]:username/my_app.git'
set :deploy_to, '/var/www/my_app'

append :linked_files, 'config/database.yml', 'config/master.key'
append :linked_dirs, 'log', 'tmp/pids', 'tmp/cache', 'tmp/sockets', 'public/system'

namespace :deploy do
  after :finishing, 'deploy:cleanup'
end

# config/deploy/production.rb
server 'your.server.ip', user: 'deploy', roles: %w{app db web}

set :rbenv_ruby, '3.1.2'

# Deployment command (run in terminal):
# cap production deploy

Output

00:00 deploy:starting
00:01 deploy:updating
00:10 deploy:publishing
00:11 deploy:restart
00:12 deploy:finished

* Deploy finished successfully

Common Pitfalls

• Not setting correct SSH access or keys causes deployment failures.
• Forgetting to link shared files like database.yml or master.key leads to runtime errors.
• Incorrect Ruby version or missing dependencies on the server can break the app.
• Running cap commands without proper permissions or user setup causes errors.

Always test SSH connection and permissions before deploying.

ruby

### Wrong: Missing linked files setup
append :linked_files, 'config/database.yml'

### Right: Include all needed linked files
append :linked_files, 'config/database.yml', 'config/master.key'

Quick Reference

Command	Description
cap production deploy	Deploy app to production server
cap staging deploy	Deploy app to staging server
cap production deploy:rollback	Rollback last deployment
cap production deploy:restart	Restart app server
cap -T	List all Capistrano tasks

Key Takeaways

Add Capistrano gems and configure deploy.rb and stage files before deploying.

Use linked_files and linked_dirs to share config and persistent data between releases.

Test SSH access and Ruby environment on the server to avoid deployment errors.

Run deployment with cap [stage] deploy command to automate code updates.

Check Capistrano logs and output for troubleshooting deployment issues.