0.15.0

Upstart process su'ing into wrong dir

.gitignore

@@ -1,6 +1,8 @@
+.bundle
 coverage
 example/log/*
-man/*.?
 man/*.html
 man/*.markdown
 pkg
+tags
+

Gemfile

@@ -0,0 +1,3 @@
+source "http://rubygems.org"
+
+gemspec

Gemfile.lock

@@ -0,0 +1,55 @@
+PATH
+  remote: .
+  specs:
+    foreman (0.15.0)
+      term-ansicolor (~> 1.0.5)
+      thor (>= 0.13.6)
+
+GEM
+  remote: http://rubygems.org/
+  specs:
+    crack (0.1.8)
+    diff-lcs (1.1.2)
+    fakefs (0.2.1)
+    hpricot (0.8.2)
+    mime-types (1.16)
+    mustache (0.11.2)
+    parka (0.6.2)
+      crack
+      rest-client
+      thor
+    rake (0.8.7)
+    rcov (0.9.8)
+    rdiscount (1.6.5)
+    rest-client (1.6.1)
+      mime-types (>= 1.16)
+    ronn (0.7.3)
+      hpricot (>= 0.8.2)
+      mustache (>= 0.7.0)
+      rdiscount (>= 1.5.8)
+    rr (1.0.2)
+    rspec (2.0.1)
+      rspec-core (~> 2.0.1)
+      rspec-expectations (~> 2.0.1)
+      rspec-mocks (~> 2.0.1)
+    rspec-core (2.0.1)
+    rspec-expectations (2.0.1)
+      diff-lcs (>= 1.1.2)
+    rspec-mocks (2.0.1)
+      rspec-core (~> 2.0.1)
+      rspec-expectations (~> 2.0.1)
+    term-ansicolor (1.0.5)
+    thor (0.14.6)
+
+PLATFORMS
+  ruby
+
+DEPENDENCIES
+  fakefs (~> 0.2.1)
+  foreman!
+  parka
+  rake
+  rcov (~> 0.9.8)
+  ronn
+  rr (~> 1.0.2)
+  rspec (~> 2.0.0)

README.markdown

@@ -1,4 +1,11 @@
-Foreman
+# Foreman
-=======
+
+## Manual
+
+http://blog.daviddollar.org/2011/05/06/introducing-foreman.html
 
 See the [man page](http://ddollar.github.com/foreman) for usage.
+
+## License
+
+MIT

Rakefile

@@ -1,3 +1,7 @@
+require "rubygems"
+require "bundler"
+Bundler.setup
+
 require "rake"
 require "rspec"
 require "rspec/core/rake_task"
@@ -21,7 +25,7 @@ end
 Rspec::Core::RakeTask.new("rcov:build") do |t|
   t.pattern = 'spec/**/*_spec.rb'
   t.rcov = true
-  t.rcov_opts = [ "--exclude", Gem.default_dir , "--exclude", "spec" ]
+  t.rcov_opts = [ "--exclude", ".bundle", "--exclude", "spec" ]
 end
 
 desc 'Build the manual'
@@ -29,57 +33,24 @@ task :man do
   ENV['RONN_MANUAL']  = "Foreman Manual"
   ENV['RONN_ORGANIZATION'] = "Foreman #{Foreman::VERSION}"
   sh "ronn -w -s toc -r5 --markdown man/*.ronn"
+end
+
+desc "Commit the manual to git"
+task "man:commit" => :man do
   sh "git add README.markdown"
   sh "git commit -m 'update readme' || echo 'nothing to commit'"
 end
 
-task :pages => :man do
+desc "Generate the Github docs"
+task :pages => "man:commit" do
   sh %{
     cp man/foreman.1.html /tmp/foreman.1.html
     git checkout gh-pages
     rm ./index.html
     cp /tmp/foreman.1.html ./index.html
     git add -u index.html
-    git commit -m "rebuilding man page"
+    git commit -m "saving man page to github docs"
     git push origin -f gh-pages
     git checkout master
   }
 end
