h1. deploy

 "home":../index.html > "recipes":index.html >  deploy  


h2. Namespaces

* "deploy:pending":deploy-pending.html (2) 
* "deploy:web":deploy-web.html (2) 


h2. Tasks

* "deploy":#deploy 
* "deploy:check":#deploy:check 
* "deploy:cleanup":#deploy:cleanup 
* "deploy:cold":#deploy:cold 
* "deploy:finalize_update":#deploy:finalize_update 
* "deploy:migrate":#deploy:migrate 
* "deploy:migrations":#deploy:migrations 
* "deploy:restart":#deploy:restart 
* "deploy:rollback":#deploy:rollback 
* "deploy:rollback_code":#deploy:rollback_code 
* "deploy:setup":#deploy:setup 
* "deploy:start":#deploy:start 
* "deploy:stop":#deploy:stop 
* "deploy:symlink":#deploy:symlink 
* "deploy:update":#deploy:update 
* "deploy:update_code":#deploy:update_code 
* "deploy:upload":#deploy:upload 


h2. Task documentation

h3(#deploy). deploy

Deploys your project. This calls both `update' and `restart'. Note that     this will generally only work for applications that have already been deployed     once. For a "cold" deploy, you'll want to take a look at the `deploy:cold'     task, which handles the cold start specifically.



h3(#deploy:check). deploy:check

Test deployment dependencies. Checks things like directory permissions,     necessary utilities, and so forth, reporting on the things that appear to     be incorrect or missing. This is good for making sure a deploy has a     chance of working before you actually run `cap deploy'.

You can define your own dependencies, as well, using the `depend' method:

  depend :remote, :gem, "tzinfo", ">=0.3.3"
  depend :local, :command, "svn"
  depend :remote, :directory, "/u/depot/files"



h3(#deploy:cleanup). deploy:cleanup

Clean up old releases. By default, the last 5 releases are kept on each     server (though you can change this with the keep_releases variable). All     other deployed revisions are removed from the servers. By default, this     will use sudo to clean up the old releases, but if sudo is not available     for your environment, set the :use_sudo variable to false instead.



h3(#deploy:cold). deploy:cold

Deploys and starts a `cold' application. This is useful if you have not     deployed your application before, or if your application is (for some     other reason) not currently running. It will deploy the code, run any     pending migrations, and then instead of invoking `deploy:restart', it will     invoke `deploy:start' to fire up the application servers.



h3(#deploy:finalize_update). deploy:finalize_update

[internal] Touches up the released code. This is called by update_code     after the basic deploy finishes. It assumes a Rails project was deployed,     so if you are deploying something else, you may want to override this     task with your own environment's requirements.

This task will make the release group-writable (if the :group_writable     variable is set to true, which is the default). It will then set up     symlinks to the shared directory for the log, system, and tmp/pids     directories, and will lastly touch all assets in public/images,     public/stylesheets, and public/javascripts so that the times are     consistent (so that asset timestamping works).



h3(#deploy:migrate). deploy:migrate

Run the migrate rake task. By default, it runs this in most recently     deployed version of the app. However, you can specify a different release     via the migrate_target variable, which must be one of :latest (for the     default behavior), or :current (for the release indicated by the     `current' symlink). Strings will work for those values instead of symbols,     too. You can also specify additional environment variables to pass to rake     via the migrate_env variable. Finally, you can specify the full path to the     rake executable by setting the rake variable. The defaults are:

  set :rake,           "rake"
  set :rails_env,      "production"
  set :migrate_env,    ""
  set :migrate_target, :latest



h3(#deploy:migrations). deploy:migrations

Deploy and run pending migrations. This will work similarly to the     `deploy' task, but will also run any pending migrations (via the     `deploy:migrate' task) prior to updating the symlink. Note that the     update in this case it is not atomic, and transactions are not used,     because migrations are not guaranteed to be reversible.



h3(#deploy:restart). deploy:restart





h3(#deploy:rollback). deploy:rollback

Rolls back to a previous version and restarts. This is handy if you ever     discover that you've deployed a lemon; `cap rollback' and you're right     back where you were, on the previously deployed version.



h3(#deploy:rollback_code). deploy:rollback_code

Rolls back to the previously deployed version. The `current' symlink will     be updated to point at the previously deployed version, and then the     current release will be removed from the servers. You'll generally want     to call `rollback' instead, as it performs a `restart' as well.



h3(#deploy:setup). deploy:setup

Prepares one or more servers for deployment. Before you can use any     of the Capistrano deployment tasks with your project, you will need to     make sure all of your servers have been prepared with `cap setup'. When     you add a new server to your cluster, you can easily run the setup task     on just that server by specifying the HOSTS environment variable:

  $ cap HOSTS=new.server.com setup

It is safe to run this task on servers that have already been set up; it     will not destroy any deployed revisions or data.



h3(#deploy:start). deploy:start





h3(#deploy:stop). deploy:stop





h3(#deploy:symlink). deploy:symlink

Updates the symlink to the most recently deployed version. Capistrano works     by putting each new release of your application in its own directory. When     you deploy a new version, this task's job is to update the `current' symlink     to point at the new version. You will rarely need to call this task     directly; instead, use the `deploy' task (which performs a complete     deploy, including `restart') or the 'update' task (which does everything     except `restart').



h3(#deploy:update). deploy:update

Copies your project and updates the symlink. It does this in a     transaction, so that if either `update_code' or `symlink' fail, all     changes made to the remote servers will be rolled back, leaving your     system in the same state it was in before `update' was invoked. Usually,     you will want to call `deploy' instead of `update', but `update' can be     handy if you want to deploy, but not immediately restart your application.



h3(#deploy:update_code). deploy:update_code

Copies your project to the remote servers. This is the first stage     of any deployment; moving your updated code and assets to the deployment     servers. You will rarely call this task directly, however; instead, you     should call the `deploy' task (to do a complete deploy) or the `update'     task (if you want to perform the `restart' task separately).

You will need to make sure you set the :scm variable to the source     control software you are using (it defaults to :subversion), and the     :deploy_via variable to the strategy you want to use to deploy (it     defaults to :checkout).



h3(#deploy:upload). deploy:upload

Copy files to the currently deployed version. This is useful for updating     files piecemeal, such as when you need to quickly deploy only a single     file. Some files, such as updated templates, images, or stylesheets,     might not require a full deploy, and especially in emergency situations     it can be handy to just push the updates to production, quickly.

To use this task, specify the files and directories you want to copy as a     comma-delimited list in the FILES environment variable. All directories     will be processed recursively, with all files being pushed to the     deployment servers. Any file or directory starting with a '.' character     will be ignored.

  $ cap deploy:upload FILES=templates,controller.rb