capistrano-multiproject 0.0.2 → 0.0.3

data/README.md

@@ -1,19 +1,181 @@
-# capistrano-multiproject
+capistrano-multiproject
+=======================
 
-## Description
+Author: Olek Poplavsky
+
+
+Introduction
+------------
 
 Capistrano extension that allows to deploy multiple projects from one location.
 
-Everybody knows/uses original multistage extension written by Jamis Buck. It works great while you have only one project/app to deploy.
-It is not quite enough if you have multiple projects to deploy (SOA would be one big use case here). Capistrano-multiproject solves this problem by allowing splitting up deploy.rb into multiple project-specific recipe files.
+Everybody knows/uses original multistage extension written by Jamis Buck. It works great while you
+have only one project/app to deploy.  It is not quite enough if you have multiple projects to deploy
+(SOA would be one big use case here). Capistrano-multiproject solves this problem by allowing
+splitting up deploy.rb into multiple project-specific recipe files.
 
-## Usage
+
+Installation
+------------
 
 Install gem
 
     $ gem install capistrano-multiproject
 
 
+Setup
+-----
+
+You are expected to create separate project, whole purpose of which is to deploy other projects.
+That may be just a directory in your source repository, or a separate repository, it is up to you.
+
+**Typical directory structure of 'deploy' project**
+
+    config/
+      deploy/
+        projects/
+          project1.rb
+          project2.rb
+        stages/
+          testing.rb
+          qa.rb
+          demo.rb
+          production.rb
+      deploy.rb
+    recipes/
+      recipe1.rb
+      recipe2.rb
+    Capfile
+    Gemfile
+
+
+Usage
+-----
+
+If your run 'cap -T' you will see that only tasks that are loaded by default are projects, stages,
+and strange '?' task. That last one is actually a replacement for  '-T' option, that is customized
+for the multiproject setup.
+
+'cap ?' outputs list of stages.
+
+'cap stage1 ?' outputs list of projects.
+
+'cap stage1 project1 ?' outputs list of capistrano tasks available in a given project.
+
+'cap stage1 project1 task1' executes capistrano task for some project in a context of given stage.
+
+
+Configuration
+-------------
+
+Add to `Gemfile`
+
+    gem 'capistrano'
+    gem 'capistrano-multiproject'
+
 Add to `Capfile`
 
     require 'capistrano/multiproject'
+    load 'config/deploy'
+
+Create file config/deploy.rb. Put you common settings/recipes there, those will be shared by all
+projects. Settings like 'scm', 'repository', 'use_sudo', 'ssh_options' are good candidates to put
+here.
+Require common shared recipes like this:
+
+    load 'recipes/recipe1.rb'
+
+Create directories deploy/projects and deploy/stages.
+
+Stages directory contains .rb files that describe settings particular to specific stage. Usually all
+that is done here is setting branch (or repository) and bunch of server roles.
+
+Example of stage file config/deploy/stages/stage1.rb:
+
+    role :app, 'app1.foo.com', 'app2.foo.com'
+    role :redis, 'misc.foo.com'
+    role :shpinx, 'misc.foo.com'
+    role :db, 'masterdb.foo.com', :primary => true, :master => true
+    role :db,  'slavedb.foo.com', :no_release => true, :master => false
+    set :branch, 'master'
+
+Projects directory contains .rb files that contains recipes specifit to particular project.
+
+Example config/deploy/projects/foo.rb:
+
+    load 'recipes/recipe1.rb'
+
+    set :shared_children, %w(log pids)
+
+    namespace :deploy  do
+      desc "Stops foo service"
+      task :stop do
+        run "#{sudo} /etc/init.d/foo stop"
+      end
+
+      desc "Starts foo service"
+      task :start do
+        run "#{sudo} /etc/init.d/foo start"
+      end
+
+      desc "Restarts foo service"
+      task :restart do
+        run "#{sudo} /etc/init.d/foo restart"
+      end
+    end
+
+By default, only roles that are named the same as project file, are loaded (that is, for project
+'foo.rb', only role 'foo' will be loaded, roles 'db', 'redis' etc will not make it to capistrano.
+When this needs to be customized, it is easy to do that my setting property project_roles like this:
+
+    set :project_roles, ['role1', 'role2']
+
+In addition to roles defined in stage file, project's recipes have access to one special/synthetic 'any_server' role.
+That role contains all the servers that were defined in the stage file, combined. It is very useful
+to implement some administration recipes, like 'reboot all servers', 'update ubuntu software on all
+servers', or 'run chef-client on all servers'.
+
+Example config/deploy/projects/admin.rb:
+
+    set :project_roles, %w(any_server)
+    namespace :servers do
+      namespace :reboot do
+        desc "Reboot all servers"
+        task :all do
+          run "#{sudo} shutdown -r +1" # reboot in 1 minute
+        end
+      end
+    end
+
+
+Compatibility
+-------------
+
+So far it was tested to work under ruby 1.9.
+
+There is no good reason why it would not work with ruby 1.8, if you find problem with that, come
+back to me and we will fix it together :)
+
+
+License
+-------
+
+capistrano-multiproject is released under the [MIT][license] license.
+
+[license]: http://www.opensource.org/licenses/MIT
+
+
+Credits
+-------
+
+**Jamis Buck**
+
+  [capistrano-multistage][multistage] started it all
+
+**Andriy Yanko**
+
+  [caphub][caphub] and [capistrano-multiconfig][multiconfig] were the inspiration for this project
+
+[multistage]: http://weblog.jamisbuck.org/2007/7/23/capistrano-multistage
+[caphub]: https://github.com/railsware/caphub
+[multiconfig]: https://github.com/railsware/capistrano-multiconfig

data/capistrano-multiproject.gemspec

