Welcome Guest | Login

Capistrano 2.x - Deploying Your Rails Application on HostingRails.com



This is a wiki article created by HostingRails users. Please login or signup to make edits.



WHY CAPISTRANO 2.x?  There are some significant changes (for the better) in the upgrade from Capistrano 1.x to Capistrano 2.x. There are a bunch of cool new commands, possibilities, configurations, and files. As usual, this is not to be an exhaustive exploration of the potential of Capistrano, but this tutorial will show the basics of configuring, setting up, and deploying your Rails app with Capistrano 2.x.


Notes/Updates : This tutorial was written using Mac OS X, hasn't been fully configured for a Linux or Windows environment. However, it should work fine for any operating system.

Suggestion to Nubies : If you haven't already done so, please read/skim through this prerequisite tutorial


== Get Started =>

1. Install Capistrano
The first step is to get the latest version of Capistrano with all its dependencies ("-y" is equivalent to "--include-dependencies") onto your local/development machine:
gem install -y capistrano
1.5. Setup SVN Repository
Once you have installed Capistrano and its dependencies, you will need a Subversion repository populated at least with a skeleton Rails app.  Setting up an SVN repository is not within the scope of this tutorial.  Please follow this SVN Repository Setup tutorial to get your repository setup on your HostingRails account.


2. Setup your Rails application to work with Capistrano
Once you have checked out your code from the svn repository, change to the root of the Rails app on your development machine and run:

capify .

# This is the output
[add] writing `./Capfile'
[add] writing `./config/deploy.rb'
[done] capified!
Capistrano created two files: /config/deploy.rb and Capfile. (Note: /config/deploy.rb might have been skipped if you already had a deploy.rb file in your app.) The config/deploy.rb file will contain your application variables used to deploy your app, while the Capfile will contain your deployment tasks.

/config/deploy.rb

Add the following variables and values to your deploy file. If you are upgrading from Capistrano 1.x you might not need to add anything.
set :application, "your_application_name"             # Can be whatever you want, I use the project name from my SVN repository
set :domain, "your_url.com"                           # The URL for your app
set :user, "username"                                 # Your HostingRails username

# For a Subversion repository
set :repository,  "svn+ssh://#{user}@#{domain}/home/#{user}/svn/#{application}/trunk"   # The repository location for svn+ssh access
# set :repository, "http://svn.#{domain}/svn/#{application}/trunk"                      # The repository location for http access from the server
# set :local_repository, "http://svn.#{domain}:port/svn/#{application}/trunk"           # The repository location for http access from the local machine (this could be different from above if you use ssh port forwarding for svn access

# For a Git repository
# See http://www.hostingrails.com/forums/wiki_thread/59 for more info on Git and HostingRails
set :repository,  "#{user}@#{domain}:/home/#{user}/git/#{application}"                  # Or any other valid git clone path
set :scm, :git

# set :scm_username, "svn_username"                   #if http
# set :scm_password, "svn_password"                   #if http
set :use_sudo, false                                  # HostingRails users don't have sudo access
set :deploy_to, "/home/#{user}/apps/#{application}"   # Where on the server your app will be deployed
set :deploy_via, :checkout                            # For this tutorial, svn checkout will be the deployment method, but check out :remote_cache in the future
set :group_writable, false                            # By default, Capistrano makes the release group-writable. You don't want this with HostingRails
# set :mongrel_port, "4444"                           # Mongrel port that was assigned to you
# set :mongrel_nodes, "4"                             # Number of Mongrel instances for those with multiple Mongrels

default_run_options[:pty] = true
# Cap won't work on windows without the above line, see
# http://groups.google.com/group/capistrano/browse_thread/thread/13b029f75b61c09d
# Its OK to leave it true for Linux/Mac

ssh_options[:keys] = %w(/Path/To/id_rsa)              # If you are using ssh_keys

role :app, domain
role :web, domain
role :db,  domain, :primary => true
If you are upgrading from Capistrano 1.x to 2.x, make sure to comment out any tasks you have. Tasks in Capistrano 2.x are put in the Capfile instead. (For more info on upgrading from 1.x to 2.x, see this.)

Capfile

Add the following lines to the Capfile. If you are using Mongrel, make sure the namespace for FCGI and Mongrel Cluster of commented out or deleted.

load 'deploy' if respond_to?(:namespace) # cap2 differentiator
load 'config/deploy'

# ========================
#     For FCGI Apps
# ========================
# NB: running the following :start task will delete your main public_html directory.
# So don't use these commands if you have existing sites in here.

namespace :deploy do

  task :start, :roles => :app do
    run "rm -rf /home/#{user}/public_html;ln -s #{current_path}/public /home/#{user}/public_html"
  end

  task :restart, :roles => :app do
    run "#{current_path}/script/process/reaper --dispatcher=dispatch.fcgi"
  end

