Skip to content
Newer
Older
100644 305 lines (220 sloc) 9.76 KB
2bc59be @espadrine Readme: Use an SVG badge.
espadrine authored
1 = Rack, a modular Ruby webserver interface {<img src="https://secure.travis-ci.org/rack/rack.svg" alt="Build Status" />}[http://travis-ci.org/rack/rack] {<img src="https://gemnasium.com/rack/rack.svg" alt="Dependency Status" />}[https://gemnasium.com/rack/rack]
d773b8b @chneukirchen Add README and other documentation
chneukirchen authored
2
e51b1af @snuggs Place comma before and
snuggs authored
3 Rack provides a minimal, modular, and adaptable interface for developing
d773b8b @chneukirchen Add README and other documentation
chneukirchen authored
4 web applications in Ruby. By wrapping HTTP requests and responses in
5 the simplest way possible, it unifies and distills the API for web
9bcca54 @chneukirchen Small README fixes
chneukirchen authored
6 servers, web frameworks, and software in between (the so-called
d773b8b @chneukirchen Add README and other documentation
chneukirchen authored
7 middleware) into a single method call.
8
9 The exact details of this are described in the Rack specification,
10 which all Rack applications should conform to.
11
12 == Supported web servers
13
14 The included *handlers* connect all kinds of web servers to Rack:
15 * WEBrick
16 * FCGI
17 * CGI
dcb6081 @chneukirchen Update README and docs
chneukirchen authored
18 * SCGI
19 * LiteSpeed
1266337 @chneukirchen Update README
chneukirchen authored
20 * Thin
dcb6081 @chneukirchen Update README and docs
chneukirchen authored
21
22 These web servers include Rack handlers in their distributions:
23 * Ebb
24 * Fuzed
7901d91 @chneukirchen Update web server list in README
chneukirchen authored
25 * Glassfish v3
7637dab @chneukirchen Update README
chneukirchen authored
26 * Phusion Passenger (which is mod_rack for Apache and for nginx)
3a04d82 @jc00ke Adding Puma to list of web servers
jc00ke authored
27 * Puma
c964469 Update README.rdoc
slivu authored
28 * Reel
c145b9a @tenderlove Revert "Add handlers for Unicorn, Rainbows! and Zbatery"
tenderlove authored
29 * Unicorn
9a6a791 @drudru Update README.doc to include unixrack web server
drudru authored
30 * unixrack
a329828 @unbit added uWSGI to the list of servers supporting Rack
unbit authored
31 * uWSGI
c25dede README: update to add yahns to the list of servers
Eric Wong authored
32 * yahns
d773b8b @chneukirchen Add README and other documentation
chneukirchen authored
33
34 Any valid Rack app will run the same on all these handlers, without
35 changing anything.
36
37 == Supported web frameworks
38
39 These frameworks include Rack adapters in their distributions:
7637dab @chneukirchen Update README
chneukirchen authored
40 * Camping
dcb6081 @chneukirchen Update README and docs
chneukirchen authored
41 * Coset
c964469 Update README.rdoc
slivu authored
42 * Espresso
dcb6081 @chneukirchen Update README and docs
chneukirchen authored
43 * Halcyon
eed24a7 @chneukirchen Update README
chneukirchen authored
44 * Mack
d773b8b @chneukirchen Add README and other documentation
chneukirchen authored
45 * Maveric
dcb6081 @chneukirchen Update README and docs
chneukirchen authored
46 * Merb
d773b8b @chneukirchen Add README and other documentation
chneukirchen authored
47 * Racktools::SimpleApplication
dcb6081 @chneukirchen Update README and docs
chneukirchen authored
48 * Ramaze
1266337 @chneukirchen Update README
chneukirchen authored
49 * Ruby on Rails
7637dab @chneukirchen Update README
chneukirchen authored
50 * Rum
dcb6081 @chneukirchen Update README and docs
chneukirchen authored
51 * Sinatra
1266337 @chneukirchen Update README
chneukirchen authored
52 * Sin
dcb6081 @chneukirchen Update README and docs
chneukirchen authored
53 * Vintage
e9f9f27 @chneukirchen Improve test documentation
chneukirchen authored
54 * Waves
7637dab @chneukirchen Update README
chneukirchen authored
55 * Wee
4e95fe1 @chneukirchen Update README
chneukirchen authored
56 * ... and many others.
dcb6081 @chneukirchen Update README and docs
chneukirchen authored
57
d773b8b @chneukirchen Add README and other documentation
chneukirchen authored
58 == Available middleware
59
60 Between the server and the framework, Rack can be customized to your
61 applications needs using middleware, for example:
62 * Rack::URLMap, to route to multiple applications inside the same process.
253cb49 @chneukirchen Last-minute details
chneukirchen authored
63 * Rack::CommonLogger, for creating Apache-style logfiles.
d773b8b @chneukirchen Add README and other documentation
chneukirchen authored
64 * Rack::ShowException, for catching unhandled exceptions and
253cb49 @chneukirchen Last-minute details
chneukirchen authored
65 presenting them in a nice and helpful way with clickable backtrace.
d773b8b @chneukirchen Add README and other documentation
chneukirchen authored
66 * Rack::File, for serving static files.
dcb6081 @chneukirchen Update README and docs
chneukirchen authored
67 * ...many others!
d773b8b @chneukirchen Add README and other documentation
chneukirchen authored
68
69 All these components use the same interface, which is described in
eed24a7 @chneukirchen Update README
chneukirchen authored
70 detail in the Rack specification. These optional components can be
71 used in any way you wish.
d773b8b @chneukirchen Add README and other documentation
chneukirchen authored
72
73 == Convenience
74
75 If you want to develop outside of existing frameworks, implement your
76 own ones, or develop middleware, Rack provides many helpers to create
77 Rack applications quickly and without doing the same web stuff all
78 over:
79 * Rack::Request, which also provides query string parsing and
80 multipart handling.
81 * Rack::Response, for convenient generation of HTTP replies and
82 cookie handling.
83 * Rack::MockRequest and Rack::MockResponse for efficient and quick
9bcca54 @chneukirchen Small README fixes
chneukirchen authored
84 testing of Rack application without real HTTP round-trips.
d773b8b @chneukirchen Add README and other documentation
chneukirchen authored
85
0b601c5 @chneukirchen Update README
chneukirchen authored
86 == rack-contrib
87
88 The plethora of useful middleware created the need for a project that
89 collects fresh Rack middleware. rack-contrib includes a variety of
3568c0d @chneukirchen Last minute README fixes
chneukirchen authored
90 add-on components for Rack and it is easy to contribute new modules.
0b601c5 @chneukirchen Update README
chneukirchen authored
91
7833d05 @dblock Moved HISTORY into a separate document.
dblock authored
92 * https://github.com/rack/rack-contrib
0b601c5 @chneukirchen Update README
chneukirchen authored
93
d773b8b @chneukirchen Add README and other documentation
chneukirchen authored
94 == rackup
95
96 rackup is a useful tool for running Rack applications, which uses the
97 Rack::Builder DSL to configure middleware and build up applications
98 easily.
99
100 rackup automatically figures out the environment it is run in, and
2577f0b @deepj Remove legacy Mongrel server
deepj authored
101 runs your application as FastCGI, CGI, or WEBrick---all from the
102 same configuration.
d773b8b @chneukirchen Add README and other documentation
chneukirchen authored
103
104 == Quick start
105
106 Try the lobster!
107
108 Either with the embedded WEBrick starter:
109
e256ec6 @chneukirchen Update README
chneukirchen authored
110 ruby -Ilib lib/rack/lobster.rb
d773b8b @chneukirchen Add README and other documentation
chneukirchen authored
111
112 Or with rackup:
113
d4906ef @josh Tell people to report bugs to lighthouse
josh authored
114 bin/rackup -Ilib example/lobster.ru
d773b8b @chneukirchen Add README and other documentation
chneukirchen authored
115
116 By default, the lobster is found at http://localhost:9292.
117
118 == Installing with RubyGems
119
b6e61e3 @raggi Update links and correct a spelling error
raggi authored
120 A Gem of Rack is available at rubygems.org. You can install it with:
d773b8b @chneukirchen Add README and other documentation
chneukirchen authored
121
122 gem install rack
123
124 I also provide a local mirror of the gems (and development snapshots)
125 at my site:
126
d894ded @chneukirchen Add trailing slash to the alternative gem server
chneukirchen authored
127 gem install rack --source http://chneukirchen.org/releases/gems/
d773b8b @chneukirchen Add README and other documentation
chneukirchen authored
128
540dc3f @chneukirchen Changes to get lighttpd setup and running when rake fulltest is run; …
chneukirchen authored
129 == Running the tests
130
7e5d611 @chneukirchen Last README updates
chneukirchen authored
131 Testing Rack requires the bacon testing framework:
540dc3f @chneukirchen Changes to get lighttpd setup and running when rake fulltest is run; …
chneukirchen authored
132
3ef25b9 @alup Update README
alup authored
133 bundle install --without extra # to be able to run the fast tests
134
135 Or:
136
137 bundle install # this assumes that you have installed native extensions!
540dc3f @chneukirchen Changes to get lighttpd setup and running when rake fulltest is run; …
chneukirchen authored
138
f6ac962 @keepcosmos remove fulltest guide on README
keepcosmos authored
139 There is a rake-based test task:
e9f9f27 @chneukirchen Improve test documentation
chneukirchen authored
140
f6ac962 @keepcosmos remove fulltest guide on README
keepcosmos authored
141 rake test tests all the tests
e9f9f27 @chneukirchen Improve test documentation
chneukirchen authored
142
f6ac962 @keepcosmos remove fulltest guide on README
keepcosmos authored
143 The testsuite has no dependencies outside of the core Ruby
7e5d611 @chneukirchen Last README updates
chneukirchen authored
144 installation and bacon.
e9f9f27 @chneukirchen Improve test documentation
chneukirchen authored
145
eed24a7 @chneukirchen Update README
chneukirchen authored
146 To run the test suite completely, you need:
e9f9f27 @chneukirchen Improve test documentation
chneukirchen authored
147
148 * fcgi
149 * memcache-client
7637dab @chneukirchen Update README
chneukirchen authored
150 * thin
e9f9f27 @chneukirchen Improve test documentation
chneukirchen authored
151
152 The full set of tests test FCGI access with lighttpd (on port
153 9203) so you will need lighttpd installed as well as the FCGI
154 libraries and the fcgi gem:
540dc3f @chneukirchen Changes to get lighttpd setup and running when rake fulltest is run; …
chneukirchen authored
155
156 Download and install lighttpd:
157
158 http://www.lighttpd.net/download
159
160 Installing the FCGI libraries:
161
162 curl -O http://www.fastcgi.com/dist/fcgi-2.4.0.tar.gz
163 tar xzvf fcgi-2.4.0.tar.gz
164 cd fcgi-2.4.0
165 ./configure --prefix=/usr/local
166 make
167 sudo make install
168 cd ..
169
170 Installing the Ruby fcgi gem:
171
172 gem install fcgi
173
e9f9f27 @chneukirchen Improve test documentation
chneukirchen authored
174 Furthermore, to test Memcache sessions, you need memcached (will be
175 run on port 11211) and memcache-client installed.
540dc3f @chneukirchen Changes to get lighttpd setup and running when rake fulltest is run; …
chneukirchen authored
176
f86c885 @byroot Document the multipart_part_limit configuration in the README
byroot authored
177 == Configuration
178
57f7b9c @JonMidhir Remove Markdown backticks for inline code in Readme
JonMidhir authored
179 Several parameters can be modified on Rack::Utils to configure Rack behaviour.
f86c885 @byroot Document the multipart_part_limit configuration in the README
byroot authored
180
181 e.g:
182
81b9f1f @JonMidhir Remove markdown from RDoc readme
JonMidhir authored
183 Rack::Utils.key_space_limit = 128
f86c885 @byroot Document the multipart_part_limit configuration in the README
byroot authored
184
185 === key_space_limit
186
187 The default number of bytes to allow a single parameter key to take up.
188 This helps prevent a rogue client from flooding a Request.
189
190 Default to 65536 characters (4 kiB in worst case).
191
192 === multipart_part_limit
193
194 The maximum number of parts a request can contain.
195 Accepting too many part can lead to the server running out of file handles.
196
57f7b9c @JonMidhir Remove Markdown backticks for inline code in Readme
JonMidhir authored
197 The default is 128, which means that a single request can't upload more than 128 files at once.
f86c885 @byroot Document the multipart_part_limit configuration in the README
byroot authored
198
57f7b9c @JonMidhir Remove Markdown backticks for inline code in Readme
JonMidhir authored
199 Set to 0 for no limit.
f86c885 @byroot Document the multipart_part_limit configuration in the README
byroot authored
200
57f7b9c @JonMidhir Remove Markdown backticks for inline code in Readme
JonMidhir authored
201 Can also be set via the RACK_MULTIPART_PART_LIMIT environment variable.
f86c885 @byroot Document the multipart_part_limit configuration in the README
byroot authored
202
d773b8b @chneukirchen Add README and other documentation
chneukirchen authored
203 == History
204
9303790 Fix history link
Maksim Sitnikov authored
205 See <https://github.com/rack/rack/blob/master/HISTORY.md>.
a5cc74b @raggi Add release notes for todays releases
raggi authored
206
d773b8b @chneukirchen Add README and other documentation
chneukirchen authored
207 == Contact
208
d4906ef @josh Tell people to report bugs to lighthouse
josh authored
209 Please post bugs, suggestions and patches to
7833d05 @dblock Moved HISTORY into a separate document.
dblock authored
210 the bug tracker at <https://github.com/rack/rack/issues>.
eed24a7 @chneukirchen Update README
chneukirchen authored
211
0ea18dd @raggi Update README for release. Add security section.
raggi authored
212 Please post security related bugs and suggestions to the core team at
771795d @raggi Update README security notes
raggi authored
213 <https://groups.google.com/group/rack-core> or rack-core@googlegroups.com. This
214 list is not public. Due to wide usage of the library, it is strongly preferred
215 that we manage timing in order to provide viable patches at the time of
216 disclosure. Your assistance in this matter is greatly appreciated.
0ea18dd @raggi Update README for release. Add security section.
raggi authored
217
eed24a7 @chneukirchen Update README
chneukirchen authored
218 Mailing list archives are available at
7833d05 @dblock Moved HISTORY into a separate document.
dblock authored
219 <https://groups.google.com/group/rack-devel>.
d773b8b @chneukirchen Add README and other documentation
chneukirchen authored
220
7637dab @chneukirchen Update README
chneukirchen authored
221 Git repository (send Git patches to the mailing list):
7833d05 @dblock Moved HISTORY into a separate document.
dblock authored
222 * https://github.com/rack/rack
4bfb6fc @chneukirchen Update README and gemspec
chneukirchen authored
223 * http://git.vuxu.org/cgi-bin/gitweb.cgi?p=rack-github.git
d773b8b @chneukirchen Add README and other documentation
chneukirchen authored
224
253cb49 @chneukirchen Last-minute details
chneukirchen authored
225 You are also welcome to join the #rack channel on irc.freenode.net.
d773b8b @chneukirchen Add README and other documentation
chneukirchen authored
226
7fed4c7 @chneukirchen Update thanks
chneukirchen authored
227 == Thanks
d773b8b @chneukirchen Add README and other documentation
chneukirchen authored
228
0b601c5 @chneukirchen Update README
chneukirchen authored
229 The Rack Core Team, consisting of
230
877d7a8 @davydovanton Added links to profile page for all rack team members
davydovanton authored
231 * Christian Neukirchen (chneukirchen[https://github.com/chneukirchen])
232 * James Tucker (raggi[https://github.com/raggi])
233 * Josh Peek (josh[https://github.com/josh])
234 * José Valim (josevalim[https://github.com/josevalim])
235 * Michael Fellinger (manveru[https://github.com/manveru])
236 * Aaron Patterson (tenderlove[https://github.com/tenderlove])
237 * Santiago Pastorino (spastorino[https://github.com/spastorino])
238 * Konstantin Haase (rkh[https://github.com/rkh])
0b601c5 @chneukirchen Update README
chneukirchen authored
239
155461c @rkh update team list
rkh authored
240 and the Rack Alumnis
241
877d7a8 @davydovanton Added links to profile page for all rack team members
davydovanton authored
242 * Ryan Tomayko (rtomayko[https://github.com/rtomayko])
243 * Scytrin dai Kinthra (scytrin[https://github.com/scytrin])
155461c @rkh update team list
rkh authored
244
0b601c5 @chneukirchen Update README
chneukirchen authored
245 would like to thank:
246
cdab8c7 @chneukirchen Add LiteSpeed handler
chneukirchen authored
247 * Adrian Madrid, for the LiteSpeed handler.
eed24a7 @chneukirchen Update README
chneukirchen authored
248 * Christoffer Sawicki, for the first Rails adapter and Rack::Deflater.
e5fa2f9 @chneukirchen Integrate patches
chneukirchen authored
249 * Tim Fletcher, for the HTTP authentication code.
6908a8f @chneukirchen Update AUTHORS and thanks
chneukirchen authored
250 * Luc Heinrich for the Cookie sessions, the static file handler and bugfixes.
d773b8b @chneukirchen Add README and other documentation
chneukirchen authored
251 * Armin Ronacher, for the logo and racktools.
4bfb6fc @chneukirchen Update README and gemspec
chneukirchen authored
252 * Alex Beregszaszi, Alexander Kahn, Anil Wadghule, Aredridel, Ben
253 Alpert, Dan Kubb, Daniel Roethlisberger, Matt Todd, Tom Robinson,
254 Phil Hagelberg, S. Brent Faulkner, Bosko Milekic, Daniel Rodríguez
255 Troitiño, Genki Takiuchi, Geoffrey Grosenbach, Julien Sanchez, Kamal
256 Fariz Mahyuddin, Masayoshi Takahashi, Patrick Aljordm, Mig, Kazuhiro
257 Nishiyama, Jon Bardin, Konstantin Haase, Larry Siden, Matias
258 Korhonen, Sam Ruby, Simon Chiang, Tim Connor, Timur Batyrshin, and
259 Zach Brock for bug fixing and other improvements.
4e95fe1 @chneukirchen Update README
chneukirchen authored
260 * Eric Wong, Hongli Lai, Jeremy Kemper for their continuous support
261 and API improvements.
262 * Yehuda Katz and Carl Lerche for refactoring rackup.
7637dab @chneukirchen Update README
chneukirchen authored
263 * Brian Candler, for Rack::ContentType.
264 * Graham Batty, for improved handler loading.
e327c85 @chneukirchen Update History
chneukirchen authored
265 * Stephen Bannasch, for bug reports and documentation.
e256ec6 @chneukirchen Update README
chneukirchen authored
266 * Gary Wright, for proposing a better Rack::Response interface.
e06975b @chneukirchen Make Rack::Response possibly close the body
chneukirchen authored
267 * Jonathan Buch, for improvements regarding Rack::Response.
6908a8f @chneukirchen Update AUTHORS and thanks
chneukirchen authored
268 * Armin Röhrl, for tracking down bugs in the Cookie generator.
3568c0d @chneukirchen Last minute README fixes
chneukirchen authored
269 * Alexander Kellett for testing the Gem and reviewing the announcement.
d773b8b @chneukirchen Add README and other documentation
chneukirchen authored
270 * Marcus Rückert, for help with configuring and debugging lighttpd.
271 * The WSGI team for the well-done and documented work they've done and
272 Rack builds up on.
b6e61e3 @raggi Update links and correct a spelling error
raggi authored
273 * All bug reporters and patch contributors not mentioned above.
d773b8b @chneukirchen Add README and other documentation
chneukirchen authored
274
275 == Copyright
276
73a6b50 @chneukirchen Update copyright messages
chneukirchen authored
277 Copyright (C) 2007, 2008, 2009, 2010 Christian Neukirchen <http://purl.org/net/chneukirchen>
d773b8b @chneukirchen Add README and other documentation
chneukirchen authored
278
279 Permission is hereby granted, free of charge, to any person obtaining a copy
280 of this software and associated documentation files (the "Software"), to
281 deal in the Software without restriction, including without limitation the
282 rights to use, copy, modify, merge, publish, distribute, sublicense, and/or
283 sell copies of the Software, and to permit persons to whom the Software is
284 furnished to do so, subject to the following conditions:
285
286 The above copyright notice and this permission notice shall be included in
287 all copies or substantial portions of the Software.
288
289 THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
290 IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
291 FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL
d4906ef @josh Tell people to report bugs to lighthouse
josh authored
292 THE AUTHORS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER
d773b8b @chneukirchen Add README and other documentation
chneukirchen authored
293 IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN
294 CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
295
296 == Links
297
e64ea88 @tricknotes Modify GitHub pages domain
tricknotes authored
298 Rack:: <http://rack.github.io/>
7833d05 @dblock Moved HISTORY into a separate document.
dblock authored
299 Official Rack repositories:: <https://github.com/rack>
300 Rack Bug Tracking:: <https://github.com/rack/rack/issues>
301 rack-devel mailing list:: <https://groups.google.com/group/rack-devel>
b6e61e3 @raggi Update links and correct a spelling error
raggi authored
302 Rack's Rubyforge project:: <http://rubyforge.org/projects/rack>
d773b8b @chneukirchen Add README and other documentation
chneukirchen authored
303
304 Christian Neukirchen:: <http://chneukirchen.org/>
Something went wrong with that request. Please try again.