rain 1.0.1

data/LICENSE.md

@@ -0,0 +1,20 @@
+Copyright 2012 eLocal USA, LLC
+
+Permission is hereby granted, free of charge, to any person obtaining
+a copy of this software and associated documentation files (the
+"Software"), to deal in the Software without restriction, including
+without limitation the rights to use, copy, modify, merge, publish,
+distribute, sublicense, and/or sell copies of the Software, and to
+permit persons to whom the Software is furnished to do so, subject to
+the following conditions:
+
+The above copyright notice and this permission notice shall be
+included in all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
+EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
+MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND
+NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE
+LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION
+OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION
+WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

data/README.md

@@ -0,0 +1,128 @@
+# Rain
+
+Rain is a deployment engine for Rails applications. It leverages
+Capistrano and Git to cleanly deploy new versions across multiple
+servers. Essentially a command-line interface to both of these tools,
+Rain emphasizes convention over configuration and attempts to make
+continuous deployment between teams more organized and therefore, more
+effective.
+
+Designed for [eLocal](http://elocal.com), it is
+currently in production use on several of our large applications. 
+
+## Installation
+
+Add to Gemfile
+
+```ruby
+gem 'rain'
+```
+
+Generate configuration
+
+```bash
+$ rake rain:config
+```
+
+This file tells Rain which versions are currently deployed. To start on
+a different version, edit the file.
+
+## Usage
+
+Rain is basically CLI glue for Capistrano and Git. In essence, it
+creates a new Git tag with the version number as the name, pushes that
+tag to `origin/master` (or whatever your default remote is), then
+commits the name of that tag to a `versions.yml` file (editing the one
+you created) and pushes that to your origin as well. When all is said
+and done, you'll have a commit in your master branch marking when the
+release occurred, as well as a tag on origin (and locally) with the
+exact commit that was deployed with Capistrano. It allows you to easily
+roll back changes without keeping a bunch of directories on the server
+filled with ancient app code, as well as see at-a-glance when new
+deployments occurred.
+
+Meant for deployment to two environments, it deploys the latest `HEAD`
+from Git's master branch to stage and the last released tag on stage to
+production.
+
+### Configuration
+
+Rain implies that you deploy to two environments, a **stage** for
+testing new changes on a real server, with real API calls, and the
+**production** environment which is where your application can be
+interacted with by its userbase.
+
+You need a `to_stage` and `to_production` task in your
+**config/deploy.rb** for whatever environment you wish to deploy. The Rails environment, task and environment in the versions.yml file must be the same name. This task will tell Capistrano which servers to deploy to before it runs its `deploy` task. It basically configures Capistrano on a per-environment basis. 
+
+Here's what one of your `to_env` tasks might like:
+
+```ruby
+desc "Let's gooooooooooooo"
+task :to_production do
+  set :user, "bruce"
+  set :rails_env, "production"
+
+  role :web,  "www.elocal.com"
+  role :app,  "dyno.elocal.com"
+  role :db,   "production.db.elocal.com", primary: true
+end
+```
+
+### Deploying
+
+Run the following command in your Terminal to deploy your app to every
+server listed in the `to_production` task:
+
+```bash
+$ rain on production
+```
+
+Rain uses [Semantic Versioning](http://semver.org), so it is possible to
+programatically increment the major or minor version instead of the
+patch, which is the default (but can be explicitly set with `--patch`).
+
+```bash
+$ rain on stage --minor
+$ rain on production --major
+```
+
+In a continuous deployment setting, it is best to establish rules
+for when minor or major versions are bumped. You can see the "best
+practice" rules established by semver.org if you run `rain help on`.
+
+## In The Wild
+
+We use this deployment script at [eLocal](http://elocal.com) to deploy a
+cluster of staging and production web app servers. Not only do we use it
+for our main site, but the API application as well, which was the
+primary motivation in developing this gem: the ability to share its code
+across all of our applications.
+
+## Contributors
+
+- [Tom Scott](http://github.com/tubbo)
+- [Rob Di Marco](http://github.com/robdimarco)
+
+## License
+
+    Copyright 2012 eLocal USA, LLC
+
+    Permission is hereby granted, free of charge, to any person obtaining
+    a copy of this software and associated documentation files (the
+    "Software"), to deal in the Software without restriction, including
+    without limitation the rights to use, copy, modify, merge, publish,
+    distribute, sublicense, and/or sell copies of the Software, and to
+    permit persons to whom the Software is furnished to do so, subject to
+    the following conditions:
+
+    The above copyright notice and this permission notice shall be
+    included in all copies or substantial portions of the Software.
+
+    THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
+    EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
+    MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND
+    NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE
+    LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION
+    OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION
+    WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

data/Rakefile

@@ -0,0 +1,38 @@
+#!/usr/bin/env rake
+begin
+  require 'bundler/setup'
+rescue LoadError
+  puts 'You must `gem install bundler` and `bundle install` to run rake tasks'
+end
+begin
+  require 'rdoc/task'
+rescue LoadError
+  require 'rdoc/rdoc'
+  require 'rake/rdoctask'
+  RDoc::Task = Rake::RDocTask
+end
+
+RDoc::Task.new(:rdoc) do |rdoc|
+  rdoc.rdoc_dir = 'rdoc'
+  rdoc.title    = 'Rain'
+  rdoc.options << '--line-numbers'
+  rdoc.rdoc_files.include('README.rdoc')
+  rdoc.rdoc_files.include('lib/**/*.rb')
+end
+
+
+
+
+Bundler::GemHelper.install_tasks
+
+require 'rake/testtask'
+
+Rake::TestTask.new(:test) do |t|
+  t.libs << 'lib'
+  t.libs << 'test'
+  t.pattern = 'test/**/*_test.rb'
+  t.verbose = false
+end
+
+
+task :default => :test

data/bin/rain

@@ -0,0 +1,11 @@
+#!/usr/bin/env ruby
+#
+# = Rain
+#
+# Usage: `rain on {RAILS_ENV}`
+
+$:.unshift File.join(File.dirname(__FILE__), *%w[.. lib])
+
+require 'rain'
+
+Rain::Deployer.start

data/lib/generators/rain/install/USAGE

@@ -0,0 +1,10 @@
+Description:
+    Generates the configuration file for Rain
+    and instructs the user on how to install
+    the Capistrano tasks.
+
+Example:
+    rails generate rain:install
+
+    This will create:
+        config/version.yml

data/lib/generators/rain/install/install_generator.rb

@@ -0,0 +1,24 @@
+module Rain
+  class InstallGenerator < Rails::Generators::Base
+    source_root File.expand_path('../templates', __FILE__)
+
+    def copy_config_file
+      copy_file "versions.yml", "config/versions.yml"
+    end
+
+    def show_capistrano_instructions
+      say <<-TEXT
+
+      Please add `require 'rain/capistrano'` to Capfile and
+      define your :to_stage and :to_production tasks in config/deploy.rb.
+
+      Then, all you have to do to deploy to all of your servers is
+
+          rain on {environment}
+
+      Consult http://github.com/eLocal/rain/wiki for more information.
+
+      TEXT
+    end
+  end
+end

data/lib/generators/rain/install/templates/versions.yml

@@ -0,0 +1,3 @@
+---
+stage: rel_0.0.1
+production: rel_0.0.1

data/lib/rain.rb

@@ -0,0 +1,17 @@
+require 'bundler'
+Bundler.require :default
+
+require 'rain/semantic_version'
+require 'rain/config'
+require 'rain/git_tools'
+require 'rain/deployer'
+
+require 'pathname'
+ENV['BUNDLE_GEMFILE'] ||= File.expand_path("../../Gemfile", Pathname.new(__FILE__).realpath)
+
+module Rain
+  def self.version
+    config = Rain::Config.new(Dir.pwd)
+    config.versions
+  end
+end

data/lib/rain/capistrano.rb

@@ -0,0 +1,25 @@
+# = Capistrano tasks
+#
+# A simple addon to Capistrano that defines some callbacks
+# and deploy tasks.
+#
+# The to_latest_tag task abstracts setting the branch of each
+# deployment to the current ReleaseTag.
+
+require 'capistrano'
+require 'rain/git_tools'
+
+module Rain
+  Capistrano::Configuration.instance(:must_exist).load do
+    after "to_stage",       "to_latest_tag"
+    after "to_production",  "to_latest_tag"
+
+    task :to_latest_tag do
+      if rails_env == 'stage'
+        set :branch, GitTools::ReleaseTag.current(rails_env)
+      else
+        set :branch, GitTools::ReleaseTag.latest
+      end
+    end
+  end
+end

data/lib/rain/config.rb

@@ -0,0 +1,21 @@
+require 'active_support/all'
+
+module Rain
+  # Holds the configuration options for Rain from versions.yml in a
+  # HashWithIndifferentAccess.
+  class Config
+    attr_reader :yaml_file
+
+    def initialize(root)
+      @yaml_file = YAML::load_file "#{root}/config/versions.yml"
+    end
+
+    def versions
+      @versions ||= if @yaml_file.present?
+                      ActiveSupport::HashWithIndifferentAccess.new @yaml_file
+                    else
+                      false
+                    end
+    end
+  end
+end

data/lib/rain/deployer.rb

@@ -0,0 +1,54 @@
+require 'thor'
+
+module Rain
+  class Deployer < Thor
+    include Thor::Actions
+    include GitTools
+
+    desc "on ENVIRONMENT", "Tag current HEAD and push it to the chosen environment. (default: 'production')"
+
+    method_option :force, type: :boolean, desc: "Force a release, do not prompt", aliases: "-f"
+    method_option :"keep-current-version", type: :boolean, desc: "Reuse the previous tag", aliases: "-k"
+    method_option :patch, default: true,  desc: SemanticVersion::PATCH
+    method_option :minor, default: false, desc: SemanticVersion::MINOR
+    method_option :major, default: false, desc: SemanticVersion::MAJOR
+    method_option :smoke, default: false, desc: "Run tests after deployment"
+
+    def on environment="production"
+      say "Making it rain on #{environment}..."
+
+      return unless working_directory_copasetic?(options)
+
+      unless options[:"keep-current-version"] or environment == 'production'
+        update_release_tag(environment, tag.to_s)
+        run_cmd("git tag #{tag.to_s}")
+        push_tag(tag)
+      else
+        say "Deploying existing tag #{GitTools::ReleaseTag.current("stage")} to '#{environment}'."
+      end
+
+      run_cmd "bundle exec cap to_#{environment} deploy"
+
+      say "Got a handful of stacks better grab an umbrella."
+    end
+
+    default_task :on
+
+  private
+    no_tasks do
+      def run_smoke_tests
+        #run Rain.config.smoke_test_command
+      end
+
+      def tag
+        @tag ||= case true
+          when options[:minor] then increment_minor_version
+          when options[:major] then increment_major_version
+        else
+          say "No version type detected, assuming you meant '--patch' (as it is default)"
+          increment_patch_version
+        end
+      end
+    end
+  end
+end

data/lib/rain/git_tools.rb

@@ -0,0 +1,109 @@
+require 'thor'
+require_relative 'git_tools/release_tag'
+
+# A collection of methods and a class, +ReleaseTag+, for querying the
+# local Git repository. Originally part of the Thor binary, it was
+# extracted to its own module after +Rain::Deployer+ got too large.
+module GitTools
+  include Thor::Actions unless ENV['RAILS_ENV'] == 'test' # this is most likely temporary
+
+  # A short user prompt if there are uncommitted changes in the repo, in
+  # case the user forgets before they deploy. Naturally, one may cancel
+  # this process effectively cancelling the entire deploy cleanly. This
+  # occurs before any hard changes (e.g., writing changes, pushes,
+  # command execution, etc.) are made.
+  def working_directory_copasetic?(options={})
+    return true if options[:force]
+    return false unless no_changes_pending? || yes?("There are currently uncommitted changes.  Are you sure you want to continue? [y/N]")
+    return false unless on_master? || yes?("You are not currently on the master branch.  Are you sure you want to continue? [y/N]")
+    true
+  end
+
+  # Test whether we are currently using the master branch. All
+  # deployment activity should take place on the master branch.
+  def on_master?
+    out = %x(git symbolic-ref -q HEAD)
+    out.strip == "refs/heads/master"
+  end
+
+  # Test whether there are any uncommitted changes in the working
+  # directory.
+  def no_changes_pending?
+    %x(git status --porcelain).split("\n").length == 0
+  end
+
+  # Moved code to ReleaseTag. Basically returns a ReleaseTag with a version
+  # equal to the latest Git tag.
+  def last_release_tag
+    ReleaseTag.latest
+  end
+
+  # Display name as set in +~/.gitconfig+
+  def git_name
+    %x(git config --get user.name).split("\n")[0]
+  end
+  alias deployer git_name
+
+  # Compares the latest Git tag with the latest version name in YAML. If
+  # both of those are equal, this returns +true+, because the Git tags
+  # are in sync with versions.yml
+  def tagged_latest_version?
+    ReleaseTag.latest == ReleaseTag.current
+  end
+
+  %w(major minor patch).each do |f|
+    define_method :"increment_#{f}_version" do
+      tag = last_release_tag
+      case f
+      when "major"
+        tag.major += 1
+        tag.minor = 0
+        tag.patch = 0
+        tag.other = nil
+      when "minor"
+        tag.minor += 1
+        tag.patch = 0
+        tag.other = nil
+      when "patch"
+        tag.patch += 1
+        tag.other = nil
+      end
+      tag
+    end
+  end
+
+  # Push a given +ReleaseTag+ to +origin+. You must have a Git
+  # remote set up for this to work.
+  def push_tag(tag)
+    unless tag.nil?
+      run_cmd "git push origin #{tag}"
+    end
+  end
+
+  # Execute any shell commnad, unless we're testing. But always print
+  # what is/what would have been executed onto stdout.
+  def run_cmd(cmd)
+    puts "executing... #{cmd}"
+    %x(#{cmd}) unless ENV['RAILS_ENV'] == "test"
+  end
+
+  # Full path of the versions.yml file in the Rails app.
+  def versions_path
+    File.expand_path "./config/versions.yml"
+  end
+
+  # A YAML-parsed Hash of the versions.yml file.
+  def versions_hash
+    YAML.load_file(versions_path)
+  end
+
+  # Write the newest ReleaseTag's version number to versions.yml, save
+  # it, and commit/push it to +origin/master+.
+  def update_release_tag(environment, tag)
+    hsh = versions_hash
+    hsh[environment] = tag
+    File.write(versions_path, hsh.to_yaml.to_s)
+    run_cmd "git commit -m '[RELEASE][#{environment}] Update release tag for #{environment} to #{tag}' #{versions_path}"
+    run_cmd "git push origin master"
+  end
+end