unicorn-fotopedia 0.99.1

data/SIGNALS

@@ -0,0 +1,109 @@
+== Signal handling
+
+In general, signals need only be sent to the master process.  However,
+the signals Unicorn uses internally to communicate with the worker
+processes are documented here as well.  With the exception of TTIN/TTOU,
+signal handling matches the behavior of {nginx}[http://nginx.net/] so it
+should be possible to easily share process management scripts between
+Unicorn and nginx.
+
+=== Master Process
+
+* HUP - reloads config file and gracefully restart all workers.
+  If the "preload_app" directive is false (the default), then workers
+  will also pick up any application code changes when restarted.  If
+  "preload_app" is true, then application code changes will have no
+  effect; USR2 + QUIT (see below) must be used to load newer code in
+  this case.
+
+* INT/TERM - quick shutdown, kills all workers immediately
+
+* QUIT - graceful shutdown, waits for workers to finish their
+  current request before finishing.
+
+* USR1 - reopen all logs owned by the master and all workers
+  See Unicorn::Util.reopen_logs for what is considered a log.
+
+* USR2 - reexecute the running binary.  A separate QUIT
+  should be sent to the original process once the child is verified to
+  be up and running.
+
+* WINCH - gracefully stops workers but keep the master running.
+  This will only work for daemonized processes.
+
+* TTIN - increment the number of worker processes by one
+
+* TTOU - decrement the number of worker processes by one
+
+=== Worker Processes
+
+Sending signals directly to the worker processes should not normally be
+needed.  If the master process is running, any exited worker will be
+automatically respawned.
+
+* INT/TERM - Quick shutdown, immediately exit.
+  Unless WINCH has been sent to the master (or the master is killed),
+  the master process will respawn a worker to replace this one.
+
+* QUIT - Gracefully exit after finishing the current request.
+  Unless WINCH has been sent to the master (or the master is killed),
+  the master process will respawn a worker to replace this one.
+
+* USR1 - Reopen all logs owned by the worker process.
+  See Unicorn::Util.reopen_logs for what is considered a log.
+  Log files are not reopened until it is done processing
+  the current request, so multiple log lines for one request
+  (as done by Rails) will not be split across multiple logs.
+
+  It is NOT recommended to send the USR1 signal directly to workers via
+  "killall -USR1 unicorn" if you are using user/group-switching support
+  in your workers.  You will encounter incorrect file permissions and
+  workers will need to be respawned.  Sending USR1 to the master process
+  first will ensure logs have the correct permissions before the master
+  forwards the USR1 signal to workers.
+
+=== Procedure to replace a running unicorn executable
+
+You may replace a running instance of unicorn with a new one without
+losing any incoming connections.  Doing so will reload all of your
+application code, Unicorn config, Ruby executable, and all libraries.
+The only things that will not change (due to OS limitations) are:
+
+1. The path to the unicorn executable script.  If you want to change to
+   a different installation of Ruby, you can modify the shebang
+   line to point to your alternative interpreter.
+
+The procedure is exactly like that of nginx:
+
+1. Send USR2 to the master process
+
+2. Check your process manager or pid files to see if a new master spawned
+   successfully.  If you're using a pid file, the old process will have
+   ".oldbin" appended to its path.  You should have two master instances
+   of unicorn running now, both of which will have workers servicing
+   requests.  Your process tree should look something like this:
+
+     unicorn master (old)
+     \_ unicorn worker[0]
+     \_ unicorn worker[1]
+     \_ unicorn worker[2]
+     \_ unicorn worker[3]
+     \_ unicorn master
+        \_ unicorn worker[0]
+        \_ unicorn worker[1]
+        \_ unicorn worker[2]
+        \_ unicorn worker[3]
+
+3. You can now send WINCH to the old master process so only the new workers
+   serve requests.  If your unicorn process is bound to an interactive
+   terminal, you can skip this step.  Step 5 will be more difficult but
+   you can also skip it if your process is not daemonized.
+
+4. You should now ensure that everything is running correctly with the
+   new workers as the old workers die off.
+
+5. If everything seems ok, then send QUIT to the old master.  You're done!
+
+   If something is broken, then send HUP to the old master to reload
+   the config and restart its workers.  Then send QUIT to the new master
+   process.

data/Sandbox

@@ -0,0 +1,78 @@
+= Tips for using \Unicorn with Sandbox installation tools
+
+Since unicorn includes executables and is usually used to start a Ruby
+process, there are certain caveats to using it with tools that sandbox
+RubyGems installations such as
+{Bundler}[http://github.com/carlhuda/bundler] or
+{Isolate}[http://github.com/jbarnette/isolate].
+
+== General deployment
+
+If you're sandboxing your unicorn installation and using Capistrano (or
+similar), it's required that you sandbox your RubyGems in a per-application
+shared directory that can be used between different revisions.
+
+unicorn will stash its original command-line at startup for the USR2
+upgrades, and cleaning up old revisions will cause revision-specific
+installations of unicorn to go missing and upgrades to fail.   If you
+find yourself in this situation and can't afford downtime, you can
+override the existing unicorn executable path in the config file like
+this:
+
+        Unicorn::HttpServer::START_CTX[0] = "/some/path/to/bin/unicorn"
+
+Then use HUP to reload, and then continue with the USR2+QUIT upgrade
+sequence.
+
+== Bundler
+
+=== Running
+
+If you're bundling unicorn, use "bundle exec unicorn" (or "bundle exec
+unicorn_rails") to start unicorn with the correct environment variables
+
+ref: http://mid.gmane.org/9ECF07C4-5216-47BE-961D-AFC0F0C82060@internetfamo.us
+
+Otherwise (if you choose to not sandbox your unicorn installation), we
+expect the tips for Isolate (below) apply, too.
+
+=== RUBYOPT pollution from SIGUSR2 upgrades
+
+This is no longer be an issue as of bundler 0.9.17
+
+ref: http://mid.gmane.org/8FC34B23-5994-41CC-B5AF-7198EF06909E@tramchase.com
+
+== Isolate
+
+=== Running
+
+Installing "unicorn" as a system-wide Rubygem and using the
+isolate gem may cause issues if you're using any of the bundled
+application-level libraries in unicorn/app/* (for compatibility
+with CGI-based applications, Rails <= 2.2.2, or ExecCgi).
+For now workarounds include doing one of the following:
+
+1. Isolating unicorn, setting GEM_HOME to your Isolate path,
+   and running the isolated version of unicorn.  You *must* set
+   GEM_HOME before running your isolated unicorn install in this way.
+
+2.  Installing the same version of unicorn as a system-wide Rubygem
+    *and* isolating unicorn as well.
+
+3. Explicitly setting RUBYLIB or $LOAD_PATH to include any gem path
+   where the unicorn gem is installed
+   (e.g. /usr/lib/ruby/gems/1.9.1/gems/unicorn-VERSION/lib)
+
+=== RUBYOPT pollution from SIGUSR2 upgrades
+
+If you are using Isolate, using Isolate 2.x is strongly recommended as
+environment modifications are idempotent.
+
+If you are stuck with 1.x versions of Isolate, it is recommended that
+you disable it with the <tt>before_exec</tt> hook prevent the PATH and
+RUBYOPT environment variable modifications from propagating between
+upgrades in your Unicorn config file:
+
+        before_exec do |server|
+          Isolate.disable
+        end

data/TODO

@@ -0,0 +1,5 @@
+* Documentation improvements
+
+* performance validation (esp. TeeInput)
+
+* improve test suite

data/TUNING

@@ -0,0 +1,70 @@
+= Tuning Unicorn
+
+Unicorn performance is generally as good as a (mostly) Ruby web server
+can provide.  Most often the performance bottleneck is in the web
+application running on Unicorn rather than Unicorn itself.
+
+== Unicorn Configuration
+
+See Unicorn::Configurator for details on the config file format.
+
+* Setting a very low value for the :backlog parameter in "listen"
+  directives can allow failover to happen more quickly if your
+  cluster is configured for it.
+
+* If you're doing extremely simple benchmarks and getting connection
+  errors under high request rates, increasing your :backlog parameter
+  above the already-generous default of 1024 can help avoid connection
+  errors.  Keep in mind this is not recommended for real traffic if
+  you have another machine to failover to (see above).
+
+* :rcvbuf and :sndbuf parameters generally do not need to be set for TCP
+  listeners under Linux 2.6 because auto-tuning is enabled.  UNIX domain
+  sockets do not have auto-tuning buffer sizes; so increasing those will
+  allow syscalls and task switches to be saved for larger requests
+  and responses.
+
+* Setting "preload_app true" can allow copy-on-write-friendly GC to
+  be used to save memory.  It will probably not work out of the box with
+  applications that open sockets or perform random I/O on files.
+  Databases like TokyoCabinet use concurrency-safe pread()/pwrite()
+  functions for safe sharing of database file descriptors across
+  processes.
+
+* On POSIX-compliant filesystems, it is safe for multiple threads or
+  processes to append to one log file as long as all the processes are
+  have them unbuffered (File#sync = true) or they are
+  record(line)-buffered in userspace.
+
+* worker_processes should be scaled to the number of processes your
+  backend system(s) can support.  DO NOT scale it to the number of
+  external network clients your application expects to be serving.
+  Unicorn is NOT for serving slow clients, that is the job of nginx.
+
+== Kernel Parameters (Linux sysctl)
+
+WARNING: Do not change system parameters unless you know what you're doing!
+
+* net.core.rmem_max and net.core.wmem_max can increase the allowed
+  size of :rcvbuf and :sndbuf respectively. This is mostly only useful
+  for UNIX domain sockets which do not have auto-tuning buffer sizes.
+
+* For load testing/benchmarking with UNIX domain sockets, you should
+  consider increasing net.core.somaxconn or else nginx will start
+  failing to connect under heavy load.  You may also consider setting
+  a higher :backlog to listen on as noted earlier.
+
+* If you're running out of local ports, consider lowering
+  net.ipv4.tcp_fin_timeout to 20-30 (default: 60 seconds).  Also
+  consider widening the usable port range by changing
+  net.ipv4.ip_local_port_range.
+
+* Setting net.ipv4.tcp_timestamps=1 will also allow setting
+  net.ipv4.tcp_tw_reuse=1 and net.ipv4.tcp_tw_recycle=1, which along
+  with the above settings can slow down port exhaustion.  Not all
+  networks are compatible with these settings, check with your friendly
+  network administrator before changing these.
+
+* Increasing the MTU size can reduce framing overhead for larger
+  transfers.  One often-overlooked detail is that the loopback
+  device (usually "lo") can have its MTU increased, too.

data/bin/unicorn

@@ -0,0 +1,126 @@
+#!/this/will/be/overwritten/or/wrapped/anyways/do/not/worry/ruby
+# -*- encoding: binary -*-
+require 'unicorn/launcher'
+require 'optparse'
+
+ENV["RACK_ENV"] ||= "development"
+daemonize = false
+options = { :listeners => [] }
+host, port = Unicorn::Const::DEFAULT_HOST, Unicorn::Const::DEFAULT_PORT
+set_listener = false
+
+opts = OptionParser.new("", 24, '  ') do |opts|
+  opts.banner = "Usage: #{File.basename($0)} " \
+                "[ruby options] [unicorn options] [rackup config file]"
+
+  opts.separator "Ruby options:"
+
+  lineno = 1
+  opts.on("-e", "--eval LINE", "evaluate a LINE of code") do |line|
+    eval line, TOPLEVEL_BINDING, "-e", lineno
+    lineno += 1
+  end
+
+  opts.on("-d", "--debug", "set debugging flags (set $DEBUG to true)") do
+    $DEBUG = true
+  end
+
+  opts.on("-w", "--warn", "turn warnings on for your script") do
+    $-w = true
+  end
+
+  opts.on("-I", "--include PATH",
+          "specify $LOAD_PATH (may be used more than once)") do |path|
+    $LOAD_PATH.unshift(*path.split(/:/))
+  end
+
+  opts.on("-r", "--require LIBRARY",
+          "require the library, before executing your script") do |library|
+    require library
+  end
+
+  opts.separator "Unicorn options:"
+
+  # some of these switches exist for rackup command-line compatibility,
+
+  opts.on("-o", "--host HOST",
+          "listen on HOST (default: #{Unicorn::Const::DEFAULT_HOST})") do |h|
+    host = h
+    set_listener = true
+  end
+
+  opts.on("-p", "--port PORT",
+          "use PORT (default: #{Unicorn::Const::DEFAULT_PORT})") do |p|
+    port = p.to_i
+    set_listener = true
+  end
+
+  opts.on("-E", "--env ENVIRONMENT",
+          "use ENVIRONMENT for defaults (default: development)") do |e|
+    ENV["RACK_ENV"] = e
+  end
+
+  opts.on("-D", "--daemonize", "run daemonized in the background") do |d|
+    daemonize = d ? true : false
+  end
+
+  opts.on("-P", "--pid FILE", "DEPRECATED") do |f|
+    warn %q{Use of --pid/-P is strongly discouraged}
+    warn %q{Use the 'pid' directive in the Unicorn config file instead}
+    options[:pid] = f
+  end
+
+  opts.on("-s", "--server SERVER",
+          "this flag only exists for compatibility") do |s|
+    warn "-s/--server only exists for compatibility with rackup"
+  end
+
+  # Unicorn-specific stuff
+  opts.on("-l", "--listen {HOST:PORT|PATH}",
+          "listen on HOST:PORT or PATH",
+          "this may be specified multiple times",
+          "(default: #{Unicorn::Const::DEFAULT_LISTEN})") do |address|
+    options[:listeners] << address
+  end
+
+  opts.on("-c", "--config-file FILE", "Unicorn-specific config file") do |f|
+    options[:config_file] = f
+  end
+
+  # I'm avoiding Unicorn-specific config options on the command-line.
+  # IMNSHO, config options on the command-line are redundant given
+  # config files and make things unnecessarily complicated with multiple
+  # places to look for a config option.
+
+  opts.separator "Common options:"
+
+  opts.on_tail("-h", "--help", "Show this message") do
+    puts opts.to_s.gsub(/^.*DEPRECATED.*$/s, '')
+    exit
+  end
+
+  opts.on_tail("-v", "--version", "Show version") do
+    puts "unicorn v#{Unicorn::Const::UNICORN_VERSION}"
+    exit
+  end
+
+  opts.parse! ARGV
+end
+
+ru = ARGV[0] || "config.ru"
+abort "configuration file #{ru} not found" unless File.exist?(ru)
+
+app = Unicorn.builder(ru, opts)
+options[:listeners] << "#{host}:#{port}" if set_listener
+
+if $DEBUG
+  require 'pp'
+  pp({
+    :unicorn_options => options,
+    :app => app,
+    :daemonize => daemonize,
+  })
+end
+
+Unicorn::Launcher.daemonize!(options) if daemonize
+Unicorn.run(app, options)

data/bin/unicorn_rails

@@ -0,0 +1,203 @@
+#!/this/will/be/overwritten/or/wrapped/anyways/do/not/worry/ruby
+# -*- encoding: binary -*-
+require 'unicorn/launcher'
+require 'optparse'
+require 'fileutils'
+
+daemonize = false
+options = { :listeners => [] }
+host, port = Unicorn::Const::DEFAULT_HOST, Unicorn::Const::DEFAULT_PORT
+set_listener = false
+ENV['RAILS_ENV'] ||= "development"
+
+opts = OptionParser.new("", 24, '  ') do |opts|
+  cmd = File.basename($0)
+  opts.banner = "Usage: #{cmd} " \
+                "[ruby options] [#{cmd} options] [rackup config file]"
+  opts.separator "Ruby options:"
+
+  lineno = 1
+  opts.on("-e", "--eval LINE", "evaluate a LINE of code") do |line|
+    eval line, TOPLEVEL_BINDING, "-e", lineno
+    lineno += 1
+  end
+
+  opts.on("-d", "--debug", "set debugging flags (set $DEBUG to true)") do
+    $DEBUG = true
+  end
+
+  opts.on("-w", "--warn", "turn warnings on for your script") do
+    $-w = true
+  end
+
+  opts.on("-I", "--include PATH",
+          "specify $LOAD_PATH (may be used more than once)") do |path|
+    $LOAD_PATH.unshift(*path.split(/:/))
+  end
+
+  opts.on("-r", "--require LIBRARY",
+          "require the library, before executing your script") do |library|
+    require library
+  end
+
+  opts.separator "#{cmd} options:"
+
+  # some of these switches exist for rackup command-line compatibility,
+
+  opts.on("-o", "--host HOST",
+          "listen on HOST (default: #{Unicorn::Const::DEFAULT_HOST})") do |h|
+    host = h
+    set_listener = true
+  end
+
+  opts.on("-p", "--port PORT", "use PORT (default: #{port})") do |p|
+    port = p.to_i
+    set_listener = true
+  end
+
+  opts.on("-E", "--env RAILS_ENV",
+          "use RAILS_ENV for defaults (default: development)") do |e|
+    ENV['RAILS_ENV'] = e
+  end
+
+  opts.on("-D", "--daemonize", "run daemonized in the background") do |d|
+    daemonize = d ? true : false
+  end
+
+  # Unicorn-specific stuff
+  opts.on("-l", "--listen {HOST:PORT|PATH}",
+          "listen on HOST:PORT or PATH",
+          "this may be specified multiple times",
+          "(default: #{Unicorn::Const::DEFAULT_LISTEN})") do |address|
+    options[:listeners] << address
+  end
+
+  opts.on("-c", "--config-file FILE", "Unicorn-specific config file") do |f|
+    options[:config_file] = f
+  end
+
+  opts.on("-P PATH", "DEPRECATED") do |v|
+    warn %q{Use of -P is ambiguous and discouraged}
+    warn %q{Use --path or RAILS_RELATIVE_URL_ROOT instead}
+    ENV['RAILS_RELATIVE_URL_ROOT'] = v
+  end
+
+  opts.on("--path PATH", "Runs Rails app mounted at a specific path.",
+          "(default: /)") do |v|
+    ENV['RAILS_RELATIVE_URL_ROOT'] = v
+  end
+
+  # I'm avoiding Unicorn-specific config options on the command-line.
+  # IMNSHO, config options on the command-line are redundant given
+  # config files and make things unnecessarily complicated with multiple
+  # places to look for a config option.
+
+  opts.separator "Common options:"
+
+  opts.on_tail("-h", "--help", "Show this message") do
+    puts opts.to_s.gsub(/^.*DEPRECATED.*$/s, '')
+    exit
+  end
+
+  opts.on_tail("-v", "--version", "Show version") do
+    puts " v#{Unicorn::Const::UNICORN_VERSION}"
+    exit
+  end
+
+  opts.parse! ARGV
+end
+
+ru = ARGV[0] || (File.exist?('config.ru') ? 'config.ru' : nil)
+
+if ru && ru =~ /\.ru\z/
+  # parse embedded command-line options in config.ru comments
+  /^#\\(.*)/ =~ File.read(ru) and opts.parse!($1.split(/\s+/))
+end
+
+def rails_builder(ru, daemonize)
+  # this lambda won't run until after forking if preload_app is false
+  lambda do ||
+    # Load Rails and (possibly) the private version of Rack it bundles.
+    begin
+      require 'config/boot'
+    rescue LoadError => err
+      abort "#$0 must be run inside RAILS_ROOT: #{err.inspect}"
+    end
+
+    inner_app = case ru
+    when nil
+      require 'config/environment'
+
+      defined?(::Rails::VERSION::STRING) or
+        abort "Rails::VERSION::STRING not defined by config/{boot,environment}"
+      # it seems Rails >=2.2 support Rack, but only >=2.3 requires it
+      old_rails = case ::Rails::VERSION::MAJOR
+      when 0, 1 then true
+      when 2 then Rails::VERSION::MINOR < 3 ? true : false
+      else
+        false
+      end
+
+      if old_rails
+        require 'unicorn/app/old_rails'
+        Unicorn::App::OldRails.new
+      else
+        ActionController::Dispatcher.new
+      end
+    when /\.ru$/
+      raw = File.read(ru)
+      raw.sub!(/^__END__\n.*/, '')
+      eval("Rack::Builder.new {(#{raw}\n)}.to_app", TOPLEVEL_BINDING, ru)
+    else
+      require ru
+      Object.const_get(File.basename(ru, '.rb').capitalize)
+    end
+
+    Rack::Builder.new do
+      map_path = ENV['RAILS_RELATIVE_URL_ROOT'] || '/'
+      if inner_app.class.to_s == "Unicorn::App::OldRails"
+        if map_path != '/'
+          # patches + tests welcome, but I really cbf to deal with this
+          # since all apps I've ever dealt with just use "/" ...
+          $stderr.puts "relative URL roots may not work for older Rails"
+        end
+        $stderr.puts "LogTailer not available for Rails < 2.3" unless daemonize
+        $stderr.puts "Debugger not available" if $DEBUG
+        map(map_path) do
+          use Unicorn::App::OldRails::Static
+          run inner_app
+        end
+      else
+        use Rails::Rack::LogTailer unless daemonize
+        use Rails::Rack::Debugger if $DEBUG
+        map(map_path) do
+          use Rails::Rack::Static
+          run inner_app
+        end
+      end
+    end.to_app
+  end
+end
+
+app = rails_builder(ru, daemonize)
+options[:listeners] << "#{host}:#{port}" if set_listener
+
+if $DEBUG
+  require 'pp'
+  pp({
+    :unicorn_options => options,
+    :app => app,
+    :daemonize => daemonize,
+  })
+end
+
+# ensure Rails standard tmp paths exist
+options[:after_reload] = lambda do
+  FileUtils.mkdir_p(%w(cache pids sessions sockets).map! { |d| "tmp/#{d}" })
+end
+
+if daemonize
+  options[:pid] = "tmp/pids/unicorn.pid"
+  Unicorn::Launcher.daemonize!(options)
+end
+Unicorn.run(app, options)