end

# ========================
#    For Mongrel Apps
# ========================

# namespace :deploy do
# 
#   task :start, :roles => :app do
#     run "rm -rf /home/#{user}/public_html;ln -s #{current_path}/public /home/#{user}/public_html"
#     run "cd #{current_path} && mongrel_rails start -e production -p #{mongrel_port} -d"
#   end
# 
#   task :restart, :roles => :app do
#     run "cd #{current_path} && mongrel_rails restart"
#   end
# 
# end

# ========================
# For Mongrel Cluster Apps
# ========================

# namespace :deploy do
# 
#   task :start, :roles => :app do
#     run "cd #{current_path} && mongrel_rails cluster::configure -e production -p #{mongrel_port}0 -N #{mongrel_nodes} -c #{current_path} --user #{user} --group #{user}"
#     run "cd #{current_path} && mongrel_rails cluster::start"
#     run "rm -rf /home/#{user}/public_html;ln -s #{current_path}/public /home/#{user}/public_html"
#     run "mkdir -p #{deploy_to}/shared/config"
#     run "mv #{current_path}/config/mongrel_cluster.yml #{deploy_to}/shared/config/mongrel_cluster.yml"
#     run "ln -s #{deploy_to}/shared/config/mongrel_cluster.yml #{current_path}/config/mongrel_cluster.yml"
#   end
# 
#   task :restart, :roles => :app do
#     run "ln -s #{deploy_to}/shared/config/mongrel_cluster.yml #{current_path}/config/mongrel_cluster.yml"
#     run "cd #{current_path} && mongrel_rails cluster::restart"
#   end
# 
# end

# ========================
# For mod_rails apps
# ========================
# This assumes that your database.yml file is NOT in subversion,
# but instead is in your deploy_to/shared directory. Database.yml
# files should *never* go into subversion for security reasons.

# namespace :deploy do
#   task :start, :roles => :app do
#     run "touch #{deploy_to}/current/tmp/restart.txt"
#   end
#   
#   task :restart, :roles => :app do
#     run "touch #{deploy_to}/current/tmp/restart.txt"
#   end
# 
#   task :after_symlink, :roles => :app do
#     run "rm -f ~/public_html;ln -s #{deploy_to}/current/public ~/public_html"
#     run "ln -s #{deploy_to}/shared/database.yml #{deploy_to}/current/config/database.yml"
#   end
# end

3. Commit Application to SVN

Now that you have your deploy.rb file and Capfile configured, you need to make sure that you have committed the most recent changes of your app to your SVN repository before attempting any deployment. If you're not already sure what to do here, it is highly recommended that you go through the following tutorials before continuing your Rails application deployment: Single-User SVN Repository Setup > Multi-User SVN Repository Setup


4. Deploy Application

With your deploy.rb file and Capfile configured and committed to Subversion, you can now deploy your app. If this is the first time deploying your app using Capistrano you will need to run the following from your Rails root on your development machine:

cap deploy:setup
This will merely create the directory structure in your HostingRails account, based upon the configuration you set in the :deploy_to variable.

Next issue:

cap deploy:cold
This will checkout a copy of your app and copy it to the deploy directory. If you are using Mongrel, or a Mongrel Cluster, they will be started. FCGI is always running on HostingRails servers so you don't need to start FCGI.

At this point your app will be deployed and will be live.

Verify that the following directories exist on the server:

~/apps/<projectname>/shared/log
~/apps/<projectname>/shared/pids
~/apps/<projectname>/shared/system
If they do not, you can go ahead and create them with mkdir -p.  If they do not exist, you'll run into problems running the reaper.

As you make subsequent changes to your app you can deploy them using:

cap deploy
This will restart FCGI, Mongrel, or the Mongrel Cluster used to serve your app.

If you have migrations that need to be run then run:

cap deploy:migrations

Capistrano has a number of other tasks, and allows you to customize your own tasks. Running cap -T from your Rails root will give print a list of tasks and how to view the description of these tasks. As mentioned above, Capistrano also allows you to set different methods for deployment. If you would like to export, instead of checkout, your SVN repository, use SFTP, or even zip or tar your app, and copy it to the server, Capistrano can make it simple for you.

For more information on Capistrano, visit www.capify.org.

Troubleshooting
Capistrano's website has some great documentation on implementing and optimizing Capistrano with Rails.  A good place to start is with this article.

Happy Railing! Happy Capping!" " " " ""



Hello Guest! In order to edit this article you must be an active client with us, please log in or sign up today!





Contributing Author(s):
Willc
Bitbutter
Jeremedia
Wsargent
Damartman
William
Ghens
Akira
Goldy
Bartocc
Oma