Skip to content
This repository
Newer
Older
100644 127 lines (65 sloc) 6.453 kb
43cb2004 » evanphx
2011-10-07 Switch README to format hoe understands
1 # Puma: A Ruby Web Server Built For Concurrency
1888887d » tarcieri
2011-10-01 Redo README in Markdown and replace Mongrel with Puma
2
a4e28070 » laserlemon
2012-04-02 Add Travis build and Gemnasium dependency status images to the README
3 [![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)
4
43cb2004 » evanphx
2011-10-07 Switch README to format hoe understands
5 ## Description
1888887d » tarcieri
2011-10-01 Redo README in Markdown and replace Mongrel with Puma
6
225b556a » kyledrake
2012-01-06 Update README file to provide more details
7 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.
1888887d » tarcieri
2011-10-01 Redo README in Markdown and replace Mongrel with Puma
8
cc2ca8a5 » kyledrake
2012-01-06 Fix extension typo
9 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!
1888887d » tarcieri
2011-10-01 Redo README in Markdown and replace Mongrel with Puma
10
225b556a » kyledrake
2012-01-06 Update README file to provide more details
11 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.
1888887d » tarcieri
2011-10-01 Redo README in Markdown and replace Mongrel with Puma
12
bc0b3a5d » jc00ke
2012-03-21 Fix typo
13 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).
1888887d » tarcieri
2011-10-01 Redo README in Markdown and replace Mongrel with Puma
14
43cb2004 » evanphx
2011-10-07 Switch README to format hoe understands
15 ## Quick Start
1888887d » tarcieri
2011-10-01 Redo README in Markdown and replace Mongrel with Puma
16
225b556a » kyledrake
2012-01-06 Update README file to provide more details
17 The easiest way to get started with Puma is to install it via RubyGems. You can do this easily:
1888887d » tarcieri
2011-10-01 Redo README in Markdown and replace Mongrel with Puma
18
06072d03 » tarcieri
2011-10-01 Indent examples at the level Markdown expects
19 $ gem install puma
1888887d » tarcieri
2011-10-01 Redo README in Markdown and replace Mongrel with Puma
20
225b556a » kyledrake
2012-01-06 Update README file to provide more details
21 Now you should have the puma command available in your PATH, so just do the following in the root folder of your Rack application:
1888887d » tarcieri
2011-10-01 Redo README in Markdown and replace Mongrel with Puma
22
4f69300f » evanphx
2011-10-04 Prune the README.md
23 $ puma app.ru
1888887d » tarcieri
2011-10-01 Redo README in Markdown and replace Mongrel with Puma
24
7a9a8e28 » rkh
2011-10-25 Add documentation for Rails/Sinatra/Rack usage
25 ## Advanced Setup
26
27 ### Sinatra
28
29 You can run your Sinatra application with Puma from the command line like this:
30
31 $ ruby app.rb -s Puma
32
33 Or you can configure your application to always use Puma:
34
35 require 'sinatra'
36 configure { set :server, :puma }
37
38 If you use Bundler, make sure you add Puma to your Gemfile (see below).
39
40 ### Rails
41
42 First, make sure Puma is in your Gemfile:
43
44 gem 'puma'
45
46 Then start your server with the `rails` command:
47
48 $ rails s puma
49
50 ### Rackup
51
52 You can pass it as an option to `rackup`:
53
54 $ rackup -s puma
55
56 Alternatively, you can modify your `config.ru` to choose Puma by default, by adding the following as the first line:
57
58 #\ -s puma
225b556a » kyledrake
2012-01-06 Update README file to provide more details
59
60 ## Configuration
61
62 Puma provides numerous options for controlling the operation of the server. Consult `puma -h` (or `puma --help`) for a full list.
63
64 ### Thread Pool
65
66 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:
67
68 $ puma -t 8:32
69
70 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).
71
72 ### Binding TCP / Sockets
73
16f74903 » kyledrake
2012-01-06 Clarify and fix typo for bind info
74 In contrast to many other server configs which require multiple flags, Puma simply uses one URI parameter with the `-b` (or `--bind`) flag:
225b556a » kyledrake
2012-01-06 Update README file to provide more details
75
76 $ puma -b tcp://127.0.0.1:9292
77
78 Want to use UNIX Sockets instead of TCP (which can provide a 5-10% performance boost)? No problem!
79
80 $ puma -b unix:///var/run/puma.sock
81
3dd7049f » evanphx
2012-03-30 Fix and configure the perms of UNIXServer. Fixes #44
82 If you need to change the permissions of the UNIX socket, just add a umask parameter:
83
84 $ puma -b 'unix:///var/run/puma.sock?umask=0777'
85
86 Need a bit of security? Use SSL sockets!
87
88 $ puma -b 'ssl://127.0.0.1:9292?key=path_to_key&cert=path_to_cert'
89
38780d85 » evanphx
2012-04-11 Add more docs to the README
90 ### Control/Status Server
91
92 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:
93
94 $ puma --control tcp://127.0.0.1:9293 --control-token foo
95
96 This directly 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 [https://github.com/puma/puma/blob/master/lib/puma/app/status.rb]() to see what the app has available.
97
98 ## Restart
99
100 Puma includes the ability to restart itself, allowing for new versions to be easily upgraded to. When available (currently anywhere but 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.
101
102 To perform a restart, there are 2 builtin mechanism:
103
104 * Send the puma process the `SIGUSR2` signal
105 * Use the status server and issue `/restart`
106
107 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.
108
109 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.
110
a8b4633d » evanphx
2012-04-11 Add documentation for the on_restart hook
111 ### Cleanup Code
112
113 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` call `on_restart`. The block passed to `on_restart` will be called, unsurprisingly, just before puma restarts itself.
114
115 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.
116
38780d85 » evanphx
2012-04-11 Add more docs to the README
117 ## pumactl
118
119 If you start puma with `-S some/path` then you can pass that same path to the `pumactl` program to control your server. For instance:
120
121 $ pumactl -S some/path restart
122
123 will cause the server to perform a restart. `pumactl` is a simple CLI frontend to the contro/status app described above.
124
225b556a » kyledrake
2012-01-06 Update README file to provide more details
125 ## License
126
127 Puma is copyright 2011 Evan Phoenix and contributors. It is licensed under the BSD license. See the include LICENSE file for details.
Something went wrong with that request. Please try again.