plow 0.1.0

data/.gitignore

@@ -0,0 +1,9 @@
+*.sw?
+.DS_Store
+coverage
+rdoc
+pkg
+.yardoc
+doc
+plow.gemspec
+plow.tmproj

data/.yardopts

@@ -0,0 +1,6 @@
+--markup markdown
+--private
+-
+LICENSE
+HISTORY
+SECURITY

data/HISTORY

@@ -0,0 +1,39 @@
+== 1.0.0 released on Oct. ??th 2009
+
+  * bin/plow and bin/plow1.9
+    * Two ruby 1.9.1 compatible command-line executables.
+    * Combined with Plow::Application, the entire application logic is decoupled from the plow generator library.
+  * lib/plow.rb
+    * Handles load-time errors gracefully for the user
+    * Specifies library-wide load order
+    * Maintains the library version in memory
+  * lib/plow/application.rb
+    * decoupled argument parsing from the generator
+    * displays usage for the command-line executables
+    * handles run-time errors gracefully for the user
+    * starts the generator
+    * Combined with the executables, the entire application logic is decoupled from the plow generator library.
+  * lib/plow/generator.rb
+    * main controller
+    * maintains the shared state data including a strategy object
+    * passes execution to the strategy object
+    * provides shared logic for outputting messages to the user
+    * provides shared logic for executing shell commands
+    * provides shared logic for evaluating ERB template files
+  * lib/plow/binding_struct.rb
+    * helper object that converts a Hash object into instances variables, which then is used as the binding object for ERB
+  * lib/plow/core_ext/object.rb
+    * dynamically adds a #blank? method to all objects (copied directly from the active_support library)
+  * lib/plow/errors.rb
+    * defines a handful of run-time error classes
+  * lib/plow/strategy/ubuntu_hardy/user_home_web_app.rb
+    * userhome-based strategy for generating a system-wide web-site structure for the Linux Ubuntu Hardy 8.04.3 LTS operating system
+      * understanding and managing the security implications of web server of virtual hosts
+  * lib/plow/strategy/ubuntu_hardy/templates/apache2-vhost.conf
+    * a simple apache2 virtual host ERB template file for the Linux Ubuntu Hardy 8.04.3 LTS operating system
+  * lib/plow/strategy/ubuntu_hardy/templates/README.txt
+    * a README file that explains the generated web-site directory structure and files
+  * Rakefile
+    * incorporating deployments with jeweler and gemcutter.  the combination is extremely powerful and seems alot more practical than maintaining my own rubygem server.  
+    
+  * inviting others to review my code and submitting patches!  long live the open-source community!

data/LICENSE

@@ -0,0 +1,20 @@
+Copyright (c) 2009 Ryan Sobol
+
+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.markdown