-
-######################################################
-
-begin
-  require 'jeweler'
-  Jeweler::Tasks.new do |s|
-    s.name    = "foreman"
-    s.version = Foreman::VERSION
-
-    s.summary     = "Process manager for applications with multiple components"
-    s.description = s.summary
-    s.author      = "David Dollar"
-    s.email       = "ddollar@gmail.com"
-    s.homepage    = "http://github.com/ddollar/foreman"
-
-    s.platform = Gem::Platform::RUBY
-    s.has_rdoc = false
-
-    s.files = %w(Rakefile README.md) + Dir["{bin,export,lib,spec}/**/*"]
-    s.require_path = "lib"
-
-    # #s.bindir             = "bin"
-    # s.executables        = Dir["bin/*"]
-    s.default_executable = "foreman"
-
-    s.add_development_dependency 'fakefs', '~> 0.2.1'
-    s.add_development_dependency 'rake',   '~> 0.8.7'
-    s.add_development_dependency 'rcov',   '~> 0.9.8'
-    s.add_development_dependency 'rr',     '~> 0.10.11'
-    s.add_development_dependency 'rspec',  '~> 2.0.0'
-
-    s.add_dependency 'term-ansicolor', '~> 1.0.5'
-    s.add_dependency 'thor', '~> 0.13.6'
-  end
-  Jeweler::GemcutterTasks.new
-rescue LoadError
-  puts "Jeweler not available. Install it with: sudo gem install jeweler"
-end

data/example/Procfile

@@ -0,0 +1,2 @@
+ticker: ./ticker $PORT
+error : ./error

data/example/Procfile.without_colon

@@ -0,0 +1,2 @@
+ticker ./ticker $PORT
+error  ./error

data/example/log/neverdie.log

