README

   1 = Zbatery: Rack HTTP server without a fork stuck in it
   2
   3 Zbatery is an HTTP server for Rack applications on systems that either
   4 do not support fork(), or have no memory (nor need) to run the
   5 master/worker model.  It is based on Rainbows! (which is based on
   6 Unicorn (which is based on Mongrel)) and inherits parts of each.
   7 Zbatery supports your choice of all the thread/fiber/event/actor-based
   8 concurrency models and Rack middleware that Rainbows! supports (or will
   9 ever support) in a single process.
  10
  11 Zbatery will still exploit certain features of Unix for transparent
  12 upgrades, log reopening, and graceful stops, but does not rely on them
  13 for basic functionality.
  14
  15 == Features
  16
  17 * Designed for {Rack}[http://rack.rubyforge.org/], the standard for
  18   modern Ruby HTTP applications.
  19
  20 * Configuration files are compatible with Rainbows!, a superset
  21   of the Unicorn
  22   {DSL}[http://unicorn.bogomips.org/Unicorn/Configurator.html].
  23
  24 * Inherits all features and concurrency models Rainbows! supports
  25   (and ever will support): http://rainbows.rubyforge.org/Summary.html
  26
  27 * -Untested- Works under operating systems that don't support signals,
  28   pipe and fork().  Unicorn 0.95.2+ has rake-compiler support, so
  29   compiling the HTTP parser should be easier at least.
  30
  31 * Web Sockets support (via
  32   {Sunshowers}[http://rainbows.rubyforge.org/sunshowers/]), requires
  33   Rainbows! 0.9.0+
  34
  35 == License
  36
  37 \Zbatery is copyright 2009,2010,2011 by all contributors (see logs in git).
  38 \Zbatery is licensed under the Ruby (1.8) license or the GPL (v2 or v3).
  39 See the included {LICENSE}[link:LICENSE.html] file for more details.
  40
  41 \Zbatery is 100% Free Software.
  42
  43 == Install
  44
  45 You may download the tarball from the Rainbows project page on Rubyforge
  46 and run setup.rb after unpacking it (and installing Unicorn and Rainbows!):
  47
  48 http://rubyforge.org/frs/?group_id=8977
  49
  50 You may also install it via RubyGems on Gemcutter:
  51
  52   gem install zbatery
  53
  54 Zbatery depends on Rainbows!, and in turn, Unicorn.  Despite Unicorn and
  55 Rainbows! being Unix-only, the Unicorn HTTP parser C extension should
  56 build on non-Unix-like systems (unverified).
  57
  58 == Usage
  59
  60 === for Rack applications
  61
  62 In APP_ROOT (where config.ru is located), run:
  63
  64   zbatery
  65
  66 Zbatery will bind to all interfaces on TCP port 8080 by default.
  67
  68 === Configuration File(s)
  69
  70 Zbatery will look for the config.ru file used by rackup in APP_ROOT.
  71
  72 For deployments, it can use a config file for Unicorn and
  73 Rainbows!-specific options specified by the +--config-file/-c+
  74 command-line switch.  Zbatery accepts all options found in
  75 {Unicorn::Configurator}[http://unicorn.bogomips.org/Unicorn/Configurator.html]
  76 as well as the "Rainbows!" block, so you can have the following in your
  77 config file:
  78
  79     Rainbows! do
  80       use :FiberSpawn
  81       worker_connections 400
  82     end
  83
  84 See the Rainbows! configuration
  85 {documentation}[http://rainbows.rubyforge.org/Rainbows.html#M000001]
  86 for more details.
  87
  88 == Disclaimer
  89
  90 There is NO WARRANTY whatsoever if anything goes wrong, but let us know
  91 and we'll try our best to fix it.
  92
  93 This project may be temporary and may eventually have its name encoded
  94 with uncrackable ROT13 encryption leaving you with no way to upgrade.
  95
  96 == Development
  97
  98 Most of the work is done in Rainbows!, Zbatery is just a shim to
  99 allow access to Rainbows! without requiring fork() or signals.
 100
 101 You can get the latest source via git from the following locations:
 102
 103   git://bogomips.org/zbatery.git
 104   git://repo.or.cz/zbatery.git (mirror)
 105
 106 You may browse the code from the web and download the latest snapshot
 107 tarballs here:
 108
 109 * http://bogomips.org/zbatery.git (cgit)
 110 * http://repo.or.cz/w/zbatery.git (gitweb)
 111
 112 Inline patches (from "git format-patch") to the mailing list are
 113 preferred because they allow code review and comments in the reply to
 114 the patch.
 115
 116 We will adhere to mostly the same conventions for patch submissions as
 117 git itself.  See the Documentation/SubmittingPatches document
 118 distributed with git on on patch submission guidelines to follow.  Just
 119 don't email the git mailing list or maintainer with Zbatery patches.
 120
 121 == Tests
 122
 123 There currently are no tests specific to Zbatery.  Keep in mind that
 124 Zbatery is only a small shim to drive Rainbows! (and Unicorn)
 125 underneath.  Rainbows! and Unicorn both have extensive (but very
 126 UNIX-specific) test suites.
 127
 128 == Contact
 129
 130 All feedback (bug reports, user/development discussion, patches, pull
 131 requests) go to the mailing list/newsgroup.  We are currently
 132 borrowing the Rainbows! mailing list since most of our code (and
 133 problems) are related to Rainbows! mailto:rainbows-talk@rubyforge.org.