@@ -0,0 +1,152 @@
+![Following the Plow](http://img.skitch.com/20091010-jd9m46i9g5u4fyyprkfe36p4q9.gif)
+
+Image courtesy of [Mother Earth News](http://www.motherearthnews.com/Modern-Homesteading/1974-05-01/Walking-Plow.aspx)
+
+PLOW Release 0.1.0 (October 13th 2009)
+======================================
+
+Copyright © 2009 Ryan Sobol. Licensed under the MIT license.  Please see the {file:LICENSE} for more information.
+
+**Homepage**:       [http://github.com/ryansobol/plow](http://github.com/ryansobol/plow)  
+
+**Documentation**:  [http://rdoc.info/projects/ryansobol/plow](http://rdoc.info/projects/ryansobol/plow)  
+**Code Metrics**: [http://devver.net/caliper/project?repo=git%3A%2F%2Fgithub.com%2Fryansobol%2Fplow.git](http://devver.net/caliper/project?repo=git%3A%2F%2Fgithub.com%2Fryansobol%2Fplow.git)  
+
+WHAT'S NEW?
+-----------
+
+**v0.1.0**
+
+* Canonical 'plow' namespace reserved on [Gemcutter](http://gemcutter.org/gems/plow) and [Rubyforge](http://rubyforge.org/projects/plow/)
+
+I'm currently working at towards assembling a "complete software" package for you.  Please stay tuned for the official launch of version 1.0.0.  :D
+
+Please see {file:HISTORY} for the historical overview of the project.
+
+SYNOPSIS
+--------
+
+Plows the fertile soil of your filesystem into neatly organized plots of web-site templates
+
+FEATURES
+--------
+
+1. Sharpens it's blade by ensuring that both a Linux system user account and it's home path exist
+2. Penetrates the soil by forming the web-site root path within the user home
+3. Seeds the web-site with an index page and web server log files
+4. Fertilizes the web-site by installing a virtual host configuration into the web server
+
+REQUIREMENTS
+------------
+
+**Supported operating system + web server combinations**
+
+* Linux Ubuntu 8.04.3 LTS (Hardy Heron) + Apache 2.2.8
+
+**Required dependencies**
+
+* Ruby 1.9.1
+
+**Optional automated specification dependencies**
+
+* RSpec 1.2.8
+
+**Optional generated API documentation dependencies**
+
+* YARD 0.2.3.5
+* BlueCloth 2.0.5
+
+INSTALLING
+----------
+
+Plow is distributed though the RubyGems ecosystem.  Assuming you've already installed RubyGems, installing Plow is simple:
+
+    sudo gem install plow
+
+LET ME BE CRYSTAL CLEAR.  DO NOT INSTALL THIS PACKAGE TO ANY NON-ROOT USER'S GEM REPOSITORY.  YOU'VE BEEN WARNED.  Please see {file:SECURITY} for a detailed explanation of this advisory.
+
+Note that Plow is RubyGems **compatible** while also simultaneously **decoupled** from it.  Feel free to install Plow manually or use any Ruby package management system of your choice.
+
+USAGE
+-----
+
+    Usage: plow USER_NAME SITE_NAME [SITE_ALIAS ...]
+    
+    Arguments:
+      USER_NAME       Name of a Linux system account user (e.g. steve)
+      SITE_NAME       Name of the web-site (e.g. www.apple.com)
+      SITE_ALIAS      (Optional) List of alias names of the web-site (e.g. apple.com)
+
+Plow is bundled with two executables named `plow` and `plow1.9`.  They are nearly identical, but with the following exception:
+
+* `plow` executes using the shell environment's `ruby` binary.  (e.g. `#!/usr/bin/env ruby`)
+* `plow1.9` executes using the shell environment's `ruby1.9` binary.  (e.g. `#!/usr/bin/env ruby1.9`)
+
+**Note:** If your Ruby 1.9 binary is something other than `ruby1.9` (i.e. like `ruby19`) then you'll need to create a shell alias similar to the following:
+
+    alias ruby1.9="`which ruby19`"
+
+EXAMPLE
+-------
+
+    $ plow steve www.apple.com apple.com
+    
+    ... plow interation ...
+    
+    $ tree /home/steve/sites/
+    /home/steve/sites/
+    |-- README
+    `-- www.apple.com
+        |-- log
+        |   `-- apache2
+        |       |-- access.log
+        |       `-- error.log
+        `-- public
+            `-- index.html
+    
+    4 directories, 4 files
+    
+    $ ls -hal /home/steve/sites/www.apple.com/log/apache2/
+    total 196K
+    drwxr-x--- 2 root  steve 4.0K Sep  5 03:11 .
+    drwxr-xr-x 3 steve steve 4.0K Sep  5 03:09 ..
+    -rw-r----- 1 root  steve 136K Sep  9 11:10 access.log
+    -rw-r----- 1 root  steve  48K Sep  9 09:06 error.log
+
+MOTIVATION
+----------
+
+There exists numerous software products for controlling and/or managing a unix-based operating systems and web servers.  So, why did I decide to write yet another?  With Plow, I needed to prove to myself that I have the necessary proficiency **to contribute free, open-source, and complete software for the benefit human-kind**.
+
+The terms "free" and "open-source" are common enough to be implicitly understood, or at least, [easily googled](http://www.google.com/searchq=free+open-source).  But what of the term "complete software"?  For me, complete software means four exclusive characteristics:
+
+* Usability enhanced through elegant user-interface combined with straight-forward documentation
+* Stability verified through automated test specifications
+* Performance demonstrated through benchmarks
+* Sustainability preserved through both human and computer readable code
+
+I have tirelessly worked to achieve a high standard in all four characteristics.  As my peer, I am grateful of your input on improving this project in any of these areas.  Please see the sections on REPORTING ISSUES and CONTRIBUTING for further information.
+
+REPORTING ISSUES
+----------------
+
+Is Plow not behaving like you expect it should?  Please forgive me!  Would you take a moment to shed light on my negligence over at the [Issue Tracker](http://github.com/ryansobol/plow/issues)?  
+
+Thank you, in advance, for taking the time to help improve Plow.
+
+CONTRIBUTING
+------------
+
+Is Plow not behaving like you need?  Open-source to the rescue!  There is a plethora of documentation to bring you up to speed.  The API documentation is generated, once the dependencies are met (please see the REQUIREMENTS section), by running the follow:
+
+    $ rake yardoc
+
+Patches are always welcome and appreciated!  To contribute your work back to the source, the process is straight-forward:
+
+* Fork the project -- may I suggest [Github](http://www.github.com)?
+* Make your feature addition or bug fix with specifications -- it's important that I don't break your hard work in a future version unintentionally.
+* Please do not casually alter files in the project root. (e.g. HISTORY, LICENSE, Rakefile, README.markdown, ROAD-MAP, SECURITY, VERSION, etc.)
+* Commit your changes and publish the change-set.
+* Send me a pull request.  All specs must pass!
+
+Take a moment to get a feel for the style of coding, specifications, and in-line documentation.  I apologize in advance for setting the standards so high.  Please see {file:ROAD-MAP} to learn how to flow with the project.

data/ROAD-MAP

@@ -0,0 +1,10 @@
+== Improvements
+
+The obvious potential improvements are ported the package to additional operating systems and web servers.  This would require minimal, but completely worth-while structure changes Plow::Generator class.
+  
+  * Move all system administrative logic to model classes and redesign the class around the builder pattern to allow to construct user-determined classes dynamically at run-time
+  * Move all data validations to the same model classes or to new classes entirely, depending on the needs at the time
+  * More specific data validations
+  * Handing of more complex web application structures
+  * automatic deployment of web applications from github
+  * better argument parsing and including option flags as needed

data/Rakefile

@@ -0,0 +1,52 @@
+require 'rubygems'
+require 'rake'
+
+begin
+  require 'jeweler'
+  Jeweler::Tasks.new do |gem|
+    gem.name              = "plow"
+    gem.rubyforge_project = "plow"
+    gem.summary           = "Plows the fertile soil of your filesystem into neatly organized plots of web-site templates"
+    gem.description       = "Plows the fertile soil of your filesystem into neatly organized plots of web-site templates"
+    gem.email             = "code@ryansobol.com"
+    gem.homepage          = "http://github.com/ryansobol/plow"
+    gem.authors           = ["Ryan Sobol"]    
+    gem.add_development_dependency "rspec", "= 1.2.8"
+    gem.add_development_dependency "yard", "= 0.2.3.5"
+    gem.add_development_dependency "bluecloth", "= 2.0.5"  # hidden yard dependency for markdown support
+    # gem is a Gem::Specification... see http://www.rubygems.org/read/chapter/20 for additional settings
+  end
+  Jeweler::GemcutterTasks.new
+  
+  Jeweler::RubyforgeTasks.new do |task|
+    task.doc_task = "yardoc"
+  end
+rescue LoadError
+  puts "Jeweler (or a dependency) not available. Install it with: sudo gem install jeweler"
+end
+
+require 'spec/rake/spectask'
+Spec::Rake::SpecTask.new(:spec) do |task|
+  task.libs << 'lib' << 'spec'
+  task.spec_files = FileList['spec/**/*_spec.rb']
+  task.spec_opts  = %w{ -O spec/spec.opts }
+end
+
+Spec::Rake::SpecTask.new(:rcov) do |task|
+  task.libs << 'lib' << 'spec'
+  task.pattern = 'spec/**/*_spec.rb'
+  task.rcov    = true
+end
+
+task :spec => :check_dependencies
+
+task :default => :spec
+
+begin
+  require 'yard'
+  YARD::Rake::YardocTask.new
+rescue LoadError => e
+  task :yardoc do
+    abort "YARD is not available. In order to run yardoc, you must: sudo gem install yard"
+  end
+end

data/SECURITY

@@ -0,0 +1,14 @@
+== A Brief Note About Security
+
+Any and all processes invoking this library must be owned, aka executed, by the root user.  Root ownership is required by this package to automate system administrative tasks, including but not limited to:
+
+* Creating and/or modifying operating system user accounts that are _typically controlled by the root user_
+* Generating and installing virtual host configuration files for web servers that are _typically owned by the root user_
+
+By installing this package, you are acknowledging the risks inherit of the above implications.  If this package, including the library source code and it's non-compiled executables, is owned by any non-root user, then anyone who has or gains access to that non-root account could modify the code in this package, without your knowledge.  The next time you execute the program, as the root user, you could now be unwittingly comprising your own system by running malicious code injected into this package.
+
+If you wish to install this package as a RubyGem with a user account granted root privileges via sudo, then please install this package by running the following command:
+
+    sudo gem install plow
+
+LET ME BE CRYSTAL CLEAR.  DO NOT INSTALL THIS PACKAGE TO ANY NON-ROOT USER'S GEM REPOSITORY.  YOU'VE BEEN WARNED.

data/VERSION

@@ -0,0 +1 @@
+0.1.0

data/bin/plow

@@ -0,0 +1,10 @@
+#!/usr/bin/env ruby
+# encoding: UTF-8
+
+unless $LOAD_PATH.include?(File.expand_path(File.dirname(__FILE__) + '/../lib'))
+  $LOAD_PATH.unshift(File.expand_path(File.dirname(__FILE__) + '/../lib'))
+end
+
+require 'plow'
+
+Plow::Application.launch(*ARGV)

data/bin/plow1.9

@@ -0,0 +1,10 @@
+#!/usr/bin/env ruby1.9
+# encoding: UTF-8
+
+unless $LOAD_PATH.include?(File.expand_path(File.dirname(__FILE__) + '/../lib'))
+  $LOAD_PATH.unshift(File.expand_path(File.dirname(__FILE__) + '/../lib'))
+end
+
+require 'plow'
+
+Plow::Application.launch(*ARGV)

data/lib/plow/application.rb

@@ -0,0 +1,66 @@
+# encoding: UTF-8
+require 'plow/generator'
+
+class Plow
+  class Application
+    class << self
+      def launch(*arguments)
+        puts version_stamp
+        
+        if arguments.length < 2
+          abort <<-MESSAGE
+Usage: plow USER_NAME SITE_NAME [SITE_ALIAS ...]
+
+  Arguments:
+    USER_NAME       Name of a Linux system account user (e.g. steve)
+    SITE_NAME       Name of the web-site (e.g. www.apple.com)
+    SITE_ALIAS      (Optional) List of alias names of the web-site (e.g. apple.com)
+
+  Summary:
+    Plows the fertile soil of your filesystem into neatly organized plots of web-site templates
+
+  Description:
+    1. Sharpens it's blade by ensuring that both a Linux system user account and it's home path exist
+    2. Penetrates the soil by forming the web-site root path within the user home
+    3. Seeds the web-site with an index page and web server log files
+    4. Fertilizes the web-site by installing a virtual host configuration into the web server
+
+  Example:
+    plow steve www.apple.com apple.com
+MESSAGE
+        end
+        
+        user_name, site_name = arguments.first(2)
+        site_aliases         = arguments.drop(2)
+        
+        begin
+          generator = Plow::Generator.new(user_name, site_name, *site_aliases)
+          generator.run!
+          return 0
+        rescue Plow::InvalidSystemUserNameError => invalid
+          abort "ERROR: #{invalid} is an invalid system user name"
+        rescue Plow::InvalidWebSiteNameError => invalid
+          abort "ERROR: #{invalid} is an invalid web-site name"
+        rescue Plow::InvalidWebSiteAliasError => invalid
+          abort "ERROR: #{invalid} is an invalid web-site alias"
+        rescue Plow::NonRootProcessOwnerError
+          abort "ERROR: This process must be owned or executed by root"
+        rescue Plow::ReservedSystemUserNameError => reserved
+          abort "ERROR: #{reserved} is a reserved system user name"
+        rescue Plow::SystemUserNameNotFoundError => not_found
+          abort "ERROR: System user name #{not_found} cannot be found when it should exist"
+        rescue Plow::AppRootAlreadyExistsError => already_exists
+          abort "ERROR: Application root path #{already_exists} already exists"
+        rescue Plow::ConfigFileAlreadyExistsError => already_exists
+          abort "ERROR: Configuration file #{already_exists} already exists"
+        end
+      end
+      
+      private
+      
+      def version_stamp
+        "Plow v#{Plow::VERSION}. Copyright (c) 2009 Ryan Sobol. Licensed under the MIT license."
+      end
+    end
+  end
+end

data/lib/plow/binding_struct.rb

@@ -0,0 +1,15 @@
+# encoding: UTF-8
+
+class Plow
+  class BindingStruct
+    def initialize(hash)
+      hash.each_pair do |name, val|
+        instance_variable_set("@#{name}".to_sym, val)
+      end
+    end
+    
+    def get_binding
+      binding
+    end
+  end
+end

data/lib/plow/core_ext/object.rb

@@ -0,0 +1,8 @@
+# encoding: UTF-8
+
+class Object
+  # See http://api.rubyonrails.org/classes/Object.html#M000279
+  def blank?
+    respond_to?(:empty?) ? empty? : !self
+  end
+end

data/lib/plow/errors.rb

@@ -0,0 +1,27 @@
+# encoding: UTF-8
+
+class Plow
+  class NonRootProcessOwnerError < StandardError
+  end
+  
+  class InvalidSystemUserNameError < StandardError
+  end
+  
+  class InvalidWebSiteNameError < StandardError
+  end
+  
+  class InvalidWebSiteAliasError < StandardError
+  end
+  
+  class ReservedSystemUserNameError < StandardError
+  end
+  
+  class SystemUserNameNotFoundError < StandardError
+  end
+  
+  class AppRootAlreadyExistsError < StandardError
+  end
+  
+  class ConfigFileAlreadyExistsError < StandardError
+  end
+end

data/lib/plow/generator.rb

@@ -0,0 +1,57 @@
+# encoding: UTF-8
+
+require 'erb'
+
+require 'plow/binding_struct'
+require 'plow/strategy/ubuntu_hardy/user_home_web_app'
+
+class Plow
+  class Generator
+    attr_reader :user_name, :site_name, :site_aliases
+    attr_reader :strategy
+    
+    def initialize(user_name, site_name, *site_aliases)
+      if user_name.blank? || user_name.include?(' ')
+        raise(Plow::InvalidSystemUserNameError, user_name)
+      end
+      
+      if site_name.blank? || site_name.include?(' ')
+        raise(Plow::InvalidWebSiteNameError, site_name)
+      end
+      
+      site_aliases.each do |site_alias|
+        if site_alias.blank? || site_alias.include?(' ')
+          raise(Plow::InvalidWebSiteAliasError, site_alias)
+        end
+      end
+      
+      @user_name    = user_name
+      @site_name    = site_name
+      @site_aliases = site_aliases
+      
+      @strategy = Plow::Strategy::UbuntuHardy::UserHomeWebApp.new(self)
+    end
+    
+    def run!
+      raise Plow::NonRootProcessOwnerError unless Process.uid == 0
+      strategy.execute
+    end
+    
+    def say(message)
+      puts "==> #{message}"
+    end
+    
+    def shell(commands)
+      commands.each_line do |command|
+        command.strip!
+        system(command) unless command.blank?
+      end
+    end
+    
+    def evaluate_template(template_path, context)
+      template = File.read(template_path)
+      context_struct = Plow::BindingStruct.new(context)
+      ERB.new(template).result(context_struct.get_binding)
+    end
+  end  
+end

data/lib/plow/strategy/ubuntu_hardy/templates/README.txt

@@ -0,0 +1,19 @@
+$ tree sites/
+sites/
+|-- README
+`-- example.ryansobol.com
+    |-- log
+    |   `-- apache2
+    |       |-- access.log
+    |       `-- error.log
+    `-- public
+        `-- index.html
+
+4 directories, 4 files
+
+$ ls -hal sites/example.ryansobol.com/log/apache2/
+total 196K
+drwxr-x--- 2 root GROUP 4.0K Sep  5 03:11 .
+drwxr-xr-x 3 USER GROUP 4.0K Sep  5 03:09 ..
+-rw-r----- 1 root GROUP 136K Sep  9 11:10 access.log
+-rw-r----- 1 root GROUP  48K Sep  9 09:06 error.log

data/lib/plow/strategy/ubuntu_hardy/templates/apache2-vhost.conf

@@ -0,0 +1,14 @@
+<%# encoding: UTF-8 %>
+<VirtualHost *:80>
+  ServerAdmin webmaster
+  ServerName <%= @site_name %>
+  <% for site_alias in @site_aliases %>
+  ServerAlias <%= site_alias %>
+  <% end %>
+  DirectoryIndex index.html
+  DocumentRoot <%= @app_public_path %>
+  
+  LogLevel warn
+  ErrorLog  <%= @app_log_path %>/apache2/error.log
+  CustomLog <%= @app_log_path %>/apache2/access.log combined
+</VirtualHost>