pulsar 1.0.0 → 1.1.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: 49da97e3127c662682484d2c3339d873a2dc7cea
-  data.tar.gz: ef831d3995741f3fdee35ff56a6c603f5095e649
+  metadata.gz: 7d2e3f41d33d1980ca08e0cfb6ad9a79fa74e8d0
+  data.tar.gz: e64cdb54592106c7f5690c71e67c435a260bc566
 SHA512:
-  metadata.gz: cad9605fa0f1f5e8564e2aa0620d20dea1c50ca5c766a0d4ae524c370c0a7777137390d78b34e0f26d965cebe5637e3bcd6bec2c2cfeac1ee4d87b36625caac3
-  data.tar.gz: 4cc0710f834e143f5e0b7969e42f03c76334a001ef5782d3d191e47e6c45be16bdcca89e3f338f938d752629045eb746761b6faf67ed5e99447b248ebb205a61
+  metadata.gz: 43c48f2e6c411fefc1650918c782ec4bfc78662743ec1ec3c33a69e7616acf9af4dafa9631af6a8280856b472ae85c8e24a310e725843a550a6b480d0afbf55d
+  data.tar.gz: 3c926574265223622a691920c39e86a4b02b9c9b6b6d77d456ee59290f5fdad2defb377ff820831943940a2f8bd72fd65593f28e0566a13ed38c0ba60e09f0fa

data/.gitignore

@@ -17,3 +17,4 @@ test/tmp
 test/version_tmp
 tmp
 !tmp/.gitkeep
+coverage/

data/README.md

@@ -1,21 +1,294 @@
-# Pulsar
+# Pulsar [![Gem Version](https://badge.fury.io/rb/pulsar.svg)](https://badge.fury.io/rb/pulsar) [![CircleCI](https://img.shields.io/circleci/project/github/nebulab/pulsar/master.png)](https://circleci.com/gh/nebulab/pulsar/tree/master) [![Coverage Status](https://coveralls.io/repos/github/nebulab/pulsar/badge.svg?branch=master)](https://coveralls.io/github/nebulab/pulsar?branch=master)
 
