diff options
Diffstat (limited to 'README')
| -rw-r--r-- | README | 141 |
1 files changed, 108 insertions, 33 deletions
@@ -1,73 +1,148 @@ -= Unicorn: UNIX + LAN/localhost-only fork of Mongrel - -Only run this behind a full-HTTP-request-buffering reverse proxy if -you're serving slow clients. That said, nginx is the only reverse -proxy we know of that meets this requirement. += Unicorn: Unix + LAN/localhost-only fork of Mongrel == Features -* process management: Unicorn will reap and restart workers that - die because of broken apps and there is no need to manage - multiple processes yourself. +* Designed for Rack, Unix, fast clients, and ease-of-debugging. We + cut out all things that are better-supported by nginx or Rack. + +* Mostly written in Ruby, only the HTTP parser (stolen and trimmed + down from Mongrel) is written in C. Unicorn is compatible with + both Ruby 1.8 and 1.9. A pure-Ruby (but still Unix-only) version + is planned. + +* Process management: Unicorn will reap and restart workers that + die from broken apps. There is no need to manage multiple processes + or ports yourself. Unicorn can spawn and manage any fixed number of + worker processes you choose to scale to your backend. + +* Load balancing is done entirely by the operating system kernel. + Requests never pile up behind a busy worker process. -* does not care if your application is thread-safe or not, workers +* Does not care if your application is thread-safe or not, workers all run within their own isolated address space and only serve one - client at a time... + client at a time. -* able to listen on multiple interfaces, including UNIX sockets, - each worker process can also bind to a private port via the - after_fork hook for easy debugging. +* Supports all Rack applications, along with pre-Rack versions of + Ruby on Rails via a Rack wrapper. -* supports all Rack applications +* Builtin reopening of all log files in your application via + USR1 signal. This allows logrotate to rotate files atomically and + quickly via rename instead of the racy and slow copytruncate method. + Unicorn also takes steps to ensure multi-line log entries from one + request all stay within the same file. * nginx-style binary re-execution without losing connections. - You can upgrade unicorn, your entire application, libraries - and even your Ruby interpreter as long as unicorn is + You can upgrade Unicorn, your entire application, libraries + and even your Ruby interpreter as long as Unicorn is installed in the same path. * before_fork and after_fork hooks in case your application - has special needs when dealing with forked processes. + has special needs when dealing with forked processes. These + should not be needed when the "preload_app" directive is + false (the default). -* builtin log rotation via USR1 signal +* Can be used with copy-on-write-friendly memory management + to save memory (by setting "preload_app" to true). -* Ruby 1.9-compatible (at least the test cases all pass :>) +* Able to listen on multiple interfaces including UNIX sockets, + each worker process can also bind to a private port via the + after_fork hook for easy debugging. == License Unicorn is copyright 2009 Eric Wong and contributors. -It is based on Mongrel: +It is based on Mongrel and carries the same license: Mongrel is copyright 2007 Zed A. Shaw and contributors. It is licensed -under the Ruby license and the GPL2. See the include LICENSE file for +under the Ruby license and the GPL2. See the included LICENSE file for details. +Unicorn is 100% Free Software. + == Install The library consists of a C extension so you'll need a C compiler or at least a friend who can build it for you. -Finally, the source includes a setup.rb for those who hate RubyGems. +You may download the tarball from the Mongrel project page on Rubyforge +and run setup.rb after unpacking it: -You can get the source via git via the following locations: +http://rubyforge.org/frs/?group_id=1306 - git://git.bogomips.org/unicorn.git +You may also install it via Rubygems on Rubyforge: + + gem install unicorn + +You can get the latest source via git from the following locations +(these versions may not be stable): + git://git.bogomips.org/unicorn.git http://git.bogomips.org/unicorn.git + git://repo.or.cz/unicorn.git (mirror) + http://repo.or.cz/r/unicorn.git (mirror) + +If you have web browser software for the World Wide Web +(on the Information Superhighway), you may browse the code from +your web browser and download the latest snapshot tarballs here: + +* http://git.bogomips.org/cgit/unicorn.git (cgit) +* http://repo.or.cz/w/unicorn.git (gitweb) == Usage +=== non-Rails Rack applications + +In APP_ROOT, run: + + unicorn + +=== for Rails applications (should work for all 1.2 or later versions) + +In RAILS_ROOT, run: + + unicorn_rails + +Unicorn will bind to all interfaces TCP port 8080 by default. +You may use the +-l/--listen+ switch to bind to a different +address:port or a UNIX socket. + +=== Configuration File(s) + Unicorn will look for the config.ru file used by rackup in APP_ROOT. -Optionally, it can use a config file specified by the --config-file/-c -command-line switch. -Unicorn should be capable of running all Rack applications. Since this -is a preforking webserver, you do not have to worry about thread-safety -of your application or libraries. However, your Rack application may use -threads internally (and should even be able to continue running threads -after the request is complete). +For deployments, it can use a config file for Unicorn-specific options +specified by the +--config-file/-c+ command-line switch. See +Unicorn::Configurator for the syntax of the Unicorn-specific options. +The default settings are designed for maximum out-of-the-box +compatibility with existing applications. -== Contact +Most command-line options for other Rack applications (above) are also +supported. Run `unicorn -h` or `unicorn_rails -h` to see command-line +options. -Newsgroup and mailing list coming, or it'll be a part of the Mongrel project... +== Disclaimer + +Like the creatures themselves, production deployments of Unicorn are +rare or even non-existent. There is NO WARRANTY whatsoever if anything +goes wrong, but let us know and we'll try our best to fix it. + +Unicorn is designed to only serve fast clients. See the PHILOSOPHY +and DESIGN documents for more details regarding this. + +Rainbows are NOT included. + +== Known Issues + +* WONTFIX: code reloading with Sinatra 0.3.2 (and likely older + versions) apps is broken. The workaround is to force production + mode to disable code reloading in your Sinatra application: + set :env, :production + Since this is no longer an issue with Sinatra 0.9.x apps and only + affected non-production instances, this will not be fixed on our end. + Also remember we're capable of replacing the running binary without + dropping any connections regardless of framework :) + +== Contact Email Eric Wong at normalperson@yhbt.net for now. +Newsgroup and mailing list maybe coming... |