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 If you're on GNU/Linux and overwhelmed by options in zbatery,
  12 consider {yahns}[http://yahns.yhbt.net/] as it has fewer options,
  13 optional fork usage, and more energy-efficient during non-peak traffic.
  14
  15 Zbatery will still exploit certain features of Unix for transparent
  16 upgrades, log reopening, and graceful stops, but does not rely on them
  17 for basic functionality.
  18
  19 == Features
  20
  21 * Designed for {Rack}[http://rack.github.io/], the standard for
  22   modern Ruby HTTP applications.
  23
  24 * Configuration files are compatible with Rainbows!, a superset
  25   of the Unicorn
  26   {DSL}[http://unicorn.bogomips.org/Unicorn/Configurator.html].
  27
  28 * Inherits all features and concurrency models Rainbows! supports
  29   (and ever will support): http://rainbows.bogomips.org/Summary.html
  30
  31 * Web Sockets support (via {Cramp}[http://cramp.in/])
  32
  33 == License
  34
  35 \Zbatery is copyright 2009,2010,2011 by all contributors (see logs in git).
  36 \Zbatery is licensed under the Ruby (1.8) license or the GPL (v2 or v3).
  37 See the included {LICENSE}[link:LICENSE.html] file for more details.
  38
  39 \Zbatery is 100% Free Software.
  40
  41 == Install
  42
  43 You may install it via RubyGems on RubyGems.org:
  44
  45   gem install zbatery
  46
  47 Zbatery depends on Rainbows!, and in turn, Unicorn.  Despite Unicorn and
  48 Rainbows! being Unix-only, the Unicorn HTTP parser C extension should
  49 build on non-Unix-like systems (unverified).
  50
  51 == Usage
  52
  53 === for Rack applications
  54
  55 In APP_ROOT (where config.ru is located), run:
  56
  57   zbatery
  58
  59 Zbatery will bind to all interfaces on TCP port 8080 by default.
  60
  61 === Configuration File(s)
  62
  63 Zbatery will look for the config.ru file used by rackup in APP_ROOT.
  64
  65 For deployments, it can use a config file for Unicorn and
  66 Rainbows!-specific options specified by the +--config-file/-c+
  67 command-line switch.  Zbatery accepts all options found in
  68 {Unicorn::Configurator}[http://unicorn.bogomips.org/Unicorn/Configurator.html]
  69 as well as the "Rainbows!" block, so you can have the following in your
  70 config file:
  71
  72     Rainbows! do
  73       use :ThreadSpawn
  74       worker_connections 666
  75     end
  76
  77 See the Rainbows! configuration
  78 {documentation}[http://rainbows.bogomips.org/Rainbows/Configurator.html]
  79 for more details.
  80
  81 == Disclaimer
  82
  83 There is NO WARRANTY whatsoever if anything goes wrong, but let us know
  84 and we'll try our best to fix it.
  85
  86 == Development
  87
  88 Most of the work is done in Rainbows!, Zbatery is just a shim to
  89 allow access to Rainbows! without requiring fork() or signals.
  90
  91 You can get the latest source via git from the following locations:
  92
  93   git://bogomips.org/zbatery.git
  94   git://repo.or.cz/zbatery.git (mirror)
  95
  96 You may browse the code from the web and download the latest snapshot
  97 tarballs here:
  98
  99 * http://bogomips.org/zbatery.git (cgit)
 100 * http://repo.or.cz/w/zbatery.git (gitweb)
 101
 102 Inline patches (from "git format-patch") to the mailing list are
 103 preferred because they allow code review and comments in the reply to
 104 the patch.
 105
 106 We will adhere to mostly the same conventions for patch submissions as
 107 git itself.  See the Documentation/SubmittingPatches document
 108 distributed with git on on patch submission guidelines to follow.  Just
 109 don't email the git mailing list or maintainer with Zbatery patches.
 110
 111 == Tests
 112
 113 There currently are no tests specific to Zbatery.  Keep in mind that
 114 Zbatery is only a small shim to drive Rainbows! (and Unicorn)
 115 underneath.  Rainbows! and Unicorn both have extensive (but very
 116 UNIX-specific) test suites.
 117
 118 == Contact
 119
 120 All feedback (bug reports, user/development discussion, patches, pull
 121 requests) go to the mailing list/public-inbox.  We are currently
 122 borrowing the Rainbows! mailing list since most of our code (and
 123 problems) are related to Rainbows! mailto:rainbows-public@bogomips.org.