-The easy [Capistrano](https://rubygems.org/gems/capistrano) deploy and configuration manager.
+The easy [Capistrano][cap-gem] deploy and configuration manager.
 
-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.
+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 gradually add configurations and recipes so that you never have to duplicate
+code again.
 
-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.
+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.
 
 Some of the benefits of using Pulsar:
-* No capistrano configurations in the application code
+* No Capistrano configurations in the application code
 * No need to have the application locally to deploy
 * Every recipe can be shared between all applications
 * Can easily be integrated with other tools
 * Write the least possible code to deploy
 
+*DISCLAIMER*: Understanding Capistrano is strongly suggested before using
+Pulsar.
+
 ## Capistrano support
 
-This version of Pulsar, version `1.0.0` only supports Capistrano v3. If you're looking for Capistrano v2 support you can
-use Pulsar version `0.3.5` but, take care, that version is not maintained anymore.
+This version of Pulsar (version `>= 1.0.0`) only supports Capistrano v3. If
+you're looking for Capistrano v2 support you can use Pulsar version `0.3.5` but,
+take care, that version is not maintained anymore.
+
+## Installation
+
+The most useful way of installing Pulsar is as a system gem:
+
+```bash
+$ gem install pulsar
+```
+
+This will install the `pulsar` command which will be used to for everything,
+from running Capistrano to listing your configurations.
+
+---
+
+The first thing you'll need to do is to create your own configuration repo:
+
+```bash
+$ pulsar install ~/Desktop/pulsar-conf
+```
+
+This will create a basic starting point for building your configuration
+repository. As soon as you're done configuring you should consider transforming
+this folder to a git repository.
+
+You can have a look at how your repository should look like by browsing the
+[Pulsar Conf Demo][pulsar-conf-demo].
+
+**NOTE**: Pulsar only supports git.
+
+## Configuration
+
+This is an example repository configuration layout:
+
+```bash
+pulsar-conf/
+  |── Gemfile
+  ├── Gemfile.lock
+  ├── apps
+  │   ├── Capfile
+  │   ├── deploy.rb
+  │   └── my_application
+  │       ├── Capfile
+  │       ├── deploy.rb
+  │       ├── production.rb
+  │       └── staging.rb
+  └── recipes
+      ├── generic
+      │   ├── maintenance_mode.rake
+      │   ├── notify.rake
+      │   └── utils.rake
+      ├── rails
+      │   ├── passenger.rake
+      │   ├── repair_permissions.rake
+      │   ├── symlink_configs.rake
+      │   ├── unicorn.rake
+      │   └── whenever.rake
+      └── spree_1
+          └── symlink_assets.rake
+```
+
+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.
+
+* `Capfile` is the generic Capfile shared by all applications
+* `deploy.rb` has configurations that are shared by all applications
+* `my_application/Capfile` is the Capfile that will be used for this particular
+application
+* `my_application/deploy.rb` includes configuration shared by every stage of the
+application
+* `my_application/staging.rb` and `my_application/production.rb` files include
+stage configurations
+
+### _recipes_ directory
+
+This directory contains your recipes. You can create any number of directories
+to organize your recipes. In Capistrano v3 fashion, all the files are plain old
+rake tasks (make sure to name them with the `.rake` extension).
+
+The recipes contained in this folder are **always included** in each stage for
+each application.
+
+---
+
+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][whenever]:
+
+```ruby
+#
+# Inside Gemfile
+#
+gem 'whenever'
+
+#
+# Inside some Capfile (either generic or application specific)
+#
+require 'whenever/capistrano'
+
+#
+# Inside some .rb configuration file (either generic or application specific)
+#
+set :whenever_command, "bundle exec whenever"
+```
+
+### 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 (*i.e.* `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 can also
+use local repository, which is useful while developing your deployment.
+
+You have three possibilities:
+
+* `-c` command line option
+* `PULSAR_CONF_REPO` environment variable
+* `~/.pulsar/config` configuration file
+
+The fastest way is probably the `.pulsar/config` file inside your home
+directory:
+
+```bash
+#
+# Inside ~/.pulsar/config
+#
+PULSAR_CONF_REPO="gh-user/pulsar-conf"
+
+#
+# You can use local repository for development so you don't need to push changes
+# every time
+#
+# PULSAR_CONF_REPO="/full/path/to/repository"
+
+#
+# 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. You can either
+list your applications or build a configuration and run Capistrano on it.
+
+### Deploy
+
+Running the `deploy` command really means running Capistrano on a certain
+configuration.
+
+To deploy `my_application` to `production`:
+
+```bash
+$ pulsar deploy my_application production
+```
+
+The above command will fetch the Pulsar configuration repository, run
+`bundle install`, combine the generic `Capfile` and `deploy.rb` files with the
+`my_application` specific ones and add specific `production.rb` stage
+configuration. At last it will run `cap deploy` on it.
+
+Right now Pulsar does not support tasks other then deploy. Support for running
+other Capistrano taks will come, state tuned!
+
+### Listing applications
+
+Pulsar can fetch your configuration repository and list the application and
+stages you can run deploys on:
+
+```bash
+$ pulsar list
+```
+
+This will fetch the Pulsar configuration repository and list everything that's
+inside, like this:
+
+```
+my_application: production, staging
+awesome_startup: dev, production, staging
+```
+
+### Execute arbitrary Capistrano tasks
+
+You can launch any Capistrano task via `task` command. You can also
+pass arguments in _Rake style_ (i.e. via square brackets after task name)
+
+```
+$ pulsar task mycustom:task[argumen1,argument2] my_application staging
+```
+
+or via environment variables.
+
+```
+$ TASK_ARG1=arg1 TASK_ARG2=arg2 pulsar task mycustom:task my_application staging
+```
+
+## Integrations
+
+Pulsar is easy to integrate, you just need access to the configurations
+repository and the ability to run a command.
+
+Right now there are no integrations for Pulsar v1 but there are some built for
+the old v0.3 version that can be used as an example.
+
+### Chat Bots
+
+- https://gist.github.com/mtylty/5324075: a [hubot][hubot] script that runs
+Pulsar via the command line
+- [hubot-pulsar][hubot-pulsar]: a [hubot][hubot] plugin for integrating via
+[Pulsar REST API][pulsar-rest-api]
+- [lita-pulsar][lita-pulsar]: a [Lita][lita] plugin for integrating via the
+command line
+
+
+### Pulsar REST API service
+
+[Pulsar REST API][pulsar-rest-api] is a service to provide a REST API for
+executing pulsar jobs.
+
+Here is a [real-life example][pulsar-rest-api-blogpost] of how you can integrate
+and simplify your Pulsar workflow.
+
+## About
+
+[![Nebulab][nebulab-logo]][nebulab]
+
+Pulsar is funded and maintained by the [Nebulab][nebulab] team.
+
+We firmly believe in the power of open-source. [Contact us][contact-us] if you
+like our work and you need help with your project design or development.
+
+[license]: MIT-LICENSE
+[cap-gem]: https://rubygems.org/gems/capistrano
+[nebulab]: http://nebulab.it/
+[nebulab-logo]: http://nebulab.it/assets/images/public/logo.svg
+[contact-us]: http://nebulab.it/contact-us/
+[pulsar-conf-demo]: http://github.com/nebulab/pulsar-conf-demo
+[whenever]: https://github.com/javan/whenever
+[hubot]: https://hubot.github.com
+[hubot-pulsar]: https://github.com/cargomedia/hubot-pulsar
+[pulsar-rest-api]: https://github.com/cargomedia/pulsar-rest-api
+[pulsar-rest-api-blogpost]: http://www.cargomedia.ch/2015/06/23/pulsar-rest-api.html
+[lita]: https://www.lita.io
+[lita-pulsar]: http://github.com/nebulab/lita-pulsar

data/circle.yml

@@ -1,16 +1,61 @@
+machine:
+  post:
+    - |
+      if [[ -e ~/rvm_binaries/ruby-2.0.0-p648.tar.bz2 ]]
+      then
+        rvm mount ~/rvm_binaries/ruby-2.0.0-p648.tar.bz2
+      else
+        mkdir -p ~/rvm_binaries
+        rvm install 2.0.0 --disable-binary
+        cd ~/rvm_binaries && rvm prepare 2.0.0
+      fi
+    - |
+      if [[ -e ~/rvm_binaries/ruby-2.1.10.tar.bz2 ]]
+      then
+        rvm mount ~/rvm_binaries/ruby-2.1.10.tar.bz2
+      else
+        mkdir -p ~/rvm_binaries
+        rvm install 2.1.10 --disable-binary
+        cd ~/rvm_binaries && rvm prepare 2.1.10
+      fi
+    - |
+      if [[ -e ~/rvm_binaries/ruby-2.2.6.tar.bz2 ]]
+      then
+        rvm mount ~/rvm_binaries/ruby-2.2.6.tar.bz2
+      else
+        mkdir -p ~/rvm_binaries
+        rvm install 2.2.6 --disable-binary
+        cd ~/rvm_binaries && rvm prepare 2.2.6
+      fi
+    - |
+      if [[ -e ~/rvm_binaries/ruby-2.3.3.tar.bz2 ]]
+      then
+        rvm mount ~/rvm_binaries/ruby-2.3.3.tar.bz2
+      else
+        mkdir -p ~/rvm_binaries
+        rvm install 2.3.3 --disable-binary
+        cd ~/rvm_binaries && rvm prepare 2.3.3
+      fi
+    - |
+      if [[ -e ~/rvm_binaries/ruby-2.4.0.tar.bz2 ]]
+      then
+        rvm mount ~/rvm_binaries/ruby-2.4.0.tar.bz2
+      else
+        mkdir -p ~/rvm_binaries
+        rvm install 2.4.0 --disable-binary
+        cd ~/rvm_binaries && rvm prepare 2.4.0
+      fi
 dependencies:
+  cache_directories:
+    - ~/rvm_binaries
   pre:
-    - rvm install 2.0.0
-    - rvm install 2.1.10
-    - rvm install 2.2.6
-    - rvm install 2.3.3
-    - rvm install 2.4.0
+    - mkdir $CIRCLE_ARTIFACTS/coverage
   override:
-    - rvm-exec 2.0.0 bash -c "bundle check --path=vendor/bundle || bundle install --path=vendor/bundle"
-    - rvm-exec 2.1.10 bash -c "bundle check --path=vendor/bundle || bundle install --path=vendor/bundle"
-    - rvm-exec 2.2.6 bash -c "bundle check --path=vendor/bundle || bundle install --path=vendor/bundle"
-    - rvm-exec 2.3.3 bash -c "bundle check --path=vendor/bundle || bundle install --path=vendor/bundle"
-    - rvm-exec 2.4.0 bash -c "bundle check --path=vendor/bundle || bundle install --path=vendor/bundle"
+    - rvm-exec 2.0.0 bash -c "gem install bundler && (bundle check --path=vendor/bundle || bundle install --path=vendor/bundle)"
+    - rvm-exec 2.1.10 bash -c "gem install bundler && (bundle check --path=vendor/bundle || bundle install --path=vendor/bundle)"
+    - rvm-exec 2.2.6 bash -c "gem install bundler && (bundle check --path=vendor/bundle || bundle install --path=vendor/bundle)"
+    - rvm-exec 2.3.3 bash -c "gem install bundler && (bundle check --path=vendor/bundle || bundle install --path=vendor/bundle)"
+    - rvm-exec 2.4.0 bash -c "gem install bundler && (bundle check --path=vendor/bundle || bundle install --path=vendor/bundle)"
 test:
   pre:
     - git config --global user.email "circleci@nebulab.it" && git config --global user.name "Circle CI"
@@ -19,4 +64,4 @@ test:
     - rvm-exec 2.1.10 bash -c "bundle exec rspec --color --format documentation spec"
     - rvm-exec 2.2.6 bash -c "bundle exec rspec --color --format documentation spec"
     - rvm-exec 2.3.3 bash -c "bundle exec rspec --color --format documentation spec"
-    - rvm-exec 2.4.0 bash -c "bundle exec rspec --color --format documentation spec"
+    - rvm-exec 2.4.0 bash -c "COVERAGE=true bundle exec rspec --color --format documentation spec"

data/lib/pulsar.rb

@@ -8,6 +8,8 @@ module Pulsar
   require 'interactor'
   require 'fileutils'
 
+  require 'pulsar/context_error'
+  require 'pulsar/validator'
   require 'pulsar/interactors/cleanup'
   require 'pulsar/interactors/create_run_dirs'
   require 'pulsar/interactors/add_applications'
@@ -23,7 +25,7 @@ module Pulsar
 
   require 'pulsar/organizers/list'
   require 'pulsar/organizers/install'
-  require 'pulsar/organizers/deploy'
+  require 'pulsar/organizers/task'
 
   require 'pulsar/constants'
   require 'pulsar/cli'

data/lib/pulsar/cli.rb

@@ -1,3 +1,8 @@
+if ENV['COVERAGE']
+  ENV['FEATURE_TESTS'] = 'true'
+  require_relative '../../spec/support/coverage_setup'
+end
+
 module Pulsar
   class CLI < Thor
     map %w[--version -v] => :__print_version
@@ -50,9 +55,10 @@ module Pulsar
     option :conf_repo, aliases: '-c'
     def deploy(application, environment)
       load_config
-      result = Pulsar::Deploy.call(
+      result = Pulsar::Task.call(
         repository: load_option_or_env!(:conf_repo),
-        application: application, environment: environment
+        application: application, environment: environment,
+        task: 'deploy'
       )
 
       if result.success?
@@ -63,6 +69,24 @@ module Pulsar
       end
     end
 
+    desc 'task APPLICATION ENVIRONMENT TASK', 'Run Capistrano task for APPLICATION on ENVIRONMENT'
+    option :conf_repo, aliases: '-c'
+    def task(application, environment, task)
+      load_config
+      result = Pulsar::Task.call(
+        repository: load_option_or_env!(:conf_repo),
+        application: application, environment: environment,
+        task: task
+      )
+
+      if result.success?
+        puts "Executed task #{task} for #{application} on #{environment}!"
+      else
+        puts "Failed to execute task #{task} for #{application} on #{environment}."
+        puts result.error
+      end
+    end
+
     desc "--version, -v", "print the version"
     def __print_version
       puts Pulsar::VERSION
@@ -71,6 +95,8 @@ module Pulsar
     private
 
     def load_config
+      return unless File.exist?(PULSAR_CONF) && File.stat(PULSAR_CONF).readable?
+
       Dotenv.load(PULSAR_CONF) # Load configurations for Pulsar
     end
 
@@ -81,8 +107,7 @@ module Pulsar
       option_value   = options[option] || ENV[env_option]
 
       if option_value.nil? || option_value.empty?
-        fail RequiredArgumentMissingError,
-             exception_text
+        fail RequiredArgumentMissingError, exception_text
       end
 
       option_value