There are two resources for deployment, the Deploy Resource - with extensive attributes available to specify use, and the SCM Resources - which can be used within the Deploy Resource, or independently.

There are many approaches and strategies that can be undertaken to use these resources for managing and automating deployment within your infrastructure. The discussion below goes over some of those approaches and provides some examples of use.

SCM Resources

Source Control Management (SCM) Resources, which may be used within the Deploy resource, or independently.

Actions

"sync" is the default action.

Attributes

Providers

SCM Examples

Did you need the absolute latest version of CouchDB?

Prefer the git mirror?

Want to use different branches depending on the environment of the node?

In the above example, the branch_name variable is being set to "staging" or "master" depending on the environment of the node. Once that is determined, it uses the branch_name variable to set the revision for the repository.

Keep in mind that if you use the command "git status" after running this recipe it will return the branch name as "deploy" regardless, as this is a default value. You should be able to see it checking out the correct branch when you run chef-client with debugging on:

Deploy Resource

A resource to help you manage and control your deployments. Please note the number of attributes available for specifying behavior, and review the Discussion for strategies and examples of use.

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.

1. 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.
2. 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
3. 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.
4. 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 need 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 deploy_revision resource results in deployed components under the destination location being owned by the user who runs the application. If this is an issue for your particular workflow, there are three approaches you can undertake:

• you'll need to incorporate changing permissions to their desired end state within your recipe, or
• add a before_restart block to fix up the permissions, or
• have an unprivileged user (e.g., "opscode") as the owner of the deploy directory, and another unprivileged user (e.g., "opscodeapp") run it. This is the approach we'd recommend.

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

All of the above callbacks support embedded recipes given in a block, but assume 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"}
  Note that if you try to do "symlink_before_migrate {}", the "{}" will be interpreted as a block rather than an empty hash. Instead, use "symlink_before_migrate({})" or "symlink_before_migrate nil".
• 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"}

How to Nuke and Start Over

Chef keeps track of the order in which you've deployed each revision of your application in a cache file. If you delete the deployed code from a box in order to force a redeployment, you need to delete this cache file as well. Under the default configuration, this cache file is located in /var/chef/cache/revision-deploys/APPNAME/

Deploy Examples

Basic attribute usage

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

When deploying non-rails code and you don't want any symlinks to the shared folder, use parentheses or Hash.new to avoid an ambiguity in Ruby

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. This issue is addressed with version 0.10.6+.
  
  
  
  

Resources

Yum Package Resource