Skip to content

HTTPS clone URL

Subversion checkout URL

You can clone with HTTPS or Subversion.

Download ZIP
Newer
Older
100644 132 lines (67 sloc) 6.597 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
a4e2807 @laserlemon Add Travis build and Gemnasium dependency status images to the README
laserlemon authored
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
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
225b556 @kyledrake Update README file to provide more details
kyledrake authored
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.
1888887 @tarcieri Redo README in Markdown and replace Mongrel with Puma
tarcieri authored
8
cc2ca8a @kyledrake Fix extension typo
kyledrake authored
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!
1888887 @tarcieri Redo README in Markdown and replace Mongrel with Puma
tarcieri authored
10
225b556 @kyledrake Update README file to provide more details
kyledrake authored
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.
1888887 @tarcieri Redo README in Markdown and replace Mongrel with Puma
tarcieri authored
12
bc0b3a5 @jc00ke Fix typo
jc00ke authored
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).
1888887 @tarcieri Redo README in Markdown and replace Mongrel with Puma
tarcieri authored
14
43cb200 @evanphx Switch README to format hoe understands
evanphx authored
15 ## Quick Start
1888887 @tarcieri Redo README in Markdown and replace Mongrel with Puma
tarcieri authored
16
225b556 @kyledrake Update README file to provide more details
kyledrake authored
17 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
18
06072d0 @tarcieri Indent examples at the level Markdown expects
tarcieri authored
19 $ gem install puma
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 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
22
4f69300 @evanphx Prune the README.md
evanphx authored
23 $ puma app.ru
1888887 @tarcieri Redo README in Markdown and replace Mongrel with Puma
tarcieri authored
24
7a9a8e2 @rkh Add documentation for Rails/Sinatra/Rack usage
rkh authored
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
efb7fad @mifix Updated start command for rails
mifix authored
48 $ rails s Puma
7a9a8e2 @rkh Add documentation for Rails/Sinatra/Rack usage
rkh authored
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
225b556 @kyledrake Update README file to provide more details
kyledrake authored
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
16f7490 @kyledrake Clarify and fix typo for bind info
kyledrake authored
74 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
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
3dd7049 @evanphx Fix and configure the perms of UNIXServer. Fixes #44
evanphx authored
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
38780d8 @evanphx Add more docs to the README
evanphx authored
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
0bfd707 @mikegehard Fix typo.
mikegehard authored
96 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 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
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
a8b4633 @evanphx Add documentation for the on_restart hook
evanphx authored
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
38780d8 @evanphx Add more docs to the README
evanphx authored
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
b7337c0 @Antiarchitect Typo fixed.
Antiarchitect authored
123 will cause the server to perform a restart. `pumactl` is a simple CLI frontend to the control/status app described above.
38780d8 @evanphx Add more docs to the README
evanphx authored
124
f2cb62c Implemented an init.d script to manage the Jungle.
Darío Javier Cravero authored
125 ## Managing multiple Pumas / init.d script
126
127 If you want an easy way to manage multiple scripts at once check "tools/jungle" for an init.d script.
128
225b556 @kyledrake Update README file to provide more details
kyledrake authored
129 ## License
130
131 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.