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 by all contributors (see logs in git).
  38 It is ultimately based on Mongrel and carries the same license.
  39
  40 Mongrel is copyright 2007 Zed A. Shaw and contributors. It is licensed
  41 under the Ruby license and the GPL2. See the included LICENSE file for
  42 details.
  43
  44 Zbatery is 100% Free Software.
  45
  46 == Install
  47
  48 You may download the tarball from the Rainbows project page on Rubyforge
  49 and run setup.rb after unpacking it (and installing Unicorn and Rainbows!):
  50
  51 http://rubyforge.org/frs/?group_id=8977
  52
  53 You may also install it via RubyGems on Gemcutter:
  54
  55   gem install zbatery
  56
  57 Zbatery depends on Rainbows!, and in turn, Unicorn.  Despite Unicorn and
  58 Rainbows! being Unix-only, the Unicorn HTTP parser C extension should
  59 build on non-Unix-like systems (unverified).
  60
  61 == Usage
  62
  63 === for Rack applications
  64
  65 In APP_ROOT (where config.ru is located), run:
  66
  67   zbatery
  68
  69 Zbatery will bind to all interfaces on TCP port 8080 by default.
  70
  71 === Configuration File(s)
  72
  73 Zbatery will look for the config.ru file used by rackup in APP_ROOT.
  74
  75 For deployments, it can use a config file for Unicorn and
  76 Rainbows!-specific options specified by the +--config-file/-c+
  77 command-line switch.  Zbatery accepts all options found in
  78 {Unicorn::Configurator}[http://unicorn.bogomips.org/Unicorn/Configurator.html]
  79 as well as the "Rainbows!" block, so you can have the following in your
  80 config file:
  81
  82     Rainbows! do
  83       use :FiberSpawn
  84       worker_connections 400
  85     end
  86
  87 See the Rainbows! configuration
  88 {documentation}[http://rainbows.rubyforge.org/Rainbows.html#M000001]
  89 for more details.
  90
  91 == Disclaimer
  92
  93 There is NO WARRANTY whatsoever if anything goes wrong, but let us know
  94 and we'll try our best to fix it.
  95
  96 This project may be temporary and may eventually have its name encoded
  97 with uncrackable ROT13 encryption leaving you with no way to upgrade.
  98
  99 == Development
 100
 101 Most of the work is done in Rainbows!, Zbatery is just a shim to
 102 allow access to Rainbows! without requiring fork() or signals.
 103
 104 You can get the latest source via git from the following locations:
 105
 106   git://git.bogomips.org/zbatery.git
 107   git://repo.or.cz/zbatery.git (mirror)
 108
 109 You may browse the code from the web and download the latest snapshot
 110 tarballs here:
 111
 112 * http://git.bogomips.org/cgit/zbatery.git (cgit)
 113 * http://repo.or.cz/w/zbatery.git (gitweb)
 114
 115 Inline patches (from "git format-patch") to the mailing list are
 116 preferred because they allow code review and comments in the reply to
 117 the patch.
 118
 119 We will adhere to mostly the same conventions for patch submissions as
 120 git itself.  See the Documentation/SubmittingPatches document
 121 distributed with git on on patch submission guidelines to follow.  Just
 122 don't email the git mailing list or maintainer with Zbatery patches.
 123
 124 == Tests
 125
 126 There currently are no tests specific to Zbatery.  Keep in mind that
 127 Zbatery is only a small shim to drive Rainbows! (and Unicorn)
 128 underneath.  Rainbows! and Unicorn both have extensive (but very
 129 UNIX-specific) test suites.
 130
 131 == Contact
 132
 133 All feedback (bug reports, user/development discussion, patches, pull
 134 requests) go to the mailing list/newsgroup.  We are currently
 135 borrowing the Rainbows! mailing list since most of our code (and
 136 problems) are related to Rainbows! mailto:rainbows-talk@rubyforge.org.