====== 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''

===== 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.

===== 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.