doc: switch bogomips.org to yhbt.net
[rainbows.git] / README
blob5fc3a311e4b21f8b01aa44f6a26b85884a751477
1 = Rainbows! - Rack app server for sleepy apps and slow clients
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.
7 If you're on GNU/Linux and overwhelmed by options in \Rainbows!,
8 consider {yahns}[https://yhbt.net/yahns/] 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.
12 For Rack applications not heavily bound by slow external network
13 dependencies, consider unicorn instead as it simpler and easier to
14 debug.
16 == \Rainbows! is about Diversity
18 We aim to support as many concurrency models as we can because they all
19 suck; differently.
21 For network concurrency, models we currently support are:
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]
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.
45 We also provide Rainbows::AppPool Rack middleware for some network
46 concurrency models for limiting application concurrency independently of
47 network concurrency.
49 == Features
51 * Designed for {Rack}[http://rack.github.io/], the standard for
52   modern Ruby HTTP applications.
54 * Built on {unicorn}[https://yhbt.net/unicorn/], inheriting its
55   process/socket management features such as transparent upgrades and
56   Ruby configuration DSL.
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.
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.
68 * We give you {lots of options}[link:Summary.html] with more
69   {on the way}[link:TODO.html].
71 == Applications
73 \Rainbows! is mainly designed for the odd things Unicorn sucks at:
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
85 \Rainbows! can also be used to service slow clients directly even with
86 fast applications.
88 == License
90 \Rainbows! is copyright 2009,2010 by all contributors (see logs in git).
91 \Rainbows! is licensed under the Ruby (1.8) license or the GPLv2 or later.
92 See the included {LICENSE}[link:LICENSE.html] file for more details.
94 \Rainbows! is 100% Free Software.
96 == Install
98 You may install it via RubyGems on RubyGems.org:
100   gem install rainbows
102 == Usage
104 === for Rack applications
106 In APP_ROOT (where config.ru is located), run:
108   rainbows
110 \Rainbows! will bind to all interfaces on TCP port 8080 by default.
112 === Configuration File(s)
114 \Rainbows! will look for the config.ru file used by rackup in APP_ROOT.
116 For deployments, it can use a config file for Unicorn and
117 \Rainbows!-specific options specified by the +--config-file/-c+
118 command-line switch.  \Rainbows! accepts all options found in
119 {Unicorn::Configurator}[https://yhbt.net/unicorn/Unicorn/Configurator.html]
120 as well as the "\Rainbows!" block, so you can have the following in your
121 config file:
123     worker_processes 4 # assuming four CPU cores
124     Rainbows! do
125       use :ThreadSpawn
126       worker_connections 100
127     end
129 See the {Rainbows! configuration}[link:Rainbows/Configurator.html]
130 {documentation}[link:Rainbows/Configurator.html]
131 for more details.
133 == Development
135 You can get the latest source via git from the following locations
136 (these versions may not be stable):
138   https://yhbt.net/rainbows.git
139   https://repo.or.cz/rainbows.git (mirror)
141 You may browse the code from the web and download the latest snapshot
142 tarballs here:
144 * https://yhbt.net/rainbows.git
145 * https://repo.or.cz/rainbows.git (gitweb)
147 Inline patches (from "git format-patch") to the mailing list are
148 preferred because they allow code review and comments in the reply to
149 the patch.
151 We will adhere to mostly the same conventions for patch submissions as
152 git itself.  See the
153 https://80x24.org/mirrors/git.git/tree/Documentation/SubmittingPatches?h=v2.20.1
154 document distributed with git on on patch submission guidelines to follow.
155 Just don't email the git mailing list or maintainer with \Rainbows! patches.
157 == Disclaimer
159 There is NO WARRANTY whatsoever if anything goes wrong, but let us know
160 and we'll try our best to fix it.
162 Rainbows! is extremely sensitive to fatal bugs in the apps it hosts.
163 Each Rainbows! worker process may be handling thousands of clients;
164 unexpectedly killing the process will abort _all_ of those
165 connections.  Lives may be lost!
167 Rainbows! hackers are not responsible for your application/library bugs.
168 Use an application server which is tolerant of buggy applications
169 if you cannot be bothered to fix all your fatal bugs.
171 == Contact
173 All feedback (bug reports, user/development discussion, patches, pull
174 requests) go to the mailing list.  Patches must be sent inline
175 (git format-patch -M + git send-email).  No subscription is necessary
176 to post on the mailing list.  No top posting.
178 * email: mailto:rainbows-public@yhbt.net
179 * subscribe: mailto:rainbows-public+subscribe@yhbt.net
180 * archives: https://yhbt.net/rainbows-public/
181   http://ou63pmih66umazou.onion/rainbows-public/
182   nntp://news.public-inbox.org/inbox.comp.lang.ruby.rainbows
183   nntp://ou63pmih66umazou.onion/inbox.comp.lang.ruby.rainbows
184   nntp://news.gmane.io/gmane.comp.lang.ruby.rainbows.general