Skip to content

HTTPS clone URL

Subversion checkout URL

You can clone with HTTPS or Subversion.

Download ZIP
Newer
Older
100644 252 lines (143 sloc) 12.85 kb
43cb200 @evanphx Switch README to format hoe understands
evanphx authored
1 # Puma: A Ruby Web Server Built For Concurrency
1888887 @tarcieri Redo README in Markdown and replace Mongrel with Puma
tarcieri authored
2
e74a9f7 @brixen Add Gitter badge.
brixen authored
3 [![Gitter](https://badges.gitter.im/Join%20Chat.svg)](https://gitter.im/puma/puma?utm_source=badge&utm_medium=badge&utm_campaign=pr-badge) [![Build Status](https://secure.travis-ci.org/puma/puma.png)](http://travis-ci.org/puma/puma) [![Dependency Status](https://gemnasium.com/puma/puma.png)](https://gemnasium.com/puma/puma) <a href="https://codeclimate.com/github/puma/puma"><img src="https://codeclimate.com/github/puma/puma.png" /></a>
a4e2807 @laserlemon Add Travis build and Gemnasium dependency status images to the README
laserlemon authored
4
43cb200 @evanphx Switch README to format hoe understands
evanphx authored
5 ## Description
1888887 @tarcieri Redo README in Markdown and replace Mongrel with Puma
tarcieri authored
6
4b318e2 @catsby Update README for shorter gem description
catsby authored
7 Puma is a simple, fast, threaded, and highly concurrent HTTP 1.1 server for Ruby/Rack applications. Puma is intended for use in both development and production environments. In order to get the best throughput, it is highly recommended that you use a Ruby implementation with real threads like Rubinius or JRuby.
8
9 ## Built For Speed &amp; Concurrency
10
225b556 @kyledrake Update README file to provide more details
kyledrake authored
11 Puma is a simple, fast, and highly concurrent HTTP 1.1 server for Ruby web applications. It can be used with any application that supports Rack, and is considered the replacement for Webrick and Mongrel. It was designed to be the go-to server for [Rubinius](http://rubini.us), but also works well with JRuby and MRI. Puma is intended for use in both development and production environments.
1888887 @tarcieri Redo README in Markdown and replace Mongrel with Puma
tarcieri authored
12
cc2ca8a @kyledrake Fix extension typo
kyledrake authored
13 Under the hood, Puma processes requests using a C-optimized Ragel extension (inherited from Mongrel) that provides fast, accurate HTTP 1.1 protocol parsing in a portable way. Puma then serves the request in a thread from an internal thread pool (which you can control). This allows Puma to provide real concurrency for your web application!
1888887 @tarcieri Redo README in Markdown and replace Mongrel with Puma
tarcieri authored
14
225b556 @kyledrake Update README file to provide more details
kyledrake authored
15 With Rubinius 2.0, Puma will utilize all cores on your CPU with real threads, meaning you won't have to spawn multiple processes to increase throughput. You can expect to see a similar benefit from JRuby.
1888887 @tarcieri Redo README in Markdown and replace Mongrel with Puma
tarcieri authored
16
bc0b3a5 @jc00ke Fix typo
jc00ke authored
17 On MRI, there is a Global Interpreter Lock (GIL) that ensures only one thread can be run at a time. But if you're doing a lot of blocking IO (such as HTTP calls to external APIs like Twitter), Puma still improves MRI's throughput by allowing blocking IO to be run concurrently (EventMachine-based servers such as Thin turn off this ability, requiring you to use special libraries). Your mileage may vary. In order to get the best throughput, it is highly recommended that you use a Ruby implementation with real threads like [Rubinius](http://rubini.us) or [JRuby](http://jruby.org).
1888887 @tarcieri Redo README in Markdown and replace Mongrel with Puma
tarcieri authored
18
43cb200 @evanphx Switch README to format hoe understands
evanphx authored
19 ## Quick Start
1888887 @tarcieri Redo README in Markdown and replace Mongrel with Puma
tarcieri authored
20
225b556 @kyledrake Update README file to provide more details
kyledrake authored
21 The easiest way to get started with Puma is to install it via RubyGems. You can do this easily:
1888887 @tarcieri Redo README in Markdown and replace Mongrel with Puma
tarcieri authored
22
06072d0 @tarcieri Indent examples at the level Markdown expects
tarcieri authored
23 $ gem install puma
1888887 @tarcieri Redo README in Markdown and replace Mongrel with Puma
tarcieri authored
24
58434d7 @catsby Clarify some platform specifics
catsby authored
25 Now you should have the `puma` command available in your PATH, so just do the following in the root folder of your Rack application:
1888887 @tarcieri Redo README in Markdown and replace Mongrel with Puma
tarcieri authored
26
4f69300 @evanphx Prune the README.md
evanphx authored
27 $ puma app.ru
1888887 @tarcieri Redo README in Markdown and replace Mongrel with Puma
tarcieri authored
28
7a9a8e2 @rkh Add documentation for Rails/Sinatra/Rack usage
rkh authored
29 ## Advanced Setup
30
31 ### Sinatra
32
33 You can run your Sinatra application with Puma from the command line like this:
34
35 $ ruby app.rb -s Puma
36
37 Or you can configure your application to always use Puma:
38
39 require 'sinatra'
40 configure { set :server, :puma }
41
42 If you use Bundler, make sure you add Puma to your Gemfile (see below).
43
44 ### Rails
45
46 First, make sure Puma is in your Gemfile:
47
48 gem 'puma'
49
50 Then start your server with the `rails` command:
51
efb7fad @mifix Updated start command for rails
mifix authored
52 $ rails s Puma
7a9a8e2 @rkh Add documentation for Rails/Sinatra/Rack usage
rkh authored
53
54 ### Rackup
55
56 You can pass it as an option to `rackup`:
57
6e6b0b0 Edit rackup start command to rackup -s Puma.
Hendra Uzia authored
58 $ rackup -s Puma
7a9a8e2 @rkh Add documentation for Rails/Sinatra/Rack usage
rkh authored
59
60 Alternatively, you can modify your `config.ru` to choose Puma by default, by adding the following as the first line:
61
62 #\ -s puma
225b556 @kyledrake Update README file to provide more details
kyledrake authored
63
64 ## Configuration
65
66 Puma provides numerous options for controlling the operation of the server. Consult `puma -h` (or `puma --help`) for a full list.
67
68 ### Thread Pool
69
70 Puma utilizes a dynamic thread pool which you can modify. You can set the minimum and maximum number of threads that are available in the pool with the `-t` (or `--threads`) flag:
71
72 $ puma -t 8:32
92a1f13 Modified README.
Maik Kempe authored
73
225b556 @kyledrake Update README file to provide more details
kyledrake authored
74 Puma will automatically scale the number of threads based on how much traffic is present. The current default is `0:16`. Feel free to experiment, but be careful not to set the number of maximum threads to a very large number, as you may exhaust resources on the system (or hit resource limits).
75
7e38415 @catsby Add some documentation for Clustered mode
catsby authored
76 ### Clustered mode
77
78 Puma 2 offers clustered mode, allowing you to use forked processes to handle multiple incoming requests concurrently, in addition to threads already provided. You can tune the number of workers with the `-w` (or `--workers`) flag:
79
80 $ puma -t 8:32 -w 3
4a65718 @catsby a little more or Thread use with Clustered mode
catsby authored
81
f4bccd2 @Juanmcuello Move on_worker_boot paragraph in clustered mode.
Juanmcuello authored
82 On a ruby implementation that offers native threads, you should tune this number to match the number of cores available.
83 Note that threads are still used in clustered mode, and the `-t` thread flag setting is per worker, so `-w 2 -t 16:16` will be 32 threads.
0d09337 @catsby Document preload options
catsby authored
84
2a8c68f @joevandyk Fix speling in README.md
joevandyk authored
85 If you're running in Clustered Mode you can optionally choose to preload your application before starting up the workers. This is necessary in order to take advantage of the [Copy on Write](http://en.wikipedia.org/wiki/Copy-on-write) feature introduced in [MRI Ruby 2.0](https://blog.heroku.com/archives/2013/3/6/matz_highlights_ruby_2_0_at_waza). To do this simply specify the `--preload` flag in invocation:
0d09337 @catsby Document preload options
catsby authored
86
87 # CLI invocation
88 $ puma -t 8:32 -w 3 --preload
f4bccd2 @Juanmcuello Move on_worker_boot paragraph in clustered mode.
Juanmcuello authored
89
0d09337 @catsby Document preload options
catsby authored
90 If you're using a configuration file, use the `preload_app!` method, and be sure to specify your config file's location with the `-C` flag:
91
92 $ puma -C config/puma.rb
f4bccd2 @Juanmcuello Move on_worker_boot paragraph in clustered mode.
Juanmcuello authored
93
0d09337 @catsby Document preload options
catsby authored
94 # config/puma.rb
95 threads 8,32
96 workers 3
f4bccd2 @Juanmcuello Move on_worker_boot paragraph in clustered mode.
Juanmcuello authored
97 preload_app!
0d09337 @catsby Document preload options
catsby authored
98
f4bccd2 @Juanmcuello Move on_worker_boot paragraph in clustered mode.
Juanmcuello authored
99 Additionally, you can specify a block in your configuration file that will be run on boot of each worker:
7e38415 @catsby Add some documentation for Clustered mode
catsby authored
100
101 # config/puma.rb
102 on_worker_boot do
103 # configuration here
104 end
f4bccd2 @Juanmcuello Move on_worker_boot paragraph in clustered mode.
Juanmcuello authored
105
106 This code can be used to setup the process before booting the application, allowing
58434d7 @catsby Clarify some platform specifics
catsby authored
107 you to do some Puma-specific things that you don't want to embed in your application.
f4bccd2 @Juanmcuello Move on_worker_boot paragraph in clustered mode.
Juanmcuello authored
108 For instance, you could fire a log notification that a worker booted or send something to statsd.
109 This can be called multiple times to add hooks.
110
111 If you're preloading your application and using ActiveRecord, it's recommend you setup your connection pool here:
7e38415 @catsby Add some documentation for Clustered mode
catsby authored
112
0d09337 @catsby Document preload options
catsby authored
113 # config/puma.rb
114 on_worker_boot do
115 ActiveSupport.on_load(:active_record) do
116 ActiveRecord::Base.establish_connection
117 end
118 end
6258581 @sorentwo Change umask examples to more permissive values
sorentwo authored
119
399a484 @brixen Update README.md
brixen authored
120 When you use preload_app, your new code goes all in the master process, and is then copied in the workers (meaning it’s only compatible with cluster mode). General rule is to use preload_app when your workers die often and need fast starts. If you don’t have many workers, you probably should not use preload_app.
f131df9 @sammcj Update README.md
sammcj authored
121
122 Note that preload_app can’t be used with phased restart, since phased restart kills and restarts workers one-by-one, and preload_app is all about copying the code of master into the workers.
7e38415 @catsby Add some documentation for Clustered mode
catsby authored
123
225b556 @kyledrake Update README file to provide more details
kyledrake authored
124 ### Binding TCP / Sockets
125
16f7490 @kyledrake Clarify and fix typo for bind info
kyledrake authored
126 In contrast to many other server configs which require multiple flags, Puma simply uses one URI parameter with the `-b` (or `--bind`) flag:
225b556 @kyledrake Update README file to provide more details
kyledrake authored
127
128 $ puma -b tcp://127.0.0.1:9292
129
130 Want to use UNIX Sockets instead of TCP (which can provide a 5-10% performance boost)? No problem!
131
132 $ puma -b unix:///var/run/puma.sock
133
3dd7049 @evanphx Fix and configure the perms of UNIXServer. Fixes #44
evanphx authored
134 If you need to change the permissions of the UNIX socket, just add a umask parameter:
135
6258581 @sorentwo Change umask examples to more permissive values
sorentwo authored
136 $ puma -b 'unix:///var/run/puma.sock?umask=0111'
3dd7049 @evanphx Fix and configure the perms of UNIXServer. Fixes #44
evanphx authored
137
138 Need a bit of security? Use SSL sockets!
139
140 $ puma -b 'ssl://127.0.0.1:9292?key=path_to_key&cert=path_to_cert'
141
38780d8 @evanphx Add more docs to the README
evanphx authored
142 ### Control/Status Server
143
58434d7 @catsby Clarify some platform specifics
catsby authored
144 Puma comes with a builtin status/control app that can be used query and control Puma itself. Here is an example of starting Puma with the control server:
38780d8 @evanphx Add more docs to the README
evanphx authored
145
146 $ puma --control tcp://127.0.0.1:9293 --control-token foo
147
58434d7 @catsby Clarify some platform specifics
catsby authored
148 This directs Puma to start the control server on localhost port 9293. Additionally, all requests to the control server will need to include `token=foo` as a query parameter. This allows for simple authentication. Check out [status.rb](https://github.com/puma/puma/blob/master/lib/puma/app/status.rb) to see what the app has available.
38780d8 @evanphx Add more docs to the README
evanphx authored
149
92a1f13 Modified README.
Maik Kempe authored
150 ### Configuration file
151
58434d7 @catsby Clarify some platform specifics
catsby authored
152 You can also provide a configuration file which Puma will use with the `-C` (or `--config`) flag:
8715d93 Modified README.
Maik Kempe authored
153
92a1f13 Modified README.
Maik Kempe authored
154 $ puma -C /path/to/config
155
9d6bcf6 @brianknight10 Described the configuration file finding behavior added in 2.8.0 and how...
brianknight10 authored
156 By default, if no configuration file is specifed, Puma will look for a configuration file at config/puma.rb. If an environment is specified, either via the `-e` and `--environment` flags, or through the `RACK_ENV` environment variable, the default file location will be config/puma/environment_name.rb.
157
158 If you want to prevent Puma from looking for a configuration file in those locations, provide a dash as the argument to the `-C` (or `--config`) flag:
159
160 $ puma -C "-"
161
4dabeb7 @TrevorBramble Update README.md
TrevorBramble authored
162 Take the following [sample configuration](https://github.com/puma/puma/blob/master/examples/config.rb) as inspiration or check out [configuration.rb](https://github.com/puma/puma/blob/master/lib/puma/configuration.rb) to see all available options.
8eedae4 Moved sample configuration into existing one.
Maik Kempe authored
163
38780d8 @evanphx Add more docs to the README
evanphx authored
164 ## Restart
165
58434d7 @catsby Clarify some platform specifics
catsby authored
166 Puma includes the ability to restart itself allowing easy upgrades to new versions. When available (MRI, Rubinius, JRuby), Puma performs a "hot restart". This is the same functionality available in *unicorn* and *nginx* which keep the server sockets open between restarts. This makes sure that no pending requests are dropped while the restart is taking place.
38780d8 @evanphx Add more docs to the README
evanphx authored
167
825c9e8 @perplexes Fix typo
perplexes authored
168 To perform a restart, there are 2 builtin mechanisms:
38780d8 @evanphx Add more docs to the README
evanphx authored
169
58434d7 @catsby Clarify some platform specifics
catsby authored
170 * Send the `puma` process the `SIGUSR2` signal
38780d8 @evanphx Add more docs to the README
evanphx authored
171 * Use the status server and issue `/restart`
172
58434d7 @catsby Clarify some platform specifics
catsby authored
173 No code is shared between the current and restarted process, so it should be safe to issue a restart any place where you would manually stop Puma and start it again.
38780d8 @evanphx Add more docs to the README
evanphx authored
174
58434d7 @catsby Clarify some platform specifics
catsby authored
175 If the new process is unable to load, it will simply exit. You should therefore run Puma under a supervisor when using it in production.
38780d8 @evanphx Add more docs to the README
evanphx authored
176
f131df9 @sammcj Update README.md
sammcj authored
177 ### Normal vs Hot vs Phased Restart
178
179 A hot restart means that no requests while deploying your new code will be lost, since the server socket is kept open between restarts.
180
181 But beware, hot restart does not mean that the incoming requests won’t hang for multiple seconds while your new code has not fully deployed. If you need a zero downtime and zero hanging requests deploy, you must use phased restart.
182
183 When you run pumactl phased-restart, Puma kills workers one-by-one, meaning that at least another worker is still available to serve requests, which lead in zero hanging request (yay!).
184
185 But again beware, upgrading an application sometimes involves upgrading the database schema. With phased restart, there may be a moment during the deployment where processes belonging to the previous version and processes belonging to the new version both exist at the same time. Any database schema upgrades you perform must therefore be backwards-compatible with the old application version.
186
187 if you perform a lot of database migrations, you probably should not use phased restart and use a normal/hot restart instead (pumactl restart). That way, no code is shared while deploying (in that case, preload_app might help for quicker deployment, see below).
188
189
a8b4633 @evanphx Add documentation for the on_restart hook
evanphx authored
190 ### Cleanup Code
191
58434d7 @catsby Clarify some platform specifics
catsby authored
192 Puma isn't able to understand all the resources that your app may use, so it provides a hook in the configuration file you pass to `-C` called `on_restart`. The block passed to `on_restart` will be called, unsurprisingly, just before Puma restarts itself.
a8b4633 @evanphx Add documentation for the on_restart hook
evanphx authored
193
194 You should place code to close global log files, redis connections, etc in this block so that their file descriptors don't leak into the restarted process. Failure to do so will result in slowly running out of descriptors and eventually obscure crashes as the server is restart many times.
195
e6ae403 @jcbantuelle Correct Typo in README.md
jcbantuelle authored
196 ### Platform Constraints
9d4811f @evanphx Better document some platform constraints
evanphx authored
197
58434d7 @catsby Clarify some platform specifics
catsby authored
198 Because of various platforms not being implement certain things, the following differences occur when Puma is used on different platforms:
9d4811f @evanphx Better document some platform constraints
evanphx authored
199
58434d7 @catsby Clarify some platform specifics
catsby authored
200 * **JRuby**, **Windows**: server sockets are not seamless on restart, they must be closed and reopened. These platforms have no way to pass descriptors into a new process that is exposed to ruby
201 * **JRuby**, **Windows**: cluster mode is not supported due to a lack of fork(2)
202 * **Windows**: daemon mode is not supported due to a lack of fork(2)
9d4811f @evanphx Better document some platform constraints
evanphx authored
203
38780d8 @evanphx Add more docs to the README
evanphx authored
204 ## pumactl
205
f9fc59b remove obsolete pumactl instructions; refer to pumactl for details
Trung Lê authored
206 `pumactl` is a simple CLI frontend to the control/status app described above. Please refer to `pumactl --help` for available commands.
e2c0f0c @jpascal Add more options to pumactl
jpascal authored
207
eec5702 Added a general jungle README and modified the general docs to tell abou...
Darío Javier Cravero authored
208 ## Managing multiple Pumas / init.d / upstart scripts
f2cb62c Implemented an init.d script to manage the Jungle.
Darío Javier Cravero authored
209
eec5702 Added a general jungle README and modified the general docs to tell abou...
Darío Javier Cravero authored
210 If you want an easy way to manage multiple scripts at once check [tools/jungle](https://github.com/puma/puma/tree/master/tools/jungle) for init.d and upstart scripts.
f2cb62c Implemented an init.d script to manage the Jungle.
Darío Javier Cravero authored
211
70daed8 @joneslee85 add capistrano note into README
joneslee85 authored
212 ## Capistrano deployment
213
2847fdb @mariuz Update README.md
mariuz authored
214 Puma has support for Capistrano3 with an [external gem](https://github.com/seuros/capistrano-puma), you just need require that in Gemfile:
70daed8 @joneslee85 add capistrano note into README
joneslee85 authored
215
2847fdb @mariuz Update README.md
mariuz authored
216 ```ruby
217 gem 'capistrano3-puma'
218 ```
219 And then execute:
220
221 ```bash
222 bundle
223 ```
224
225 Then add to Capfile
70daed8 @joneslee85 add capistrano note into README
joneslee85 authored
226
227 ```ruby
2847fdb @mariuz Update README.md
mariuz authored
228 require 'capistrano/puma'
70daed8 @joneslee85 add capistrano note into README
joneslee85 authored
229 ```
230
231 and then
232
233 ```bash
30cd9fa @petergoldstein Fix bad link, typos in bundle commands
petergoldstein authored
234 $ bundle exec cap puma:start
f4bccd2 @Juanmcuello Move on_worker_boot paragraph in clustered mode.
Juanmcuello authored
235 $ bundle exec cap puma:restart
30cd9fa @petergoldstein Fix bad link, typos in bundle commands
petergoldstein authored
236 $ bundle exec cap puma:stop
44cbda1 @Juanmcuello Add phased restart to capistrano recipe.
Juanmcuello authored
237 $ bundle exec cap puma:phased_restart
70daed8 @joneslee85 add capistrano note into README
joneslee85 authored
238 ```
239
987ff95 @jjb readme notes on running test suite
jjb authored
240 ## Contributing
241
242 To run the test suite:
243
244 ```bash
245 $ bundle install
246 $ bundle exec rake
247 ```
70daed8 @joneslee85 add capistrano note into README
joneslee85 authored
248
225b556 @kyledrake Update README file to provide more details
kyledrake authored
249 ## License
250
388940a @mariuz Update README.md
mariuz authored
251 Puma is copyright 2014 Evan Phoenix and contributors. It is licensed under the BSD 3-Clause license. See the include LICENSE file for details.
Something went wrong with that request. Please try again.