Capistrano Mailer v3.1.0 (20090917)
* For Capistrano Deployment Email Notification
* It is a Capistrano Plugin / Ruby Gem that requires ActionMailer
Ever wanted to be emailed whenever someone on the team does a cap deploy of trunk or some tag to some server.
Wouldn’t it be nice to know about it every time a release was deployed? For large rails projects this type of coordination is essential, and this plugin makes sure everyone on the need to know list is notified when something new is deployed.
This plugin/gem is an extension to Capistrano.
That means it registers itself with Capistrano as a plugin and is therefore available to call in your recipes.
If you are looking to roll your own email integration into capistrano then try this pastie: pastie.org/146264 (thanks to Mislav Marohnić). But if you want to take the easy road to riches then keep reading ;)
-- figurative "riches" of course, I promise nothing in return for your using this plugin
Important Note: The first time you deploy to a server (a ‘cold’ deploy) capistrano mailer will cause an error because it uses capistrano’s previous release variables, and when there are no previous releases capistrano throws an error. In the next version this will be fixed, just don’t have time at the moment. If you would like to work on this ‘first deploy’ problem please fork my repo and work on it!
Home Page
github.com/pboling/capistrano_mailer/tree/master
Requirements
* at least Rails 1.2.6 (might work with older versions, but has not been tested)
* at least Capistrano 2.4.3 (might work with capistrano as old as 2.1.0, but has not been tested)
* Known to be compatible with SCMs as of version 3.1.0: Perforce, SVN
* Known to be compatible with, but does not require, the deprec gem.
Installation
Gem Using Git building from source:
mkdir -p ~/src
cd ~/src
git clone git://github.com/pboling/capistrano_mailer.git
cd capistrano_mailer
gem build capistrano_mailer.gemspec
sudo gem install capistrano_mailer-3.0.3.gem # (Or whatever version gets built)
Then cd to your rails app to optionally freeze the gem into your app:
rake gems:freeze GEM=capistrano_mailer
# You do NOT need to add a config.gem line to environment.rb for capistrano mailer.
Installing Gem from Github’s Gem Server:
gem sources -a http://gems.github.com
sudo gem install pboling-capistrano_mailer
# You do NOT need to add a config.gem line to environment.rb for capistrano mailer.
Plugin using Git:
# Installation as plugin might work... I haven't tried it.
./script/plugin install git://github.com/pboling/capistrano_mailer.git
Using SVN (deprecated, repository is no longer updated):
./script/plugin install http://capistrano-mailer.googlecode.com/svn/trunk/capistrano_mailer
Upgrading
From version 2.1.0 to version 3.x.x:
-
Update the way CapistranoMailer is configured using the new method: CapMailer.configure_capistrano_mailer, see below.
-
Update the require statement at the top of deploy.rb, see below (note for plugin change from capostrano_mailer to capistrano/mailer).
-
Change the mailer.send to mailer.send_notification_email in your cap recipe.
Usage
1. Install as gem or plugin.
2. Add this line to the top of your deploy.rb:
# For gem:
require 'capistrano/mailer'
# For plugin:
require 'vendor/plugins/capistrano_mailer/lib/capistrano/mailer'
3. Add a cap_mailer_settings.rb file to your config/ directory:
# If installed as a plugin might need the require here as well
ActionMailer::Base.delivery_method = :smtp
ActionMailer::Base.smtp_settings = {
:address => "mail.example.com",
:port => 25,
:domain => 'default.com',
:perform_deliveries => true,
:user_name => "[email protected]",
:password => "mypassword",
:authentication => :login }
ActionMailer::Base.default_charset = "utf-8"# or "latin1" or whatever you are using
CapMailer.configure_capistrano_mailer do |config|
config[:recipient_addresses] = ["[email protected]"]
# NOTE: THERE IS A BUG IN RAILS 2.3.3 which forces us to NOT use anything but a simple email address string for the sender address.
# https://rails.lighthouseapp.com/projects/8994/tickets/2340
# Therefore %("Capistrano Deployment" <[email protected]>) style addresses may not work in Rails 2.3.3
config[:sender_address] = "[email protected]"
config[:subject_prepend] = "[EMPTY-CAP-DEPLOY]"
config[:site_name] = "Empty Example.com App"
config[:email_content_type] = "text/html" # OR "text/plain" if you want the plain text version of the email
end
4. Add these two tasks to your deploy.rb:
namespace :show do
desc "Show some internal Cap-Fu: What's mah NAYM?!?"
task :me do
set :task_name, task_call_frames.first.task.fully_qualified_name
#puts "Running #{task_name} task"
end
end
namespace :deploy do
...
desc "Send email notification of deployment (only send variables you want to be in the email)"
task :notify, :roles => :app do
show.me # this sets the task_name variable
mailer.send_notification_email([
:rails_env => rails_env,
:host => host,
:task_name => task_name,
:application => application,
:repository => repository,
:scm => scm,
:deploy_via => deploy_via,
:deploy_to => deploy_to,
:revision => revision,
:real_revision => real_revision,
:release_name => release_name,
:version_dir => version_dir,
:shared_dir => shared_dir,
:current_dir => current_dir,
:releases_path => releases_path,
:shared_path => shared_path,
:current_path => current_path,
:release_path => release_path,
:releases => releases,
:current_release => current_release,
:previous_release => previous_release,
:current_revision => current_revision,
:latest_revision => latest_revision,
:previous_revision => previous_revision,
:run_method => run_method,
:latest_release => latest_release,
],[ # Send some custom vars you've setup in your deploy.rb to be sent out with the notification email!
# will be rendered as a section of the email called 'Release Data'
#:some_other_var1 => some_other_var1,
#:some_other_var2 => some_other_var2,
#:some_other_var3 => some_other_var3
],[ # Send some more custom vars you've setup in your deploy.rb to be sent out with the notification email!
# will be rendered as a section of the email called 'Extra Information'
#:some_other_var4 => some_other_var4,
#:some_other_var5 => some_other_var5,
#:some_other_var6 => some_other_var6
],[ # and even more!!!
# these will not be rendered as a section, but will be passed to the email template in the @data hash,
# and be available there if you want to write your own template
]
)
end
...
end
Make _sure_ you've defined `rails_env`, `repository`, `deploy_to`, `host`, and `application`.
task_name is defined by the show:me task above, and the others are defined behind the scenes by Capistrano!
The only parameter to mailer.send_notification_email that is *required* is the first array of hashes, and _minimally_ it needs the keys:
:rails_env
:repository
:task_name (provided by the show:me task included in this readme)
:deploy_to
:host
:application
If anyone has a cool way of recording the *output* into a capistrano accessible variable,
so that it can be shoved into the release email that would be an excellent contribution!
5. Then add the hook somewhere in your deploy.rb:
after "deploy", "deploy:notify"
6. Enjoy and Happy Capping!
7. Customization
If you want to use your own views you'll need to recreate the notification_email view:
First you need to define where your templates are:
CapMailer.configure_capistrano_mailer do |config|
config[:template_root] = "app/views/capistrano_mailer/"
end
Then you'll need to create templates there called:
notification_email.text.html.erb
and / or
notification_email.text.plain.erb
Take a look at the templates that comes with the plugin to see how it is done (views/cap_mailer/...)
This plugin is a collaboration between Sagebit, LLC (http://www.sagebit.com) and Peter Boling (http://www.peterboling.com).
Written initially while Peter Boling was working at Sagebit for use in various projects.
Author: Peter Boling, peter.boling at gmail dot com
Copyright (c) 2009 Peter Boling of 9thBit LLC, released under the MIT license
Copyright (c) 2007-8 Sagebit LLC, released under the MIT license