@@ -0,0 +1,4 @@
+tick
+tick
+./never_die:6:in `sleep': Interrupt
+	from ./never_die:6

data/example/ticker

@@ -1,6 +1,6 @@
 #!/usr/bin/env ruby
 
 while true
-  puts "tick"
+  puts "tick: #{ARGV.inspect}"
   sleep 1
 end

data/export/upstart/process.conf.erb

@@ -3,4 +3,4 @@ stop on stopping <%= app %>-<%= process.name %>
 respawn
 
 chdir <%= engine.directory %>
-exec su <%= user %> -c "PORT=<%= port %> <%= process.command %> >> <%= log_root %>/<%=process.name%>-<%=num%>.log 2>&1"
+exec su <%= user %> -c 'export PORT=<%= port %>; <%= process.command %> >> <%= log_root %>/<%=process.name%>-<%=num%>.log 2>&1'

example/Procfile

@@ -1,2 +0,0 @@
-ticker ./ticker
-error  ./error

foreman.gemspec

@@ -1,89 +1,29 @@
-# Generated by jeweler
+$:.unshift File.expand_path("../lib", __FILE__)
-# DO NOT EDIT THIS FILE DIRECTLY
+require "foreman/version"
-# Instead, edit Jeweler::Tasks in Rakefile, and run the gemspec command
-# -*- encoding: utf-8 -*-
 
-Gem::Specification.new do |s|
+Gem::Specification.new do |gem|
-  s.name = %q{foreman}
+  gem.name     = "foreman"
-  s.version = "0.7.0"
+  gem.version  = Foreman::VERSION
 
-  s.required_rubygems_version = Gem::Requirement.new(">= 0") if s.respond_to? :required_rubygems_version=
+  gem.author   = "David Dollar"
-  s.authors = ["David Dollar"]
+  gem.email    = "ddollar@gmail.com"
-  s.date = %q{2010-07-19}
+  gem.homepage = "http://github.com/ddollar/foreman"
-  s.default_executable = %q{foreman}
+  gem.summary  = "Process manager for applications with multiple components"
-  s.description = %q{Process manager for applications with multiple components}
-  s.email = %q{ddollar@gmail.com}
-  s.executables = ["foreman"]
-  s.extra_rdoc_files = [
-    "README.markdown"
-  ]
-  s.files = [
-    "Rakefile",
-     "bin/foreman",
-     "export/upstart/master.conf.erb",
-     "export/upstart/process.conf.erb",
-     "export/upstart/process_master.conf.erb",
-     "lib/foreman.rb",
-     "lib/foreman/cli.rb",
-     "lib/foreman/engine.rb",
-     "lib/foreman/export.rb",
-     "lib/foreman/export/base.rb",
-     "lib/foreman/export/inittab.rb",
-     "lib/foreman/export/upstart.rb",
-     "lib/foreman/process.rb",
-     "lib/foreman/utils.rb",
-     "spec/foreman/cli_spec.rb",
-     "spec/foreman/engine_spec.rb",
-     "spec/foreman/export/upstart_spec.rb",
-     "spec/foreman/export_spec.rb",
-     "spec/foreman/process_spec.rb",
-     "spec/foreman_spec.rb",
-     "spec/spec_helper.rb"
-  ]
-  s.homepage = %q{http://github.com/ddollar/foreman}
-  s.rdoc_options = ["--charset=UTF-8"]
-  s.require_paths = ["lib"]
-  s.rubygems_version = %q{1.3.7}
-  s.summary = %q{Process manager for applications with multiple components}
-  s.test_files = [
-    "spec/foreman/cli_spec.rb",
-     "spec/foreman/engine_spec.rb",
-     "spec/foreman/export/upstart_spec.rb",
-     "spec/foreman/export_spec.rb",
-     "spec/foreman/process_spec.rb",
-     "spec/foreman_spec.rb",
-     "spec/spec_helper.rb"
-  ]
 
-  if s.respond_to? :specification_version then
+  gem.description = gem.summary
-    current_version = Gem::Specification::CURRENT_SPECIFICATION_VERSION
-    s.specification_version = 3
 
-    if Gem::Version.new(Gem::VERSION) >= Gem::Version.new('1.2.0') then
+  gem.executables = "foreman"
-      s.add_development_dependency(%q<fakefs>, ["~> 0.2.1"])
+  gem.files = Dir["**/*"].select { |d| d =~ %r{^(README|bin/|data/|ext/|lib/|spec/|test/)} }
-      s.add_development_dependency(%q<rake>, ["~> 0.8.7"])
+  gem.files << "man/foreman.1"
-      s.add_development_dependency(%q<rcov>, ["~> 0.9.8"])
+
-      s.add_development_dependency(%q<rr>, ["~> 0.10.11"])
+  gem.add_dependency 'term-ansicolor', '~> 1.0.5'
-      s.add_development_dependency(%q<rspec>, ["~> 2.0.0"])
+  gem.add_dependency 'thor',           '>= 0.13.6'
-      s.add_runtime_dependency(%q<term-ansicolor>, ["~> 1.0.5"])
+
-      s.add_runtime_dependency(%q<thor>, ["~> 0.13.6"])
+  gem.add_development_dependency 'parka'
-    else
+  gem.add_development_dependency 'rake'
-      s.add_dependency(%q<fakefs>, ["~> 0.2.1"])
+  gem.add_development_dependency 'ronn'
-      s.add_dependency(%q<rake>, ["~> 0.8.7"])
+  gem.add_development_dependency 'fakefs', '~> 0.2.1'
-      s.add_dependency(%q<rcov>, ["~> 0.9.8"])
+  gem.add_development_dependency 'rcov',   '~> 0.9.8'
-      s.add_dependency(%q<rr>, ["~> 0.10.11"])
+  gem.add_development_dependency 'rr',     '~> 1.0.2'
-      s.add_dependency(%q<rspec>, ["~> 2.0.0"])
+  gem.add_development_dependency 'rspec',  '~> 2.0.0'
-      s.add_dependency(%q<term-ansicolor>, ["~> 1.0.5"])
-      s.add_dependency(%q<thor>, ["~> 0.13.6"])
-    end
-  else
-    s.add_dependency(%q<fakefs>, ["~> 0.2.1"])
-    s.add_dependency(%q<rake>, ["~> 0.8.7"])
-    s.add_dependency(%q<rcov>, ["~> 0.9.8"])
-    s.add_dependency(%q<rr>, ["~> 0.10.11"])
-    s.add_dependency(%q<rspec>, ["~> 2.0.0"])
-    s.add_dependency(%q<term-ansicolor>, ["~> 1.0.5"])
-    s.add_dependency(%q<thor>, ["~> 0.13.6"])
-  end
 end
-

lib/foreman.rb

@@ -1,6 +1,6 @@
-module Foreman
+require "foreman/version"
 
-  VERSION = "0.7.0"
+module Foreman
 
   class AppDoesNotExist < Exception; end
 

lib/foreman/cli.rb

@@ -2,13 +2,15 @@ require "foreman"
 require "foreman/engine"
 require "foreman/export"
 require "thor"
+require "yaml"
 
 class Foreman::CLI < Thor
 
-  class_option :procfile, :type => :string, :aliases => "-f", :desc => "Default: ./Procfile"
+  class_option :procfile, :type => :string, :aliases => "-f", :desc => "Default: Procfile"
 
   desc "start [PROCESS]", "Start the application, or a specific process"
 
+  method_option :port,        :type => :numeric, :aliases => "-p"
   method_option :concurrency, :type => :string,  :aliases => "-c",
     :banner => '"alpha=5,bar=3"'
 
@@ -35,8 +37,8 @@ class Foreman::CLI < Thor
     check_procfile!
 
     formatter = case format
-      when "upstart" then Foreman::Export::Upstart
       when "inittab" then Foreman::Export::Inittab
+      when "upstart" then Foreman::Export::Upstart
       else error "Unknown export format: #{format}."
     end
 
@@ -46,10 +48,18 @@ class Foreman::CLI < Thor
     error ex.message
   end
 
+  desc "check", "Validate your application's Procfile"
+
+  def check
+    processes = engine.processes_in_order.map { |p| p.first }
+    error "no processes defined" unless processes.length > 0
+    display "valid procfile detected (#{processes.join(', ')})"
+  end
+
 private ######################################################################
 
   def check_procfile!
-    error("Procfile does not exist.") unless File.exist?(procfile)
+    error("#{procfile} does not exist.") unless File.exist?(procfile)
   end
 
   def engine
@@ -57,10 +67,12 @@ private ######################################################################
   end
 
   def procfile
-    options[:procfile] || "./Procfile"
+    options[:procfile] || "Procfile"
   end
 
-private ######################################################################
+  def display(message)
+    puts message
+  end
 
   def error(message)
     puts "ERROR: #{message}"
@@ -71,4 +83,11 @@ private ######################################################################
     File.exist?(procfile)
   end
 
+  def options
+    original_options = super
+    return original_options unless File.exists?(".foreman")
+    defaults = YAML::load_file(".foreman")
+    Thor::CoreExt::HashWithIndifferentAccess.new(defaults.merge(original_options))
+  end
+
 end

lib/foreman/engine.rb

@@ -20,60 +20,77 @@ class Foreman::Engine
     @directory = File.expand_path(File.dirname(procfile))
   end
 
-  def processes(concurrency=nil)
+  def processes
     @processes ||= begin
-      concurrency = Foreman::Utils.parse_concurrency(concurrency)
+      @order = []
-
       procfile.split("\n").inject({}) do |hash, line|
         next if line.strip == ""
-        name, command = line.split(" ", 2)
+        name, command = line.split(/ *: +/, 2)
-
+        unless command
-        if concurrency[name] > 1 then
+          warn_deprecated_procfile!
-          1.upto(concurrency[name]) do |num|
+          name, command = line.split(/ +/, 2)
-            process = Foreman::Process.new("#{name}.#{num}", command)
-            process.color = next_color
-            hash[process.name] = process
-          end
-        else
-          process = Foreman::Process.new(name, command)
-          process.color = next_color
-          hash[process.name] = process
         end
-
+        process = Foreman::Process.new(name, command)
-        hash
+        process.color = next_color
+        @order << process.name
+        hash.update(process.name => process)
       end
     end
   end
 
+  def process_order
+    processes
+    @order.uniq
+  end
+
+  def processes_in_order
+    process_order.map do |name|
+      [name, processes[name]]
+    end
+  end
+
   def start(options={})
     proctitle "ruby: foreman master"
 
-    processes(options[:concurrency]).each do |name, process|
+    processes_in_order.each do |name, process|
-      fork process
+      fork process, options
     end
 
-    trap("TERM") { kill_and_exit("TERM") }
+    trap("TERM") { puts "SIGTERM received"; kill_all("TERM") }
-    trap("INT")  { kill_and_exit("INT")  }
+    trap("INT")  { puts "SIGINT received";  kill_all("TERM")  }
 
     watch_for_termination
   end
 
   def execute(name, options={})
-    processes(options[:concurrency]).values.select do |process|
+    fork processes[name], options
-      process.name =~ /\A#{name}\.?\d*\Z/
-    end.each do |process|
-      fork process
-    end
 
-    trap("TERM") { kill_and_exit("TERM") }
+    trap("TERM") { puts "SIGTERM received"; kill_all("TERM") }
-    trap("INT")  { kill_and_exit("INT")  }
+    trap("INT")  { puts "SIGINT received";  kill_all("TERM")  }
 
     watch_for_termination
   end
 
+  def port_for(process, num, base_port=nil)
+    base_port ||= 5000
+    offset = processes_in_order.map { |p| p.first }.index(process.name) * 100
+    base_port.to_i + offset + num - 1
+  end
+
 private ######################################################################
 
-  def fork(process)
+  def fork(process, options={})
+    concurrency = Foreman::Utils.parse_concurrency(options[:concurrency])
+
+    1.upto(concurrency[process.name]) do |num|
+      fork_individual(process, num, port_for(process, num, options[:port]))
+    end
+  end
+
+  def fork_individual(process, num, port)
+    ENV["PORT"] = port.to_s
+    ENV["PS"]   = "#{process.name}.#{num}"
+
     pid = Process.fork do
       run(process)
     end
@@ -82,32 +99,33 @@ private ######################################################################
     running_processes[pid] = process
   end
 
-  def run(process, log_to_file=true)
+  def run(process)
     proctitle "ruby: foreman #{process.name}"
 
-    Dir.chdir directory do
+    begin
-      FileUtils.mkdir_p "log"
+      Dir.chdir directory do
-      command = process.command
+        command = process.command
 
-      begin
         PTY.spawn("#{process.command} 2>&1") do |stdin, stdout, pid|
           until stdin.eof?
             info stdin.gets, process
           end
         end
-      rescue PTY::ChildExited, Interrupt
+      end
+    rescue PTY::ChildExited, Interrupt
+      begin
         info "process exiting", process
+      rescue Interrupt
       end
     end
   end
 
-  def kill_and_exit(signal="TERM")
+  def kill_all(signal="TERM")
     info "terminating"
     running_processes.each do |pid, process|
       info "killing #{process.name} in pid #{pid}"
       Process.kill(signal, pid)
     end
-    exit 0
   end
 
   def info(message, process=nil)
@@ -127,8 +145,8 @@ private ######################################################################
   end
 
   def pad_process_name(process)
-    name = process ? process.name : "system"
+    name = process ? "#{ENV["PS"]}" : "system"
-    name.ljust(longest_process_name)
+    name.ljust(longest_process_name + 3) # add 3 for process number padding
   end
 
   def print_info
@@ -150,7 +168,8 @@ private ######################################################################
     pid, status = Process.wait2
     process = running_processes.delete(pid)
     info "process terminated", process
-    kill_and_exit
+    kill_all
+    Process.waitall
   end
 
   def running_processes
@@ -163,4 +182,12 @@ private ######################################################################
     @current_color >= COLORS.length ? "" : COLORS[@current_color]
   end
 
+  def warn_deprecated_procfile!
+    return if @already_warned_deprecated
+    @already_warned_deprecated = true
+    puts "!!! This format of Procfile is deprecated, and will not work starting in v0.12"
+    puts "!!! Use a colon to separate the process name from the command"
+    puts "!!! e.g.   web: thin start"
+  end
+
 end

lib/foreman/export.rb

@@ -4,5 +4,5 @@ module Foreman::Export
   class Exception < ::Exception; end
 end
 
-require "foreman/export/upstart"
 require "foreman/export/inittab"
+require "foreman/export/upstart"

lib/foreman/export/base.rb

@@ -24,13 +24,7 @@ private ######################################################################
   end
 
   def export_template(name)
-    File.read(File.expand_path("../../../../export/#{name}", __FILE__))
+    File.read(File.expand_path("../../../../data/export/#{name}", __FILE__))
-  end
-
-  def port_for(base_port, app, num)
-    base_port ||= 5000
-    offset = engine.processes.keys.sort.index(app) * 100
-    base_port.to_i + offset + num - 1
   end
 
   def write_file(filename, contents)

lib/foreman/export/inittab.rb

@@ -7,7 +7,7 @@ class Foreman::Export::Inittab < Foreman::Export::Base
     user = options[:user] || app
     log_root = options[:log] || "/var/log/#{app}"
 
-    concurrency = parse_concurrency(options[:concurrency])
+    concurrency = Foreman::Utils.parse_concurrency(options[:concurrency])
 
     inittab = []
     inittab << "# ----- foreman #{app} processes -----"
@@ -15,7 +15,7 @@ class Foreman::Export::Inittab < Foreman::Export::Base
     engine.processes.values.inject(1) do |index, process|
       1.upto(concurrency[process.name]) do |num|
         id = app.slice(0, 2).upcase + sprintf("%02d", index)
-        port = port_for(options[:port], process.name, num)
+        port = engine.port_for(process, num, options[:port])
         inittab << "#{id}:4:respawn:/bin/su - #{user} -c 'PORT=#{port} #{process.command} >> #{log_root}/#{process.name}-#{num}.log 2>&1'"
         index += 1
       end
@@ -27,8 +27,8 @@ class Foreman::Export::Inittab < Foreman::Export::Base
     inittab = inittab.join("\n") + "\n"
 
     if fname
-      FileUtils.mkdir_p(log_root)
+      FileUtils.mkdir_p(log_root) rescue error "could not create #{log_root}"
-      FileUtils.chown(user, nil, log_root)
+      FileUtils.chown(user, nil, log_root) rescue error "could not chown #{log_root} to #{user}"
       write_file(fname, inittab)
     else
       puts inittab

lib/foreman/export/upstart.rb

@@ -17,7 +17,7 @@ class Foreman::Export::Upstart < Foreman::Export::Base
       FileUtils.rm(file)
     end
 
-    concurrency = parse_concurrency(options[:concurrency])
+    concurrency = Foreman::Utils.parse_concurrency(options[:concurrency])
 
     master_template = export_template("upstart/master.conf.erb")
     master_config   = ERB.new(master_template).result(binding)
@@ -31,7 +31,7 @@ class Foreman::Export::Upstart < Foreman::Export::Base
       write_file "#{location}/#{app}-#{process.name}.conf", process_master_config
 
       1.upto(concurrency[process.name]) do |num|
-        port = port_for(options[:port], process.name, num)
+        port = engine.port_for(process, num, options[:port])
         process_config = ERB.new(process_template).result(binding)
         write_file "#{location}/#{app}-#{process.name}-#{num}.conf", process_config
       end

lib/foreman/version.rb

@@ -0,0 +1,5 @@
+module Foreman
+
+  VERSION = "0.15.0"
+
+end

man/foreman.1

@@ -0,0 +1,194 @@
+.\" generated with Ronn/v0.7.3
+.\" http://github.com/rtomayko/ronn/tree/0.7.3
+.
+.TH "FOREMAN" "1" "May 2011" "Foreman 0.13.0" "Foreman Manual"
+.
+.SH "NAME"
+\fBforeman\fR \- manage Procfile\-based applications
+.
+.SH "SYNOPSIS"
+\fBforeman start [process]\fR
+.
+.br
+\fBforeman export <format> [location]\fR
+.
+.SH "DESCRIPTION"
+\fBForeman\fR is a manager for Procfile\-based applications\. Its aim is to abstract away the details of the Procfile format, and allow you to either run your application directly or export it to some other process management format\.
+.
+.SH "RUNNING"
+\fBforeman start\fR is used to run your application directly from the command line\.
+.
+.P
+If no additional parameters are passed, foreman will run one instance of each type of process defined in your Procfile\.
+.
+.P
+If a parameter is passed, foreman will run one instance of the specified application type\.
+.
+.P
+The following options control how the application is run:
+.
+.TP
+\fB\-c\fR, \fB\-\-concurrency\fR
+Specify the number of each process type to run\. The value passed in should be in the format \fBprocess=num,process=num\fR
+.
+.TP
+\fB\-p\fR, \fB\-\-port\fR
+Specify which port to use as the base for this application\. Should be a multiple of 1000\.
+.
+.SH "EXPORTING"
+\fBforeman export\fR is used to export your application to another process management format\.
+.
+.P
+An location to export can be passed as an argument\. This argument may be either required or optional depending on the export format\.
+.
+.P
+The following options control how the application is run:
+.
+.TP
+\fB\-a\fR, \fB\-\-app\fR
+Use this name rather than the application\'s root directory name as the name of the application when exporting\.
+.
+.TP
+\fB\-c\fR, \fB\-\-concurrency\fR
+Specify the number of each process type to run\. The value passed in should be in the format \fBprocess=num,process=num\fR
+.
+.TP
+\fB\-l\fR, \fB\-\-log\fR
+Specify the directory to place process logs in\.
+.
+.TP
+\fB\-p\fR, \fB\-\-port\fR
+Specify which port to use as the base for this application\. Should be a multiple of 1000\.
+.
+.TP
+\fB\-u\fR, \fB\-\-user\fR
+Specify the user the application should be run as\. Defaults to the app name
+.
+.SH "OPTIONS"
+These options control all modes of foreman\'s operation\.
+.
+.TP
+\fB\-f\fR, \fB\-\-procfile\fR
+Specify an alternate location for the application\'s Procfile\. This file\'s containing directory will be assumed to be the root directory of the application\.
+.
+.SH "EXPORT FORMATS"
+foreman currently supports the following output formats:
+.
+.IP "\(bu" 4
+inittab
+.
+.IP "\(bu" 4
+upstart
+.
+.IP "" 0
+.
+.SH "INITTAB EXPORT"
+Will export a chunk of inittab\-compatible configuration:
+.
+.IP "" 4
+.
+.nf
+
+# \-\-\-\-\- foreman example processes \-\-\-\-\-
+EX01:4:respawn:/bin/su \- example \-c \'PORT=5000 bundle exec thin start >> /var/log/web\-1\.log 2>&1\'
+EX02:4:respawn:/bin/su \- example \-c \'PORT=5100 bundle exec rake jobs:work >> /var/log/job\-1\.log 2>&1\'
+# \-\-\-\-\- end foreman example processes \-\-\-\-\-
+.
+.fi
+.
+.IP "" 0
+.
+.SH "UPSTART EXPORT"
+Will create a series of upstart scripts in the location you specify\. Scripts will be structured to make the following commands valid:
+.
+.P
+\fBstart appname\fR
+.
+.P
+\fBstop appname\-processname\fR
+.
+.P
+\fBrestart appname\-processname\-3\fR
+.
+.SH "PROCFILE"
+A Procfile should contain both a name for the process and the command used to run it\.
+.
+.IP "" 4
+.
+.nf
+
+web: bundle exec thin start
+job: bundle exec rake jobs:work
+.
+.fi
+.
+.IP "" 0
+.
+.P
+You can validate your Procfile format using the \fBcheck\fR command
+.
+.IP "" 4
+.
+.nf
+
+$ foreman check
+.
+.fi
+.
+.IP "" 0
+.
+.SH "DEFAULT OPTIONS"
+If a \fB\.foreman\fR file exists in the current directory, default options will be read from it\. This file should be in YAML format with the long option name as keys\. Example:
+.
+.IP "" 4
+.
+.nf
+
+concurrency: alpha=0
+port: 15000
+.
+.fi
+.
+.IP "" 0
+.
+.SH "EXAMPLES"
+Start one instance of each process type, interleave the output on stdout:
+.
+.IP "" 4
+.
+.nf
+
+$ foreman start
+.
+.fi
+.
+.IP "" 0
+.
+.P
+Export the application in upstart format:
+.
+.IP "" 4
+.
+.nf
+
+$ foreman export upstart /etc/init
+.
+.fi
+.
+.IP "" 0
+.
+.P
+Run one process type from the application defined in a specific Procfile:
+.
+.IP "" 4
+.
+.nf
+
+$ foreman start alpha \-p ~/myapp/Procfile
+.
+.fi
+.
+.IP "" 0
+.
+.SH "COPYRIGHT"
+Foreman is Copyright (C) 2010 David Dollar \fIhttp://daviddollar\.org\fR

man/foreman.1.ronn

@@ -29,6 +29,10 @@ The following options control how the application is run:
     Specify the number of each process type to run. The value passed in
     should be in the format `process=num,process=num`
 
+  * `-p`, `--port`:
+    Specify which port to use as the base for this application. Should be
+    a multiple of 1000.
+
 ## EXPORTING
 
 `foreman export` is used to export your application to another process
@@ -100,8 +104,21 @@ will be structured to make the following commands valid:
 A Procfile should contain both a name for the process and the command used
 to run it.
 
-    web  bundle exec thin start
+    web: bundle exec thin start
-    job  bundle exec rake jobs:work
+    job: bundle exec rake jobs:work
+
+You can validate your Procfile format using the `check` command
+
+    $ foreman check
+
+## DEFAULT OPTIONS
+
+If a `.foreman` file exists in the current directory, default options will
+be read from it. This file should be in YAML format with the long option
+name as keys. Example:
+
+    concurrency: alpha=0
+    port: 15000
 
 ## EXAMPLES
 
@@ -115,7 +132,7 @@ Export the application in upstart format:
 
 Run one process type from the application defined in a specific Procfile:
 
-    $ foreman start alpha -p ~/app/Procfile
+    $ foreman start alpha -p ~/myapp/Procfile
 
 ## COPYRIGHT
 

spec/foreman/cli_spec.rb

@@ -58,4 +58,27 @@ describe "Foreman::CLI" do
     end
   end
 
+  describe "check" do
+    describe "with a valid Procfile" do
+      before { write_procfile }
+
+      it "displays the jobs" do
+        mock(subject).display("valid procfile detected (alpha, bravo)")
+        subject.check
+      end
+    end
+
+    describe "with a blank Procfile" do
+      before do
+        FileUtils.touch("Procfile")
+      end
+
+      it "displays an error" do
+        mock_error(subject, "no processes defined") do
+          subject.check
+        end
+      end
+    end
+  end
+
 end

spec/foreman/engine_spec.rb

@@ -12,28 +12,51 @@ describe "Foreman::Engine" do
     end
 
     describe "with a Procfile" do
+      before { write_procfile }
+
       it "reads the processes" do
-        write_procfile
         subject.processes["alpha"].command.should == "./alpha"
         subject.processes["bravo"].command.should == "./bravo"
       end
     end
+
+    describe "with a deprecated Procfile" do
+      before do
+        File.open("Procfile", "w") do |file|
+          file.puts "name command"
+        end
+      end
+
+      it "should print a deprecation warning" do
+        mock(subject).warn_deprecated_procfile!
+        subject.processes.length.should == 1
+      end
+    end
   end
 
   describe "start" do
     it "forks the processes" do
       write_procfile
-      mock(subject).fork(subject.processes["alpha"])
+      mock(subject).fork(subject.processes["alpha"], {})
-      mock(subject).fork(subject.processes["bravo"])
+      mock(subject).fork(subject.processes["bravo"], {})
       mock(subject).watch_for_termination
       subject.start
     end
+
+    it "handles concurrency" do
+      write_procfile
+      mock(subject).fork_individual(subject.processes["alpha"], 1, 5000)
+      mock(subject).fork_individual(subject.processes["alpha"], 2, 5001)
+      mock(subject).fork_individual(subject.processes["bravo"], 1, 5100)
+      mock(subject).watch_for_termination
+      subject.start(:concurrency => "alpha=2")
+    end
   end
 
   describe "execute" do
     it "runs the processes" do
       write_procfile
-      mock(subject).fork(subject.processes["alpha"])
+      mock(subject).fork(subject.processes["alpha"], {})
       mock(subject).watch_for_termination
       subject.execute("alpha")
     end

spec/foreman/export/upstart_spec.rb

@@ -1,2 +1,21 @@
 require "spec_helper"
 require "foreman/export/upstart"
+
+describe Foreman::Export::Upstart do
+  let(:engine) { Foreman::Engine.new(write_procfile) }
+  let(:upstart) { Foreman::Export::Upstart.new(engine) }
+
+  before(:each) { load_export_templates_into_fakefs("upstart") }
+  before(:each) { stub(upstart).say }
+
+  it "exports to the filesystem" do
+    upstart.export("/tmp/init")
+
+    File.read("/tmp/init/foreman.conf").should         == example_export_file("upstart/foreman.conf")
+    File.read("/tmp/init/foreman-alpha.conf").should   == example_export_file("upstart/foreman-alpha.conf")
+    File.read("/tmp/init/foreman-alpha-1.conf").should == example_export_file("upstart/foreman-alpha-1.conf")
+    File.read("/tmp/init/foreman-alpha-2.conf").should == example_export_file("upstart/foreman-alpha-2.conf")
+    File.read("/tmp/init/foreman-bravo.conf").should   == example_export_file("upstart/foreman.bravo.conf")
+    File.read("/tmp/init/foreman-bravo-1.conf").should == example_export_file("upstart/foreman-bravo-1.conf")
+  end
+end

spec/resources/export/upstart/foreman-alpha-1.conf

@@ -0,0 +1,6 @@
+start on starting foreman-alpha
+stop on stopping foreman-alpha
+respawn
+
+chdir /Users/david/Code/foreman
+exec su foreman -c 'export PORT=5000; ./alpha >> /var/log/foreman/alpha-1.log 2>&1'

spec/resources/export/upstart/foreman-alpha-2.conf

@@ -0,0 +1,6 @@
+start on starting foreman-alpha
+stop on stopping foreman-alpha
+respawn
+
+chdir /Users/david/Code/foreman
+exec su foreman -c 'export PORT=5001; ./alpha >> /var/log/foreman/alpha-2.log 2>&1'

spec/resources/export/upstart/foreman-alpha.conf

@@ -0,0 +1,2 @@
+start on starting foreman
+stop on stopping foreman

spec/resources/export/upstart/foreman-bravo-1.conf

@@ -0,0 +1,6 @@
+start on starting foreman-bravo
+stop on stopping foreman-bravo
+respawn
+
+chdir /Users/david/Code/foreman
+exec su foreman -c 'export PORT=5100; ./bravo >> /var/log/foreman/bravo-1.log 2>&1'

spec/resources/export/upstart/foreman.bravo.conf

@@ -0,0 +1,2 @@
+start on starting foreman
+stop on stopping foreman

spec/resources/export/upstart/foreman.conf

@@ -0,0 +1,8 @@
+pre-start script
+
+bash << "EOF"
+  mkdir -p /var/log/foreman
+  chown -R foreman /var/log/foreman
+EOF
+
+end script

spec/spec_helper.rb

@@ -26,9 +26,30 @@ end
 
 def write_procfile(procfile="Procfile")
   File.open(procfile, "w") do |file|
-    file.puts "alpha ./alpha"
+    file.puts "alpha: ./alpha"
-    file.puts "bravo ./bravo"
+    file.puts "bravo: ./bravo"
   end
+  File.expand_path(procfile)
+end
+
+def load_export_templates_into_fakefs(type)
+  FakeFS.deactivate!
+  files = Dir[File.expand_path("../../data/export/#{type}/**", __FILE__)].inject({}) do |hash, file|
+    hash.update(file => File.read(file))
+  end
+  FakeFS.activate!
+  files.each do |filename, contents|
+    File.open(filename, "w") do |f|
+      f.puts contents
+    end
+  end
+end
+
+def example_export_file(filename)
+  FakeFS.deactivate!
+  data = File.read(File.expand_path("../resources/export/#{filename}", __FILE__))
+  FakeFS.activate!
+  data
 end
 
 Rspec.configure do |config|