Deploy Resource

Actions

Attributes

Providers

Discussion

The Deploy Strategies

The deploy resource is ported from Capistrano and works similarly. In your deploy directory, you will need to create a subdirectory named shared, where your configuration and temporary files will be kept. For a rails application, you will typically have config, log, pids, and system directories within the shared directory to keep the files stored there independent of the code in your source repository. In addition to these, the deploy process will create subdirectories named releases and current in your deploy directory. The releases directory holds up to the five most recently deployed versions of your application, and the current directory will be a link to the currently released version.

Deployment happens in four phases, checkout, migrate, symlink, and restart. When the deploy is run, Chef uses the SCM resource to get the specified revision, placing the clone or checkout in a subdirectory of the deploy directory named cached-copy. A copy of your application is then placed in a subdirectory under the releases directory. More on this below.

Next, if a migration is to be run, Chef symlinks the database configuration file in to the checkout, by default config/database.yml, into the checkout and runs the migration command. For a rails application, migration_command is usually set to rake db:migrate

After migration, the symlink proceeds by removing directories for shared and temporary files from the checkout, by default log, tmp/pids, and public/system. After this step, any needed directories, by default tmp, public, and config, are created if they don't yet exist. The symlink step completes by symlinking shared directories into the current release, public/system, tmp/pids, and log by default, and then symlinking the release directory to current.

Following the symlink step, the application is restarted according to the restart command set in the recipe.

Timestamped Deploy

The two available deploy providers mainly differ in how they name the directories that contain your releases. Although the difference might seem minor, it has a large effect on how the deployment behaves.

The "timestamped" deploy strategy is the default. It names release directories with a timestamp of the form "YYYYMMDDHHMMSS". For example, your release might be located at the path /my/deploy/dir/releases/20040815162342.

The deploy provider determines whether or not to deploy your code based on the existence of the release dir it is attempting to deploy to. Because the timestamp will be different for every chef run, the timestamped deploy provider is not idempotent. If you choose to use this deployment strategy, you will to manually manage the action setting on the resource to prevent unintended continuous deployment.

Deploy Revision

Although the "revision" deploy strategy is not the default for compatibility reasons, it is the recommended strategy. With this strategy, the release subdirectory will be named after the revision id used by your SCM. For git users, this will be the familiar SHA checksum; For subversion users, it will be the integer revision number. Note that even if you supply a branch name, tag, or other name instead of the revision id, Chef will lookup the revision id from your SCM and name this directory with the revision id.

As noted above, the deploy providers determine whether or not to deploy based on whether or not the releases directory it is trying to deploy to exists. This means that deploy_revision will be completely idempotent if you specify an exact revision to deploy. You could also use this in more interesting ways, for example, if you have a "deploy" or "production" branch in git, you can set the provider to track this branch. This will cause your deployment to get updated the next time chef runs after pushing to that branch.

The drawback to the revision deploy strategy is that if the deploy fails for any reason, and you want to re-deploy with the same code, you'll need to manually set the action to :force_deploy. Forcing a deploy will remove the old release directory and then proceed with the deployment as usual. Be forewarned that this can cause downtime if you force a deployment over the current release.

The deployed revisions are stored in (file_cache_path)/revision-deploys/(deploy_path)

Interacting with Your Infrastructure During Deployment

In between each step of the deployment process, you can run arbitrary ruby or chef code using callbacks. The available callbacks are:

• before_migrate
• before_symlink
• before_restart
• after_restart
• restart_command supports embedded recipes given in a block, but assumes a shell command (instead of a deploy hook filename) when given a string.

Each of these callbacks can be used in one of three ways:

• You can pass a block:
  callback_blocks
• You can specify a file. Files are searched relative to the current release. The code in the file is evaluated exactly as if you had put that code in a block.
  callback_files
• If you don't provide a block or file, Chef will look for a file in the current checkout named deploy/callback_name.rb, such as deploy/before_migrate.rb. If it exists, it will be evaluated as above.

Within your callbacks, there are several ways to get access to information about the deployment. As shown in the example above, you can use release_path to get the path to the current release. You can access the deploy resource itself using the new_resource method, allowing you to access the environment variables you've set. If you've relied on access to an @configuration variable using the original chef-deploy gem, you can continue to use that as well, however, new_resource is the preferred way. These are all available only at the "top level" within callbacks, so you need to assign any values you intend to use to local variables as shown in the callback_blocks example above.

Custom Application Layouts

By default, the deploy resource expects your application to be structured like a rails app, but you can customize the layout for any kind of application.

• symlink_before_migrate
  symlink_before_migrate is a hash mapping files in the shared directory to files in the current release. The primary use is to link required configuration files into place so they're available during the migration step. The default is
  {"config/database.yml" => "config/database.yml"}
• purge_before_symlink
  purge_before_symlink is an array of directories which will be removed before the symlink step. This removes directories before the production copy from the shared directory is symlinked in. Defaults to
  ["log", "tmp/pids", "public/system"]
• create_dirs_before_symlink
  This list is used to create directories that need to exist in the release before the symlink step. To illustrate in the context of a rails app, you might use .gitignore to keep all tempfiles out of your repository and not have the tmp/ directory in your checked out code, but the symlink step will create a symlink from shared/pids to RELEASE/tmp/pids. Since this would fail if the RELEASE/tmp directory did not exist, the directory must be created for the deploy to proceed. Note that it is not necessary to create directories that will be symlinked in the symlink step, such as log/, as these don't rely on the existence of other directories in the release. Directories that already exist won't be overwritten. Defaults:
  ["tmp", "public", "config"]
• symlinks
  symlinks is a hash mapping files and directories from their locations in the shared dir to locations in the release dir, used in the main symlinking step. Defaults to
  {"system" => "public/system", "pids" => "tmp/pids", "log" => "log"}

Examples

Basic attribute usage is shown here:

Any recipes using the git-deploy gem can continue using the same API:

The layout of the application matches a Rails app by default, but you can customize it to fit your needs:

Using resources from within your callbacks as blocks or within callback files distributed with your application's source code:

Open Issues

• Only One Level of Submodules
  If you have submodules that themselves depend on submodules, the second level of submodules won't be initialized/updated. See the comments below.
• Directories are Assumed to Exist (CHEF-630)
  You'll need to have most of the directories needed by deploy already created before the deploy runs.