README

   1 = Rainbows! - unicorn for sleepy apps and slow clients
   2
   3 \Rainbows! is an HTTP server for sleepy Rack applications.  It is based on
   4 unicorn, but designed to handle applications that expect long
   5 request/response times and/or slow clients.
   6
   7 If you're on GNU/Linux and overwhelmed by options in \Rainbows!,
   8 consider {yahns}[http://yahns.yhbt.net/] as it has fewer options
   9 and more energy-efficient during non-peak traffic and may also
  10 be configured as a single worker process.
  11
  12 For Rack applications not heavily bound by slow external network
  13 dependencies, consider unicorn instead as it simpler and easier to
  14 debug.
  15
  16 == \Rainbows! is about Diversity
  17
  18 We aim to support as many concurrency models as we can because they all
  19 suck; differently.
  20
  21 For network concurrency, models we currently support are:
  22
  23 * {Coolio}[link:Rainbows/Coolio.html]
  24 * {CoolioFiberSpawn}[link:Rainbows/CoolioFiberSpawn.html]
  25 * {CoolioThreadPool}[link:Rainbows/CoolioThreadPool.html]
  26 * {CoolioThreadSpawn}[link:Rainbows/CoolioThreadSpawn.html]
  27 * {Epoll}[link:Rainbows/Epoll.html]
  28 * {EventMachine}[link:Rainbows/EventMachine.html]
  29 * {FiberPool}[link:Rainbows/FiberPool.html]
  30 * {FiberSpawn}[link:Rainbows/FiberSpawn.html]
  31 * {NeverBlock}[link:Rainbows/NeverBlock.html]
  32 * {Revactor}[link:Rainbows/Revactor.html]
  33 * {ThreadPool}[link:Rainbows/ThreadPool.html]
  34 * {ThreadSpawn}[link:Rainbows/ThreadSpawn.html]
  35 * {WriterThreadPool}[link:Rainbows/WriterThreadPool.html]
  36 * {WriterThreadSpawn}[link:Rainbows/WriterThreadSpawn.html]
  37 * {XEpoll}[link:Rainbows/XEpoll.html]
  38 * {XEpollThreadPool}[link:Rainbows/XEpollThreadPool.html]
  39 * {XEpollThreadSpawn}[link:Rainbows/XEpollThreadSpawn.html]
  40
  41 We have {many more on the way}[link:TODO.html] for handling network
  42 concurrency.  Additionally, we also use multiple processes (managed by
  43 Unicorn) for robustness and CPU/memory/disk concurrency.
  44
  45 We also provide Rainbows::AppPool Rack middleware for some network
  46 concurrency models for limiting application concurrency independently of
  47 network concurrency.
  48
  49 == Features
  50
  51 * Designed for {Rack}[http://rack.github.io/], the standard for
  52   modern Ruby HTTP applications.
  53
  54 * Built on {Unicorn}[http://unicorn.bogomips.org/], inheriting its
  55   process/socket management features such as transparent upgrades and
  56   Ruby configuration DSL.
  57
  58 * As with Unicorn, it is able to stream large request bodies off the
  59   socket to the application while the client is still uploading.  Since
  60   \Rainbows! can handle slow clients, this feature is more useful than
  61   it is with Unicorn.
  62
  63 * Combines heavyweight concurrency (worker processes) with lightweight
  64   concurrency (Events/Fibers/Actors/Threads), allowing CPU/memory/disk to
  65   be scaled independently of client connections.  More concurrency models
  66   (listed in the TODO) will be supported as we find time for them.
  67
  68 * We give you {lots of options}[link:Summary.html] with more
  69   {on the way}[link:TODO.html].
  70
  71 == Applications
  72
  73 \Rainbows! is mainly designed for the odd things Unicorn sucks at:
  74
  75 * 3rd-party APIs (to services outside your control/LAN)
  76 * OpenID consumers (to providers outside your control/LAN)
  77 * Reverse proxy implementations with editing/censoring
  78   (to upstreams outside your control/LAN)
  79 * Comet
  80 * BOSH (with slow clients)
  81 * HTTP server push
  82 * Long polling
  83 * Reverse AJAX
  84 * real-time upload processing (via {upr}[http://upr.bogomips.org/])
  85
  86 \Rainbows! can also be used to service slow clients directly even with
  87 fast applications.
  88
  89 == License
  90
  91 \Rainbows! is copyright 2009,2010 by all contributors (see logs in git).
  92 \Rainbows! is licensed under the Ruby (1.8) license or the GPLv2 or later.
  93 See the included {LICENSE}[link:LICENSE.html] file for more details.
  94
  95 \Rainbows! is 100% Free Software.
  96
  97 == Install
  98
  99 You may install it via RubyGems on RubyGems.org:
 100
 101   gem install rainbows
 102
 103 == Usage
 104
 105 === for Rack applications
 106
 107 In APP_ROOT (where config.ru is located), run:
 108
 109   rainbows
 110
 111 \Rainbows! will bind to all interfaces on TCP port 8080 by default.
 112
 113 === Configuration File(s)
 114
 115 \Rainbows! will look for the config.ru file used by rackup in APP_ROOT.
 116
 117 For deployments, it can use a config file for Unicorn and
 118 \Rainbows!-specific options specified by the +--config-file/-c+
 119 command-line switch.  \Rainbows! accepts all options found in
 120 {Unicorn::Configurator}[http://unicorn.bogomips.org/Unicorn/Configurator.html]
 121 as well as the "\Rainbows!" block, so you can have the following in your
 122 config file:
 123
 124     worker_processes 4 # assuming four CPU cores
 125     Rainbows! do
 126       use :FiberSpawn
 127       worker_connections 100
 128     end
 129
 130 See the {Rainbows! configuration}[link:Rainbows/Configurator.html]
 131 {documentation}[link:Rainbows/Configurator.html]
 132 for more details.
 133
 134 == Development
 135
 136 You can get the latest source via git from the following locations
 137 (these versions may not be stable):
 138
 139   git://bogomips.org/rainbows.git
 140   git://repo.or.cz/rainbows.git (mirror)
 141
 142 You may browse the code from the web and download the latest snapshot
 143 tarballs here:
 144
 145 * http://bogomips.org/rainbows.git (cgit)
 146 * http://repo.or.cz/w/rainbows.git (gitweb)
 147
 148 Inline patches (from "git format-patch") to the mailing list are
 149 preferred because they allow code review and comments in the reply to
 150 the patch.
 151
 152 We will adhere to mostly the same conventions for patch submissions as
 153 git itself.  See the Documentation/SubmittingPatches document
 154 distributed with git on on patch submission guidelines to follow.  Just
 155 don't email the git mailing list or maintainer with \Rainbows! patches.
 156
 157 == Disclaimer
 158
 159 There is NO WARRANTY whatsoever if anything goes wrong, but let us know
 160 and we'll try our best to fix it.
 161
 162 == Contact
 163
 164 All feedback (bug reports, user/development discussion, patches, pull
 165 requests) go to the mailing list.  Patches must be sent inline
 166 (git format-patch -M + git send-email).  No subscription is necessary
 167 to post on the mailing list.  No top posting.  Address replies +To:+
 168 the mailing list.
 169
 170 * email: mailto:rainbows-public@bogomips.org
 171 * subscribe: mailto:rainbows-public+subscribe@bogomips.org
 172 * archives: http://bogomips.org/rainbows-public/