====== Capistrano Deployment Essentials ======

Below is a guide to the standard Capistrano tasks as augmented by the Brightbox gem.


===== deploy =====

''deploy'' is the standard task for running a deployment. This:

  * creates a new release
  * creates symbolic links to the shared directories and files
  * updates the application gems (if configured)
  * moves the ''current'' symbolic link to the new release.
  * cleans up old releases
  * restarts the mongrels to pick up the new release.
  * ensures that the mongrels are being watched by monit.
  * restarts the web server if deploying for the first time.

===== deploy:check =====

''deploy:check'' checks to make sure you have everything on your system necessary for a successful deployment. If you have specified extra dependencies in your ''config/deploy.rb'' these will be checked as well.

Be warned that there is a bug in Capistrano 2.3.0 that stops this task working if you have ''set :scm, :none'' in your ''config/deploy.rb''.

===== deploy:cleanup =====

Keeps the latest five releases of the application and deletes the rest.


===== deploy:cold =====

Like ''deploy'' but creates the database and runs migrations. Designed for first time deployment of an application. You may be better of with ''deploy:initial'' which runs ''deploy:setup'' followed by ''deploy:cold''

  * creates a new release
  * creates symbolic links to the shared directories and files
  * updates the application gems (if configured)
  * moves the ''current'' symbolic link to the new release.
  * cleans up old releases
  * checks the database config and warns of any missing or incorrect details
  * creates the database (if configured and missing)
  * runs the migrations on the database.
  * starts the mongrels to pick up the new release.
  * ensures that the mongrels are being watched by monit.
  * restarts the web server
===== deploy:initial =====

Runs ''deploy:setup'' followed by ''deploy:cold''

If this is the first release on the server and the rails app is using Passenger, it also restarts Apache to make sure Apache knows about this new application. This means any other rails applications under Apache are also restarted at the same time.

===== deploy:migrate =====

This runs the migration task on the existing release. Check you don't want ''deploy:migrations'' instead.

  * checks the database config and warns of any missing or incorrect details
  * creates the database (if configured and missing)
  * runs the migrations on the database.

===== deploy:migrations =====

''deploy:migrations'' runs a deployment and migrates the database.

  * creates a new release
  * creates symbolic links to the shared directories and files
  * updates the application gems (if configured)
  * moves the ''current'' symbolic link to the new release.
  * cleans up old releases
  * checks the database config and warns of any missing or incorrect details
  * creates the database (if configured and missing)
  * runs the migrations on the database
  * restarts the mongrels to pick up the new release
  * ensures that the mongrels are being watched by monit
  * restarts the web server if deploying for the first time

===== deploy:monit:reload =====

Reloads the monit configuration on the server. 

===== deploy:pending =====

Displays the commits that have happened on your SCM since the last deployment.

===== deploy:pending:diff =====

Shows the diff between what is running on the server and what has been committed into your SCM.

===== deploy:restart =====

This stops and starts the application layer, and the new processes are monitored by monit.

===== deploy:rollback =====

''deploy:rollback'' goes back to a previous version.

  * removes the latest version of the code
  * changes the ''current'' pointer to the previous version of the code
  * restarts the mongrels picking up the new ''current'' version.
  * ensures monit is watching the mongrels.

===== deploy:rollback_code =====

''deploy:rollback_code'' goes back to a previous version but without restarting. You probably want ''deploy:rollback'' instead.
===== deploy:setup =====

''deploy:setup'' creates or recreates the directory structure for the application and setup up the configuration. Consider ''deploy:initial'' if you are deploying a new application.

  * creates the capistrano release layout
  * creates any shared directories.
  * creates configurations for apache, nginx, mongrels, logrotate and monit.
  * activates the necessary modules in apache to support the configuration.

With Brightbox Gem v2.3.6 or above you can ''set :generate_webserver_config, false'' in your ''deploy.rb'' to stop ''deploy:setup'' (or any task that calls it) from regenerating the apache & nginx configs.

===== deploy:start =====

''deploy:start'' starts up the application layer and switches on monitoring.

===== deploy:status =====

''deploy:status'' shows the status of the application layer.

===== deploy:stop =====

''deploy:stop'' switches off the application layer and turns off monitoring. It doesn't disable the web layer configuration though - see ''deploy:disable''

===== deploy:symlink =====

Updates the ''current'' link to the latest version of code. 

===== deploy:update =====

Deploys the latest version and updates the symlink without restarting the mongrels. You probably want ''deploy''.

===== deploy:update_code =====

''deploy:update_code'' deploys new version of the code.

  * creates an new version of the code
  * Links into the shared area
  * updates the gems.