capistrano_mailer_railsless

= Capistrano Mailer

• For Capistrano Deployment Email Notification
• It is a Capistrano Plugin / Ruby Gem that requires ActionMailer
• It is MIT-LICENSE (License file is in source only for now because github won't build the gem if it is bundled with the gem... ?)

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: http://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

http://github.com/pboling/capistrano_mailer

== Credit where Credit is Due

• Thanks to Dustin Deyoung of Sagebit, LLC (http://www.sagebit.com) for the beautiful HTML email templates.

== Requirements

• 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.2: Perforce, SVN, and Git

• 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.1.6.gem # (Or whatever version gets built)

Gemcutter is the hot new gem host, and you can use it like this:

[sudo] gem install gemcutter [sudo] gem tumble # makes gemcutter gem source first in line, if you haven't already [sudo] gem install capistrano_mailer_railsless

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,

But in order to use the gems:freeze task you DO need to add it as a config.gem, at least temporarily.

Plugin using Git:

Installation as plugin works... but the setup is slightly different. (See Usage below)

./script/plugin install git://github.com/3crowd/capistrano_mailer_railsless.git

== Usage

1. Install as gem or plugin. You need to have already setup capistrano in the project, including the 'capify .' command.

2. Add this line to the top of your config/deploy.rb:

# For plugin:

#   You must make capistrano_mailer's libraries available in Ruby's load path.  This is one way to do that:
#   Add to the top of your config/deploy.rb file:
$:.unshift 'vendor/plugins/capistrano_mailer/lib'

# For frozen gem:
#   You must make capistrano_mailer's libraries available in Ruby's load path.  This is one way to do that:
#   Add to the top of your config/deploy.rb file:
$:.unshift 'vendor/gems/capistrano_mailer-x.x.x/lib'

# then for gem or plugin:
####################################
# Capistrano Plugins go here
require 'capistrano/mailer'
#configure capistrano_mailer:
# The configuration file can go anywhere, but in past versions of the gem it was required to be in the config/ dir.
require 'config/cap_mailer_settings'
####################################

3. Configure Caistrano Mailer in the settings file required in step 2:

# If installed as a plugin might need the require here as well

ActionMailer::Base.delivery_method = :smtp # or :sendmail, or whatever
ActionMailer::Base.smtp_settings = { # if using :smtp
    :address        => "mail.example.com", 
    :port           => 25, 
    :domain         => 'default.com', 
    :perform_deliveries => true,
    :user_name      => "[e-mail]", 
    :password       => "mypassword", 
    :authentication => :login }
ActionMailer::Base.default_charset = "utf-8"# or "latin1" or whatever you are using

CapMailer.configure do |config|
  config[:recipient_addresses]  = ["[e-mail]"]
  # 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" <[e-mail]>) style addresses may not work in Rails 2.3.3
  config[:sender_address]       = "[e-mail]"
  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(self)
  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. Minimally you need to define the capistrano variables: :rails_env :repository :task_name (provided by the show:me task included in this readme) :deploy_to :host :application

But there are tons of others - just take a look at lib/mailer/cap_mailer.rb.

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!

1. Then add the hook somewhere in your deploy.rb:

after "deploy", "deploy:notify"

1. Enjoy and Happy Capping!

2. 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/...)

== Authors

Peter Boling (pboling) - Wrote original Dave Nolan (textgoeshere) - lots of refactoring merged into 3.2 release Justin Lynn - removed rails specificity and defaults from codebase

== Contributors

Dustin Deyoung - HTML Email Templates mixonix - SCMs compatibility greut - SCMs compatibility

---

Modified by Justin Lynn to no longer require Rails, 3Crowd Technologies, Inc. (http://www.3crowd.com).

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) 2010 3Crowd Technologies, Inc. released under the MIT license Copyright (c) 2009 Peter Boling of 9thBit LLC, released under the MIT license Copyright (c) 2007-8 Sagebit LLC, released under the MIT license