Please add your own "newbie" questions here. 
 

• What is Capistrano?

 Capistrano is a general tool that allows you to control 1, 2, 3, hundreds, or even thousands of remote machines by running a Ruby script on your local machine.  Capistrano provides a domain specific language Ruby interface for grouping together tasks and running those commands on groups of remote servers.  You can group system administration commands into tasks, and group tasks into name spaces.  These tasks become events, and servers are grouped into roles.  This allows you to apply groups of tasks to groups of servers through a programmer-friendly high-level interface.  The net effect is a powerful tool that lets you be the conductor of a hundred or thousand servers, orchestrating massive amounts of computing power, disk space, databases, and bandwidth from your tiny little laptop at home.

• What can I use it for?

 You can use it for automating tedious series of commands that you would normally have to type into the command console in an SSH or putty.exe session.  Some possible applications include:

- automating Ruby on Rails application deployments on a single server.

- automating Ruby on Rails application deployments on a server farm.

- dynamically managing server farms on Amazon\47s electronic computing cloud.

- synching your work computer with your home computer with your school computer.

- automating Selenium regression testing tasks on your LAN.

• Why is it cool? 

Capistrano is cool because it closes the gap between concept and implementation.  It saves your time and brain power so that you can focus on your cool ideas.  It also allows you to harness the power of massive amounts of computing power if you have access to a lot of remote servers.

 

• After typing in "capify myapp" locally, a bunch of Capistrano tasks are loaded by default (see below).  Where are these tasks defined?

 

cap deploy               # Deploys your project.
cap deploy:check         # Test deployment dependencies.
cap deploy:cleanup       # Clean up old releases.
cap deploy:cold          # Deploys and starts a `cold\46#39; application.
cap deploy:migrate       # Run the migrate rake task.
cap deploy:migrations    # Deploy and run pending migrations.
cap deploy:pending       # Displays the commits since your last deploy.
cap deploy:pending:diff  # Displays the `diff\46#39; since your last deploy.
cap deploy:rollback      # Rolls back to a previous version and restarts.
cap deploy:rollback_code # Rolls back to the previously deployed version.
cap deploy:setup         # Prepares one or more servers for deployment.
cap deploy:stop          # Stop the application servers.
cap deploy:symlink       # Updates the symlink to the most recently deployed ...
cap deploy:update        # Copies your project and updates the symlink.
cap deploy:update_code   # Copies your project to the remote servers.
cap deploy:upload        # Copy files to the currently deployed version.
cap deploy:web:disable   # Present a maintenance page to visitors.
cap deploy:web:enable    # Makes the application web-accessible again.
cap invoke               # Invoke a single command on the remote servers.
cap shell                # Begin an interactive Capistrano session.

 

For me (OS X 10.4 using MacPorts), they are defined in 

/opt/local/lib/ruby/gems/1.8/gems/capistrano-2.1.0/lib/capistrano/recipes/deploy.rb  (Is this right?)

In general, `gem env gempath` will show the paths.  In this case "/opt/local/lib/ruby/gems/1.8" is one of those paths.  

 

On Leopard I see /System/Library/Frameworks/Ruby.framework/Versions/1.8/usr/lib/ruby/gems/1.8 and /Library/Ruby/Gems/1.8

• How can we modify, enhance or rewrite these tasks on a per application basis?

        Override them (perhaps copying from the gem).  For example, to redefine your deploy:setup task you could  put in your application\46#39;s Capfile:

namespace :deploy do

  task :setup, :hosts =\46gt; "www.capify.org" do
    run "cd; mkdir apps/dont_do_this_at_home/current"
  end 

end 

• Is there a way to modify these tasks and have them be applied to all future apps that are capified? 

 

• How do I make it so that I don\47t have to type in the SVN password everytime I deploy?

Add to your config/deploy.rb:

set :scm_username, "mike"
set :scm_password, "secret"

• Where can I see a sample working deploy.rb file for my host?  (TODO: add a link here to a list of deploy.rb files per host.)

There is a working deploy.rb file and Capfile posted for RailsPlayground.net in the files section of the Capistrano Google group.  Please contribute your working deploy.rb file and Capfile files there too.  This will help other people resolve host-specific weirdness and save people lots of time.

• Where are the files put when you install capistrano (ie. "gem -y install capistrano") 

Use `gem env gempath` to discover where gems are installed.

 

 For example, on OS X 10.4.11 using MacPorts, you will find the Capistrano 2.1 files here:

   /opt/local/lib/ruby/gems/1.8/gems/capistrano-2.1.0/

• What files are created when you capify your individual application?  (ie. "cap myapp" or "cap ." in your rails root directory.)

 In Capistrano 2.1, /config/deploy.rb and /Capfile are created in your rails application root directory.  Deploy.rb sets all the systems specific variables, and Capfile stores all your tasks.  If you capify your application, a bunch of built-in tasks are available to you.  For me, they are defined in 

/opt/local/lib/ruby/gems/1.8/gems/capistrano-2.1.0/lib/capistrano/recipes/deploy.rb  (Is this right?)

 

`cap -T` will list the predefined tasks, and for any given task `cap -e task` will return documentation for the task. 

• What variables might I want to set in my deploy.rb for the benefit of the stock deploy tasks? 
• application - used to determine deployment path: /home/rails/$application
• repository - Specify your source control repository.  For subversion this will be a URL
• user - ??? dunno ... mine is set to root ???
• runner - spinner is invoked as this user
• use_sudo - set this to false to not do things using sudo (if user is \47root\47?)
• deploy_to - specify the deployment path (default /u/apps/#{application})
• deploy_via - specify the deployment strategy to use (:checkout, :copy, :export, :remote_cache) - read code in lib/capistrano/recipes/deploy/strategy
• copy_strategy - (:export, :checkout) - using export avoids the .svn overhead
• migrate_env - Pass extra environment data to rake db:migrate.  (E.g.: \46#39;RAILS_ENV=dbadmin\46#39; to use the dbadmin environment for migrations.) 
• gateway - useful when your deployment target servers are behind a firewall 
• ??? more ??? 
• Read deploy.rb in the capistrano gem for more   

 

• Is capistrano run locally or on your server?

Run capistrano on one machine (locally or a management console) to manage many others. 

• Does capistrano have to be installed on your server?

The capistrano gem should be installed on the machine you wish to run cap on.  It need not be installed on the many managed servers.

• Does capistrano work on Windows Vista?

Yes.

• What do I need to do to get Capistrano running on Windows XP or Windows Vista? 

- Install putty.exe.
- Append the path of putty.exe to your PATH variable. (Is this right?)