pulsar 0.2.2 → 0.2.3

data/README.md

@@ -1,16 +1,240 @@
-# Pulsar
+# Pulsar [![Gem Version](https://badge.fury.io/rb/pulsar.png)](http://badge.fury.io/rb/pulsar) [![Build Status](https://secure.travis-ci.org/nebulab/pulsar.png?branch=master)](http://travis-ci.org/nebulab/pulsar) [![Coverage Status](https://coveralls.io/repos/nebulab/pulsar/badge.png?branch=master)](https://coveralls.io/r/nebulab/pulsar) [![Code Climate](https://codeclimate.com/github/nebulab/pulsar.png)](https://codeclimate.com/github/nebulab/pulsar)
 
-[![Gem Version](https://badge.fury.io/rb/pulsar.png)](http://badge.fury.io/rb/pulsar)
-[![Build Status](https://secure.travis-ci.org/nebulab/pulsar.png?branch=master)](http://travis-ci.org/nebulab/pulsar)
-[![Coverage Status](https://coveralls.io/repos/nebulab/pulsar/badge.png?branch=master)](https://coveralls.io/r/nebulab/pulsar)
-[![Code Climate](https://codeclimate.com/github/nebulab/pulsar.png)](https://codeclimate.com/github/nebulab/pulsar)
+The easy [Capistrano](https://rubygems.org/gems/capistrano) deploy and configuration manager.
 
-Pulsar is a little tool that helps with deploys. Its main purpose is building capfiles for [Capistrano](https://rubygems.org/gems/capistrano) 
-to run. It makes it easy to manage a large number of apps via a separate configuration repository.
+Pulsar allows you to run capistrano tasks via a separate repository where all your deploy configurations are stored.
+Once you have your own repository, you can gradully add configurations and recipes so that you never have to duplicate code again.
 
-## Installation & Usage
+The way Pulsar works means that you can deploy without actually having the application on your local machine (and neither
+have all your application dependencies installed). This lets you integrate Pulsar with nearly any deploy strategy you can think of.
 
-Refer to the [GitHub Page](http://pulsar.nebulab.it).
+Some of the benefits of using Pulsar:
+* No capistrano configurations in the application code
+* No need to have the application locally to deploy
+* Multistage support by default
+* Every recipe can be shared between all applications
+* Can easily be integrated with other tools
+* Write the least possible code to deploy
+
+## Installation
+
+The most useful way of installing Pulsar is as a system gem:
+
+```bash
+$ gem install pulsar
+```
+
+This will install two commands: `pulsar` and `pulsar-utils`. The first command is required to run capistrano,
+the other is for everything else.
+
+---
+
+You'll need to create your own configuration repo:
+
+```bash
+$ pulsar-utils init ~/Desktop/pulsar-conf
+```
+
+This will create a basic start point for building your configuration repository. As soon as you're done configuring
+you should consider storing this folder as an actual git repository.
+
+Here it is possible to see how this configuration repository will look like: [Pulsar Conf Demo](http://github.com/nebulab/pulsar-conf-demo) 
+
+**NOTE**: Pulsar only supports git and *nix systems.
+
+## Configuration
+
+This is an example repository configuration layout:
+
+```bash
+pulsar-conf/
+  |── Gemfile
+  ├── Gemfile.lock
+  ├── apps
+  │   ├── base.rb
+  │   └── my_application
+  │       ├── defaults.rb
+  │       ├── production.rb
+  │       ├── recipes
+  │       │   └── custom_recipe.rb
+  │       └── staging.rb
+  └── recipes
+      ├── generic
+      │   ├── cleanup.rb
+      │   ├── maintenance_mode.rb
+      │   ├── notify.rb
+      │   └── rake.rb
+      ├── rails
+      │   ├── passenger.rb
+      │   ├── repair_permissions.rb
+      │   ├── symlink_configs.rb
+      │   ├── unicorn.rb
+      │   └── whenever.rb
+      └── spree_1
+          └── symlink_assets.rb
+```
+
+Pulsar uses these files to build capistrano configurations on the fly, depending on how you invoke the `pulsar` command.
+Since Pulsar it's basically a capistrano wrapper, the content of these files is plain old capistrano syntax.
+
+### _apps_ directory
+
+This directory contains your application configurations. You'll have one directory per application.
+
+* `base.rb` has configurations that are shared by all applications
+* `my_application/defaults.rb` includes configuration shared by every stage of the application
+* `my_application/staging.rb` and `my_application/production.rb` files include stage configurations
+* `my_application/recipes/` are recipes that are always included for that application (no need to use `load_recipes`)
+
+### _recipes_ directory
+
+This directory contains your recipes. You can create any number of directories to organize your recipes.
+To load a recipe from your configurations you can use the `load_recipes` helper:
+
+```ruby
+#
+# Somewhere inside apps/
+#
+load_recipes do
+  rails :repair_permissions, :unicorn
+  generic :cleanup, :rake
+end
+```
+
+This will use capistrano's `load` method to include recipes from `rails/` and `generic/`.
+
+---
+
+Another way to include your recipes is by using the `Gemfile`. Many gems already include custom recipes for capistrano so
+you just need to require those. An example with [Whenever](https://github.com/javan/whenever):
+
+```ruby
+#
+# Inside Gemfile
+#
+gem 'whenever'
+
+#
+# Inside recipes/rails/whenever.rb
+#
+require 'whenever/capistrano'
+
+set :whenever_command, "bundle exec whenever"
+
+#
+# Somewhere inside apps/
+#
+load_recipes do
+  rails :whenever
+end
+```
+
+### Loading the repository
+
+Once the repository is ready, you'll need to tell Pulsar where it is. The repository location can be specified either
+as a full git path or a github repository path (`gh-user/pulsar-conf`).
+
+Since Pulsar requires the repository for everything, there are multiple ways to store this information so that 
+you don't have to type it everytime.
+
+You have three possibilities:
+
+* `-c` command line option
+* `PULSAR_CONF_REPO` environment variable
+* `~/.pulsar` configuration file
+
+The fastest way is probably the `.pulsar` hidden file inside your home directory:
+
+```bash
+#
+# Inside ~/.pulsar
+#
+PULSAR_CONF_REPO="gh-user/pulsar-conf" 
+
+#
+# Also supported
+#
+# PULSAR_CONF_REPO="git://github.com/gh-user/pulsar-conf.git"
+```
+
+Pulsar will read this file and set the environment variables properly.
+
+---
+
+If you don't want to add another file to your home directory you can export the variables yourself:
+
+```bash
+#
+# Inside ~/.bash_profile or ~/.zshrc
+#
+export PULSAR_CONF_REPO="gh-user/pulsar-conf" 
+```
+
+## Usage
+
+After the repository is ready, running Pulsar is straightforward. To deploy `my_application` to `production`:
+
+```bash
+$ pulsar my_application production
+```
+
+As a rule of thumb, anything that's added at the end of the command is passed to capistrano. Some examples:
+
+```bash
+$ pulsar my_application production --tasks
+
+$ pulsar my_application staging deploy:migrations
+
+$ pulsar my_application staging shell
+
+#
+# Deploy multiple apps by using commas 
+#
+$ pulsar my_app1,my_app2,my_app3 production
+```
+
+### Running inside a Rack application (e.g. Ruby on Rails application)
+
+In case you frequently work from a Rack application and would like a workflow similar to that of capistrano, Pulsar
+supports running from inside a Rack application directory. If you use this a lot, you should consider installing
+Pulsar via the application `Gemfile`.
+
+When deploying from inside a Rack application you can omit the application name:
+
+```bash
+$ cd /path/to/my_application
+
+$ pulsar production
+
+$ pulsar staging deploy:migrations
+```
+
+---
+
+If you need a particular configuration for an application you can store a `.pulsar` file inside the application
+directory:
+
+```bash
+#
+# Inside /path/to/my_application/.pulsar
+#
+PULSAR_CONF_REPO="gh-user/pulsar-conf"
+
+#
+# If the application directory name is different than what
+# you configured inside the Pulsar configuration repository
+#
+# PULSAR_APP_NAME="my-application"
+```
+
+## Integrations
+
+Pulsar is easy to integrate, you just need access to the configurations repository and the ability to
+run a command.
+
+### Hubot
+
+https://gist.github.com/mtylty/5324075
 
 ## Contributing
 

data/lib/pulsar/helpers/all.rb

@@ -1,4 +1,5 @@
 module Pulsar::Helpers
   autoload :Capistrano, "pulsar/helpers/capistrano"
   autoload :Clamp, "pulsar/helpers/clamp"
+  autoload :Shell, "pulsar/helpers/shell"
 end

data/lib/pulsar/helpers/capistrano.rb

@@ -1,17 +1,18 @@
 module Pulsar
   module Helpers
     module Capistrano
-      require "pulsar/helpers/clamp"
-
       class DSL
         include Pulsar::Helpers::Clamp
 
-        def initialize(cap_conf, &dsl_code)
-          @cap_conf = cap_conf
+        def initialize(capistrano, opts, &dsl_code)
+          @capistrano = capistrano
+          @options = opts
           instance_eval(&dsl_code)
         end
 
         def method_missing(meth, *args, &block)
+          return if !@capistrano.from_application_path? && @options[:app_only]
+
           recipes = "#{ENV['CONFIG_PATH']}/recipes/#{meth}"
 
           File.directory?(recipes) || raise("There are no recipes of type #{meth}")
@@ -20,18 +21,27 @@ module Pulsar
             recipe = "#{recipes}/#{arg}.rb"
             File.exists?(recipe) || raise("There is no #{arg} recipe")
 
-            @cap_conf.send(:load, recipe)
+            @capistrano.send(:load, recipe)
           end
         end
       end
 
-      def load_recipes(&block)
-        DSL.new(self, &block)
-      end
-
+      #
+      # This method can be called directly inside 
+      # capistrano configurations but needs:
+      #
+      # defer { from_application_path? }
+      #
+      # otherwise capistrano will interpret it 
+      # as a variable and error out
+      #
       def from_application_path?
         ENV.has_key?('APP_PATH')
       end
+
+      def load_recipes(opts = {}, &block)
+        DSL.new(self, opts, &block)
+      end
     end
   end
 end

data/lib/pulsar/helpers/clamp.rb

@@ -1,9 +1,7 @@
-require 'fileutils'
-
 module Pulsar
   module Helpers
     module Clamp
-      include FileUtils
+      include Pulsar::Helpers::Shell
 
       def self.included(base)
         base.extend(InstanceAndClassMethods)
@@ -22,7 +20,7 @@ module Pulsar
         def application_path
           Dir.pwd if from_application_path?
         end
-        
+
         def build_capfile(args)
           app, stage = args.split(":")
 
@@ -45,11 +43,6 @@ module Pulsar
           @capfile_name ||= "#{tmp_dir}/capfile-#{time_to_deploy}"
         end
 
-        def cd(path, opts, &block)
-          puts "Directory: #{path.white}".yellow if opts[:verbose]
-          FileUtils.cd(path) { yield }
-        end
-
         def config_path
           @configuration_path ||= "#{tmp_dir}/conf-repo-#{time_to_deploy}"
         end
@@ -58,6 +51,12 @@ module Pulsar
           touch(capfile_path, :verbose => verbose?)
         end
 
+        def each_app
+          Dir["#{config_path}/apps/*"].each do |path|
+            yield(File.basename(path)) if File.directory?(path)
+          end
+        end
+
         def fetch_repo
           if File.directory?(conf_repo)
             fetch_directory_repo(conf_repo)
@@ -115,31 +114,14 @@ module Pulsar
         end
 
         def list_apps
-          apps = Dir["#{config_path}/apps/*"].each do |app|
-            if File.directory?(app)
-              app_name = File.basename(app)
-              app_envs = []
-
-              Dir["#{app}/*"].each do |env|
-                environments = %w(development staging production)
-                env_name = File.basename(env, '.rb')
-
-                if environments.include?(env_name)
-                  app_envs << env_name
-                end
-              end
-
-              puts "#{app_name.cyan}: #{app_envs.map(&:magenta).join(', ')}"
-            end
+          each_app do |name|
+            puts "#{name.cyan}: #{stages_for(name).map(&:magenta).join(', ')}"
           end
         end
 
         def load_configuration
-          conf_path = application_path || Dir.home
-          conf_file = File.join(conf_path, ".pulsar")
-
-          if File.file?(conf_file)
-            File.readlines(conf_file).each do |line|
+          unless pulsar_configuration.nil?
+            File.readlines(pulsar_configuration).each do |line|
               conf, value = line.split("=")
 
               ENV[conf] = value.chomp.gsub('"', '') if !conf.nil? && !value.nil?
@@ -147,6 +129,15 @@ module Pulsar
           end
         end
 
+        def pulsar_configuration
+          conf_file = ".pulsar"
+          inside_app = File.join(application_path, conf_file) rescue nil
+          inside_home = File.join(Dir.home, conf_file) rescue nil
+
+          return inside_app if inside_app && File.file?(inside_app)
+          return inside_home if inside_home && File.file?(inside_home)
+        end
+
         def remove_capfile
           rm_rf(capfile_path, :verbose => verbose?)
         end
@@ -171,18 +162,6 @@ module Pulsar
           end
         end
 
-        def rm_rf(path, opts)
-          puts "Remove: #{path.white}".yellow if opts[:verbose]
-          FileUtils.rm_rf(path)
-        end
-
-        def run_cmd(cmd, opts)
-          puts "Command: #{cmd.white}".yellow if opts[:verbose]
-          system(cmd)
-
-          raise "Command #{cmd} Failed" if $? != 0
-        end
-
         def set_log_level
           level = log_level.upcase
           levels = %w(IMPORTANT INFO DEBUG)
@@ -194,13 +173,18 @@ module Pulsar
           run_cmd(cmd, :verbose => verbose?)
         end
 
-        def time_to_deploy
-          @now ||= Time.now.strftime("%Y-%m-%d-%H%M%S-s#{rand(9999)}")
+        def stages_for(app)
+          environments = %w(development staging production)
+
+          Dir["#{config_path}/apps/#{app}/*"].map do |env|
+            env_name = File.basename(env, '.rb')
+
+            env_name if environments.include?(env_name)
+          end.compact
         end
 
-        def touch(file, opts)
-          puts "Touch: #{file.white}".yellow if opts[:verbose]
-          FileUtils.touch(file)
+        def time_to_deploy
+          @now ||= Time.now.strftime("%Y-%m-%d-%H%M%S-s#{rand(9999)}")
         end
       end
     end

data/lib/pulsar/helpers/shell.rb

@@ -0,0 +1,31 @@
+require "fileutils"
+
+module Pulsar
+  module Helpers
+    module Shell
+      include FileUtils
+
+      def cd(path, opts, &block)
+        puts "Directory: #{path.white}".yellow if opts[:verbose]
+        FileUtils.cd(path) { yield }
+      end
+
+      def rm_rf(path, opts)
+        puts "Remove: #{path.white}".yellow if opts[:verbose]
+        FileUtils.rm_rf(path)
+      end
+
+      def run_cmd(cmd, opts)
+        puts "Command: #{cmd.white}".yellow if opts[:verbose]
+        system(cmd)
+
+        raise "Command #{cmd} Failed" if $? != 0
+      end
+
+      def touch(file, opts)
+        puts "Touch: #{file.white}".yellow if opts[:verbose]
+        FileUtils.touch(file)
+      end
+    end
+  end
+end

data/lib/pulsar/version.rb

@@ -1,3 +1,3 @@
 module Pulsar
-  VERSION = "0.2.2"
+  VERSION = "0.2.3"
 end

data/spec/pulsar/commands/list_spec.rb

@@ -19,6 +19,20 @@ describe Pulsar::ListCommand do
     Dir.glob("#{tmp_path}/conf-repo*").should be_empty
   end
 
+  it "lists configured apps and stages" do
+    app_one = Regexp.escape("dummy_app".cyan)
+    app_two = Regexp.escape("other_dummy_app".cyan)
+    
+    stages = [ "production".magenta, "staging".magenta ]
+    escaped_stages = Regexp.escape(stages.join(', '))
+    reversed_stages = Regexp.escape(stages.reverse.join(', '))
+
+    pulsar.run(full_list_args)
+
+    stdout.should match(/#{app_one}: (#{escaped_stages})|(#{reversed_stages})/)
+    stdout.should match(/#{app_two}: (#{escaped_stages})|(#{reversed_stages})/)
+  end
+
   it "reads configuration variables from .pulsar file in home" do
     env_vars = [ "PULSAR_CONF_REPO=\"#{dummy_conf_path}\"\n"] 
 
@@ -47,6 +61,34 @@ describe Pulsar::ListCommand do
     ENV['PULSAR_CONF_REPO'].should == dummy_conf_path
   end
 
+  it "skips lines which cannot parse when reading .pulsar file" do
+    env_vars = [ "wrong_line", "# comment"] 
+
+    File.stub(:file?).and_return(true)
+    File.stub(:readlines).with("#{File.expand_path(dummy_rack_app_path)}/.pulsar").and_return(env_vars)
+
+    FileUtils.cd(dummy_rack_app_path) do
+      reload_main_command
+
+      expect { pulsar.run(full_list_args) }.not_to raise_error
+    end
+  end
+
+  it "falls back to .pulsar file in home directory if it's not in the rack app directory" do
+    env_vars = [ "PULSAR_APP_NAME=\"dummy_app\"\n", "PULSAR_CONF_REPO=\"#{dummy_conf_path}\"\n"] 
+
+    File.stub(:file?).and_return(true)
+    File.stub(:file?).with("#{File.expand_path(dummy_rack_app_path)}/.pulsar").and_return(false)
+
+    File.should_receive(:readlines).with("#{Dir.home}/.pulsar").and_return(env_vars)
+
+    FileUtils.cd(dummy_rack_app_path) do
+      reload_main_command
+
+      pulsar.run(full_list_args)
+    end
+  end
+
   context "--conf-repo option" do
     it "is required" do
       expect { pulsar.parse([]) }.to raise_error(Clamp::UsageError)

data/spec/pulsar/commands/main_spec.rb

@@ -86,6 +86,21 @@ describe Pulsar::MainCommand do
     end
   end
 
+  it "falls back to .pulsar file in home directory if it's not in the rack app directory" do
+    env_vars = [ "PULSAR_APP_NAME=\"dummy_app\"\n", "PULSAR_CONF_REPO=\"#{dummy_conf_path}\"\n"] 
+
+    File.stub(:file?).and_return(true)
+    File.stub(:file?).with("#{File.expand_path(dummy_rack_app_path)}/.pulsar").and_return(false)
+
+    File.should_receive(:readlines).with("#{Dir.home}/.pulsar").and_return(env_vars)
+
+    FileUtils.cd(dummy_rack_app_path) do
+      reload_main_command
+
+      pulsar.run(full_cap_args + %w(production))
+    end
+  end
+
   context "Capfile" do
     it "uses base.rb in staging stage" do
       pulsar.run(full_cap_args + dummy_app(:staging))

data/spec/pulsar/helpers/capistrano_spec.rb

@@ -26,6 +26,26 @@ describe Pulsar::Helpers::Capistrano do
 
       expect { load_recipes { generic :missing_recipe } }.to raise_error(RuntimeError, /no missing_recipe recipe/)
     end
+
+    it "does not call load if :app_only is true and pulsar is not called from inside application" do
+      ENV.delete('APP_PATH')
+      File.stub(:directory?).and_return(true)
+      File.stub(:exists?).and_return(true)
+
+      self.should_not_receive(:load)
+
+      load_recipes(:app_only => true) { generic :recipe }
+    end
+
+    it "calls load if :app_only is true and pulsar is called from inside application" do
+      ENV['APP_PATH'] = "/app/path"
+      File.stub(:directory?).and_return(true)
+      File.stub(:exists?).and_return(true)
+      
+      self.should_receive(:load)
+
+      load_recipes(:app_only => true) { generic :recipe }
+    end
   end
 
   context "from_application_path?" do

data/spec/pulsar/helpers/clamp_spec.rb

@@ -50,12 +50,6 @@ describe Pulsar::Helpers::Clamp do
     end
   end
 
-  context "run_cmd" do
-    it "raises exception if command fails" do
-      expect { run_cmd("return 1", {}) }.to raise_error
-    end
-  end
-
   context "reset_for_other_app!" do
     it "resets instance variables written by the module" do
       cap, conf, time = capfile_path, config_path, time_to_deploy

data/spec/pulsar/helpers/shell_spec.rb

@@ -0,0 +1,11 @@
+require 'spec_helper'
+
+describe Pulsar::Helpers::Shell do
+  include Pulsar::Helpers::Shell
+
+  context "run_cmd" do
+    it "raises exception if command fails" do
+      expect { run_cmd("return 1", {}) }.to raise_error
+    end
+  end
+end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: pulsar
 version: !ruby/object:Gem::Version
-  version: 0.2.2
+  version: 0.2.3
   prerelease: 
 platform: ruby
 authors:
@@ -10,7 +10,7 @@ authors:
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2013-05-02 00:00:00.000000000 Z
+date: 2013-05-12 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: clamp
@@ -165,6 +165,7 @@ files:
 - lib/pulsar/helpers/all.rb
 - lib/pulsar/helpers/capistrano.rb
 - lib/pulsar/helpers/clamp.rb
+- lib/pulsar/helpers/shell.rb
 - lib/pulsar/options/all.rb
 - lib/pulsar/options/conf_repo.rb
 - lib/pulsar/options/shared.rb
@@ -176,6 +177,7 @@ files:
 - spec/pulsar/commands/utils_spec.rb
 - spec/pulsar/helpers/capistrano_spec.rb
 - spec/pulsar/helpers/clamp_spec.rb
+- spec/pulsar/helpers/shell_spec.rb
 - spec/spec_helper.rb
 - spec/support/dummies/dummy_app/config.ru
 - spec/support/dummies/dummy_conf/Gemfile
@@ -207,7 +209,7 @@ required_ruby_version: !ruby/object:Gem::Requirement
       version: '0'
       segments:
       - 0
-      hash: 2516214880330231667
+      hash: 882451203726848959
 required_rubygems_version: !ruby/object:Gem::Requirement
   none: false
   requirements:
@@ -216,7 +218,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
       version: '0'
       segments:
       - 0
-      hash: 2516214880330231667
+      hash: 882451203726848959
 requirements: []
 rubyforge_project: 
 rubygems_version: 1.8.25
@@ -232,6 +234,7 @@ test_files:
 - spec/pulsar/commands/utils_spec.rb
 - spec/pulsar/helpers/capistrano_spec.rb
 - spec/pulsar/helpers/clamp_spec.rb
+- spec/pulsar/helpers/shell_spec.rb
 - spec/spec_helper.rb
 - spec/support/dummies/dummy_app/config.ru
 - spec/support/dummies/dummy_conf/Gemfile