@@ -2,7 +2,7 @@
 
 Gem::Specification.new do |s|
   s.name        = "capistrano-multiproject"
-  s.version     = "0.0.2"
+  s.version     = "0.0.3"
   s.authors     = ["Olek Poplavsky"]
   s.email       = ["olek@woodenbits.com"]
   s.homepage    = "https://github.com/woodenbits/capistrano-multiproject"

data/lib/capistrano/multiproject/any_server_role.rb

@@ -2,9 +2,11 @@ Capistrano::Configuration.instance.load do
   namespace :multiproject do
     desc "[internal] Generate arteficial any_server role that enumerates all known servers"
     task :any_server_role do
-      project_roles_sym = project_roles.map(&:to_sym)
-      servers = roles.values.map(&:servers).flatten.sort.uniq.map(&:to_s)
-      top.role :any_server, *servers, :no_release => true
+      project_roles_sym = project_roles.map { |o| o.to_sym }
+      servers = roles.values.map { |o| o.servers }.map { |o| o.to_s }.flatten.sort.uniq
+#      ruby 1.8 hates having hash after expanding array, while 1.9 is totally cool with that
+#      top.role(:any_server, *servers, { :no_release => true })
+      servers.each { |s| top.server s, :any_server, :no_release => true }
     end
   end
 

data/lib/capistrano/multiproject/filter_roles.rb

@@ -2,8 +2,8 @@ Capistrano::Configuration.instance.load do
   namespace :multiproject do
     desc "[internal] Filter roles to only those that are used by the current project"
     task :filter_roles do
-      project_roles_sym = project_roles.map(&:to_sym)
-      roles.select! { |k,v| project_roles_sym.include?(k) }
+      project_roles_sym = project_roles.map { |o| o.to_sym }
+      roles.delete_if { |k,v| !project_roles_sym.include?(k) }
       logger.info "Filtered roles down to '#{roles.keys.sort.join(', ')}'"
       if roles.empty? && project_roles == [project]
         abort "Define servers of role '#{project}' in stage '#{stage}' configuration, or specify project roles in project recipe (e.g. 'set :project_roles, [:foo, :bar]')"

metadata

@@ -1,50 +1,39 @@
---- !ruby/object:Gem::Specification 
+--- !ruby/object:Gem::Specification
 name: capistrano-multiproject
-version: !ruby/object:Gem::Version 
-  hash: 27
+version: !ruby/object:Gem::Version
+  version: 0.0.3
   prerelease: 
-  segments: 
-  - 0
-  - 0
-  - 2
-  version: 0.0.2
 platform: ruby
-authors: 
+authors:
 - Olek Poplavsky
 autorequire: 
 bindir: bin
 cert_chain: []
-
-date: 2012-01-26 00:00:00 Z
-dependencies: 
-- !ruby/object:Gem::Dependency 
+date: 2012-01-26 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
   name: capistrano
-  prerelease: false
-  requirement: &id001 !ruby/object:Gem::Requirement 
+  requirement: &2152540700 !ruby/object:Gem::Requirement
     none: false
-    requirements: 
+    requirements:
     - - ~>
-      - !ruby/object:Gem::Version 
-        hash: 43
-        segments: 
-        - 2
-        - 9
-        - 0
+      - !ruby/object:Gem::Version
         version: 2.9.0
   type: :runtime
-  version_requirements: *id001
-description: "\n\
-  Everybody knows/uses original multistage extension written by Jamis Buck. It works great while you have only one project/app to deploy.\n\
-  It is not quite enough if you have multiple projects to deploy (SOA would be one big use case here). Capistrano-multiproject solves this problem by allowing splitting up deploy.rb into multiple project-specific recipe files.\n  "
-email: 
+  prerelease: false
+  version_requirements: *2152540700
+description: ! "\nEverybody knows/uses original multistage extension written by Jamis
+  Buck. It works great while you have only one project/app to deploy.\nIt is not quite
+  enough if you have multiple projects to deploy (SOA would be one big use case here).
+  Capistrano-multiproject solves this problem by allowing splitting up deploy.rb into
+  multiple project-specific recipe files.\n  "
+email:
 - olek@woodenbits.com
 executables: []
-
 extensions: []
-
-extra_rdoc_files: 
+extra_rdoc_files:
 - README.md
-files: 
+files:
 - capistrano-multiproject.gemspec
 - Gemfile
 - lib/capistrano/multiproject/configurations.rb
@@ -57,36 +46,27 @@ files:
 - README.md
 homepage: https://github.com/woodenbits/capistrano-multiproject
 licenses: []
-
 post_install_message: 
-rdoc_options: 
+rdoc_options:
 - --charset=UTF-8
-require_paths: 
+require_paths:
 - lib
-required_ruby_version: !ruby/object:Gem::Requirement 
+required_ruby_version: !ruby/object:Gem::Requirement
   none: false
-  requirements: 
-  - - ">="
-    - !ruby/object:Gem::Version 
-      hash: 3
-      segments: 
-      - 0
-      version: "0"
-required_rubygems_version: !ruby/object:Gem::Requirement 
+  requirements:
+  - - ! '>='
+    - !ruby/object:Gem::Version
+      version: '0'
+required_rubygems_version: !ruby/object:Gem::Requirement
   none: false
-  requirements: 
-  - - ">="
-    - !ruby/object:Gem::Version 
-      hash: 3
-      segments: 
-      - 0
-      version: "0"
+  requirements:
+  - - ! '>='
+    - !ruby/object:Gem::Version
+      version: '0'
 requirements: []
-
 rubyforge_project: 
-rubygems_version: 1.8.13
+rubygems_version: 1.8.10
 signing_key: 
 specification_version: 3
 summary: Capistrano extension that allows to deploy multiple projects from one location
 test_files: []
-