mintdigital / caplets

Capistrano Super Powers

Caplets

Capistrano is old and busted, right? Time to move on? WRONG! Caplets makes capistrano the new hotness once again. It bring capistrano into the future with all your favorite goodies: git, bundler, unicorn, and more.

WARNING: Caplets has evolved out of Mint Digital's real-world deployments of many large Rails/Rack applications. Although we have tried to keep it as generic and customizable as possible, it is still very opinionated. That is to say, it is largely tailored to how we like to deploy applications. If caplets is missing something important to you, submit an issue or fork away.

Quickstart

$ gem install caplets

# config/deploy.rb
require 'caplets'
load 'caplets/memcached'
load 'caplets/whenever'
# etc...

Roles

Caplets depends heavily on capistrano's concept of server roles to apply tasks only to the servers that require them. Most often, your sever definitions will look like this:

server 'app1.mintdigital.com',
  :app, :memcached, :sphinx, :assets,
  :primary => true

Modules

Caplets is a series of loadable capistrano extensions. This given you maximum flexibility in your deployments without having to remember to set/unset loads of capistrano variables. Only the tasks you need get run.

See the MODULES file for descriptions of all the available modules, along with what tasks they add and what variables they use.

caplets/deploy

The one module you will always get, even if you just require caplets/basic is caplets/deploy. This file is the heart of caplets; it sets up the essentials of what caplets considers a modern deployment.

The biggest change to the standard capistrano setup is that we use git to manage releases. Let me say that again as it's important:

** Instead of using subdirectories and symlinks to manage releases, caplets uses git.**

That means:

• You will not have releases or shared directories.
• Your code will be directly inside your :deploy_to directory.
• :current_path, :current_release, :release_path, :latest_release, and :shared_path will all be the same.
• Rollbacks still work, through the power of git reset
• "shared" files are really just files written to your project root but not under git version control -- no symlinks needed.

Here are a few other changes that caplets/deploy makes:

• :use_sudo is false by default
• :rails_env is replaced with :environment, which caplets expects you to set in your deploy file.
• :user and :group default to deploy
• :shared_children is not used. Use :required_children instead.
• The standard deploy task is disabled. Use deploy:quick to do an deploy:update + deploy:reload. Load caplets/db for caplets' replacement deploy:migrations task.
• Capistrano's built-in deploy:web:enable and deploy:web:disable are disabled. Load caplets/web for caplets' replacements.

require 'caplets'

Requiring caplets gets you the most common modules in one go. If you don't want them all, you can always require caplets/basic instead.

# config/deploy.rb
require 'caplets'

# Equivalent to...
require 'caplets/basic'
load 'caplets/bundle'
load 'caplets/db'
load 'caplets/logs'
load 'caplets/web'
load 'caplets/yaml'

caplets's Issues

bin_cmd variable needs set

Used in caplets/whenever but only defined in caplets/bundler

Use 'bundle check'

bundle check || bundle install

If no commits will be deployed, ask for confirmation

This should warn if we've forgotten to merge commits-to-be-deployed into the branch-to-be-deployed.

If git fetch fails, don't pretend everything is fine.

Expand thinking-sphinx config support

Set :sphinx_port and such.

cap deploy:rollback fails due to wrong git version

The git version on the destination server is 1.5.4.3

The error I get on deploy:rollback is this:

• executing `deploy:rollback:cleanup'
• executing "cd {my dir} ; git reflog delete --rewrite HEAD@{1} ; git reflog delete --rewrite HEAD@{1}"
  servers: ["my-server.net"]
  [my-server.net] executing command
  ** [out :: my-server.net] usage: git-reflog (expire | ...)
  command finished
  failed: "sh -c 'cd {my dir} ; git reflog delete --rewrite HEAD@{1} ; git reflog delete --rewrite HEAD@{1}'" on my-server.net

Support bundling app server

In particular, unicorn will use whatever version of rack is the latest on the system, even if your app has a dependency on a earlier version (such as Rails 2.3.5 / Rack 1.0.x). This makes bad things happen.

Bundling unicorn and using "gem exec" should fix it.

See 0.99.0 section of http://unicorn.bogomips.org/NEWS.html

Where is deploy:passenger:reload?

Oh, that's right: it's a typo.