passenger 2.1.3 → 2.2.0

data/doc/users_guide_snippets/global_queueing_explained.txt

@@ -0,0 +1,78 @@
+.What does this option do?
+
+Recall that Phusion Passenger spawns multiple backend processes (e.g. multiple
+Ruby on Rails processes), each which processes HTTP requests serially. One of
+Phusion Passenger's jobs is to forward HTTP requests to a suitable backend
+process. A backend process may take an arbitrary amount of time to process a
+specific HTTP request. If the websites are (temporarily) under high load, and
+the backend processes cannot process the requests fast enough, then some
+requests may have to be queued.
+
+If global queuing is turned off, then Phusion Passenger will use 'fair load
+balancing'. This means that each backend process will have its own private
+queue. Phusion Passenger will forward an HTTP request to the backend process
+that has the least amount of requests in its queue.
+
+If global queuing is turned on, then Phusion Passenger will use a global queue
+that's shared between all backend processes. If an HTTP request comes in, and
+all the backend processes are still busy, then Phusion Passenger will wait until
+at least one backend process is done, and will then forward the request to that
+process.
+
+.When to turn on global queuing?
+
+You should turn on global queuing if one of your web applications may have
+long-running requests.
+
+For example suppose that:
+
+- global queuing is turned off.
+- we're currently in a state where all backend processes have 3 requests in
+  their queue, except for a single backend process, which has 1 request in its
+  queue.
+
+The situation looks like this:
+
+--------------------------------------------------
+Backend process A:  [*     ]  (1 request in queue)
+Backend process B:  [***   ]  (3 requests in queue)
+Backend process C:  [***   ]  (3 requests in queue)
+Backend process D:  [***   ]  (3 requests in queue)
+--------------------------------------------------
+
+Each process is currently serving short-running requests.
+
+Phusion Passenger will forward the next request to backend process A. A will
+now have 2 items in its queue. We'll mark this new request with an X:
+
+--------------------------------------------------
+Backend process A:  [*X    ]  (2 request in queue)
+Backend process B:  [***   ]  (3 requests in queue)
+Backend process C:  [***   ]  (3 requests in queue)
+Backend process D:  [***   ]  (3 requests in queue)
+--------------------------------------------------
+
+Assuming that B, C and D still aren't done with their current request, the next
+HTTP request - let's call this Y - will be forwarded to backend process A as
+well, because it has the least number of items in its queue:
+
+--------------------------------------------------
+Backend process A:  [*XY   ]  (3 requests in queue)
+Backend process B:  [***   ]  (3 requests in queue)
+Backend process C:  [***   ]  (3 requests in queue)
+Backend process D:  [***   ]  (3 requests in queue)
+--------------------------------------------------
+
+But if request X happens to be a long-running request that needs 60 seconds to
+complete, then we'll have a problem. Y won't be processed for at least 60
+seconds. It would have been a better idea if Y was forward to processes B, C or
+D instead, because they only have short-living requests in their queues.
+
+This problem will be avoided entirely if you turn global queuing on. With global
+queuing, all backend processes will share the same queue. The first backend
+process that becomes available will take from the queue, and so this
+``queuing-behind-long-running-request'' problem will never occur.
+
+Turning global queuing off will yield a minor performance improvement (about 5%,
+depending on how fast/slow your web application is), which is why it's off by
+default.

data/doc/users_guide_snippets/rackup_specifications.txt

@@ -0,0 +1,75 @@
+This subsection shows example 'config.ru' files for various web frameworks.
+
+==== Camping ====
+------------------------------------------------------
+require 'rubygems'
+require 'rack'
+require 'camping'
+
+##### Begin Camping application
+Camping.goes :Blog
+
+...your application code here...
+##### End Camping application
+
+run Rack::Adapter::Camping.new(Blog)
+------------------------------------------------------
+
+For Camping versions 2.0 and up, using `run Blog` as the final line will do.
+
+==== Halcyon ====
+------------------------------------------------------
+require 'rubygems'
+require 'halcyon'
+$LOAD_PATH.unshift(Halcyon.root / 'lib')
+Halcyon::Runner.load_config Halcyon.root/'config'/'config.yml'
+run Halcyon::Runner.new
+------------------------------------------------------
+
+==== Mack ====
+------------------------------------------------------
+ENV["MACK_ENV"] = ENV["RACK_ENV"]
+load("Rakefile")
+require 'rubygems'
+require 'mack'
+run Mack::Utils::Server.build_app
+------------------------------------------------------
+
+==== Merb ====
+------------------------------------------------------
+require 'rubygems'
+require 'merb-core'
+
+Merb::Config.setup(
+  :merb_root   => File.expand_path(File.dirname(__FILE__)),
+  :environment => ENV['RACK_ENV']
+)
+Merb.environment = Merb::Config[:environment]
+Merb.root = Merb::Config[:merb_root]
+Merb::BootLoader.run
+
+run Merb::Rack::Application.new
+------------------------------------------------------
+
+==== Ramaze ====
+------------------------------------------------------
+require "start"
+Ramaze.trait[:essentials].delete Ramaze::Adapter
+Ramaze.start :force => true
+run Ramaze::Adapter::Base
+------------------------------------------------------
+
+==== Sinatra ====
+------------------------------------------------------
+require 'rubygems'
+require 'sinatra'
+
+root_dir = File.dirname(__FILE__)
+
+set :environment, ENV['RACK_ENV'].to_sym
+set :root,        root_dir
+set :app_file,    File.join(root_dir, 'app.rb')
+disable :run
+
+run Sinatra::Application
+------------------------------------------------------

data/doc/users_guide_snippets/rails_spawn_method.txt

@@ -0,0 +1,48 @@
+Internally, Phusion Passenger spawns multiple Ruby on Rails processes in order to handle
+requests. But there are multiple ways with which processes can be spawned, each having
+its own set of pros and cons. Supported spawn methods are:
+
+'smart'::
+When this spawn method is used, Phusion Passenger will attempt to cache Ruby on Rails
+framework code and application code for a limited period of time. Please read
+<<spawning_methods_explained,Spawning methods explained>> for a more detailed
+explanation of what smart spawning exactly does.
++
+*Pros:*
+This can significantly decrease spawn time (by as much as 90%). And, when Ruby Enterprise
+Edition is used, <<reducing_memory_usage,memory usage can be reduced by 33% on average>>.
++
+*Cons:*
+Some Ruby on Rails applications and libraries are not compatible with smart spawning.
+If that's the case for your application, then you should use 'conservative' as
+spawning method.
+
+'smart-lv2'::
+This spawning method is similar to 'smart' but it skips the framework spawner
+and uses the application spawner directly. This means the framework code is not
+cached between multiple applications, although it is still cached within
+instances of the same application. Please read
+<<spawning_methods_explained,Spawning methods explained>> for a more detailed
+explanation of what smart-lv2 spawning exactly does.
++
+*Pros:* It is compatible with a larger number of applications when compared to
+the 'smart' method, and still performs some caching.
++
+*Cons:* It is slower than smart spawning if you have many applications which
+use the same framework version. It is therefore advised that shared hosts use the
+'smart' method instead.
+
+'conservative'::
+This spawning method is similar to the one used in Mongrel Cluster. It does not
+perform any code caching at all. Please read
+<<spawning_methods_explained,Spawning methods explained>> for a more detailed
+explanation of what conservative spawning exactly does.
++
+*Pros:*
+Conservative spawning is guaranteed to be compatible with all Rails applications
+and libraries.
++
+*Cons:*
+Much slower than smart spawning. Every spawn action will be equally slow, though no slower than
+the startup time of a single server in Mongrel Cluster. Conservative spawning will also
+render <<reducing_memory_usage,Ruby Enterprise Edition's memory reduction technology>> useless.

data/doc/users_guide_snippets/tips.txt

@@ -0,0 +1,173 @@
+[[user_switching]]
+=== User switching (security) ===
+
+There is a problem that plagues most PHP web hosts, namely the fact that all PHP
+applications are run in the same user context as the web server. So for
+example, Joe's PHP application will be able to read Jane's PHP application's
+passwords. This is obviously undesirable on many servers.
+
+Phusion Passenger solves this problem by implementing 'user switching'. A Rails
+application is started as the owner of the file 'config/environment.rb',
+and a Rack application is started as the owner of the file 'config.ru'.
+So if '/home/webapps/foo/config/environment.rb' is owned by 'joe', then Phusion
+Passenger will launch the corresponding Rails application as 'joe' as well.
+
+This behavior is the default, and you don't need to configure anything. But
+there are things that you should keep in mind:
+
+- The owner of 'environment.rb' must have read access to the Rails application's
+  folder, and read/write access to the Rails application's 'logs' folder.
+  Likewise, the owner of 'config.ru' must have read access to the Rack application's
+  folder.
+- This feature is only available if Apache is started by 'root'. This is the
+  case on most Apache installations.
+- Under no circumstances will applications be run as 'root'. If
+  'environment.rb'/'config.ru' is owned as root or by an unknown user, then the
+  Rails/Rack application will run as the user specified by
+  <<PassengerDefaultUser,PassengerDefaultUser (Apache)>>/<<PassengerDefaultUser,passenger_default_user (Nginx)>>.
+
+User switching can be disabled with the
+<<PassengerUserSwitching,PassengerUserSwitching (Apache)>>/<<PassengerUserSwitching,passenger_user_switching (Nginx)>>
+option.
+
+
+[[reducing_memory_usage]]
+=== Reducing memory consumption of Ruby on Rails applications by 33% ===
+
+Is it possible to reduce memory consumption of your Rails applications by 33% on average,
+by using http://www.rubyenterpriseedition.com/[Ruby Enterprise Edition].
+Please visit the website for details.
+
+Note that this feature does not apply to Rack applications.
+
+[[capistrano]]
+=== Capistrano recipe ===
+
+Phusion Passenger can be combined with link:http://capify.org/[Capistrano].
+The following Capistrano recipe demonstrates Phusion Passenger support.
+It assumes that you're using Git as version control system.
+
+--------------------------------------------------
+set :application, "myapp"
+set :domain,      "example.com"
+set :repository,  "ssh://#{domain}/path-to-your-git-repo/#{application}.git"
+set :use_sudo,    false
+set :deploy_to,   "/path-to-your-web-app-directory/#{application}"
+set :scm,         "git"
+
+role :app, domain
+role :web, domain
+role :db,  domain, :primary => true
+
+namespace :deploy do
+  task :start, :roles => :app do
+    run "touch #{current_release}/tmp/restart.txt"
+  end
+  
+  task :stop, :roles => :app do
+    # Do nothing.
+  end
+  
+  desc "Restart Application"
+  task :restart, :roles => :app do
+    run "touch #{current_release}/tmp/restart.txt"
+  end
+end
+--------------------------------------------------
+
+
+[[moving_phusion_passenger]]
+=== Moving Phusion Passenger to a different directory ===
+
+It is possible to relocate the Phusion Passenger files to a different directory. It
+involves two steps:
+
+1. Moving the directory.
+2. Updating the ``PassengerRoot'' configuration option in Apache.
+
+For example, if Phusion Passenger is located in '/opt/passenger/', and you'd like to
+move it to '/usr/local/passenger/', then do this:
+
+1. Run the following command:
++
+------------------------------------
+mv /opt/passenger /usr/local/passenger
+------------------------------------
+2. Edit your Apache configuration file, and set:
++
+------------------------------------
+PassengerRoot /usr/local/passenger
+------------------------------------
+
+=== Installing multiple Ruby on Rails versions ===
+
+Each Ruby on Rails applications that are going to be deployed may require a
+specific Ruby on Rails version. You can install a specific version with
+this command:
+-----------------------------
+gem install rails -v X.X.X
+-----------------------------
+where 'X.X.X' is the version number of Ruby on Rails.
+
+All of these versions will exist in parallel, and will not conflict with each
+other. Phusion Passenger will automatically make use of the correct version.
+
+=== Making the application restart after each request ===
+
+In some situations it might be desirable to restart the web application after
+each request, for example when developing a non-Rails application that doesn't
+support code reloading, or when developing a web framework.
+
+To achieve this, simply create the file 'tmp/always_restart.txt' in your
+application's root folder. Unlike 'restart.txt', Phusion Passenger does not
+check for this file's timestamp: Phusion Passenger will always restart the
+application, as long as 'always_restart.txt' exists.
+
+NOTE: If you're just developing a Rails application then you probably don't need
+this feature. If you set 'RailsEnv development' in your Apache configuration,
+then Rails will automatically reload your application code after each request.
+'always_restart.txt' is only useful if you're working on Ruby on Rails itself,
+or when you're not developing a Rails application and your web framework
+does not support code reloading.
+
+[[sub_uri_deployment_uri_fix]]
+=== How to fix broken images/CSS/JavaScript URIs in sub-URI deployments
+
+Some people experience broken images and other broken static assets when they
+deploy their application to a sub-URI (i.e. 'http://mysite.com/railsapp/').
+The reason for this usually is that you used a
+static URI for your image in the views. This means your 'img' source probably refers
+to something like '/images/foo.jpg'. The leading slash means that it's an absolute URI:
+you're telling the browser to always load 'http://mysite.com/images/foo.jpg' no
+matter what. The problem is that the image is actually at
+'http://mysite.com/railsapp/images/foo.jpg'. There are two ways to fix this.
+
+The first way (not recommended) is to change your view templates to refer to
+'images/foo.jpg'. This is a relative URI: note the lack of a leading slash). What
+this does is making the path relative to the current URI. The problem is that if you
+use restful URIs, then your images will probably break again when you add a level to
+the URI.
+For example, when you're at 'http://mysite.com/railsapp' the browser will look for
+'http://mysite.com/railsapp/images/foo.jpg'. But when you're at
+'http://mysite.com/railsapp/controller'. the browser will look for
+'http://mysite.com/railsapp/controller/images/foo.jpg'.
+So relative URIs usually don't work well with layout templates.
+
+The second and highly recommended way is to always use Rails helper methods to
+output tags for static assets. These helper methods automatically take care
+of prepending the base URI that you've deployed the application to. For images
+there is `image_tag`, for JavaScript there is `javascript_include_tag` and for
+CSS there is `stylesheet_link_tag`. In the above example you would simply remove
+the '<img>' HTML tag and replace it with inline Ruby like this:
+
+---------------------------------------
+<%= image_tag("foo.jpg") %>
+---------------------------------------
+
+This will generate the proper image tag to `$RAILS_ROOT/public/images/foo.jpg`
+so that your images will always work no matter what sub-URI you've deployed to.
+
+These helper methods are more valuable than you may think. For example they also
+append a timestamp to the URI to better facilitate HTTP caching. For more information,
+please refer to
+link:http://api.rubyonrails.org/classes/ActionView/Helpers/AssetTagHelper.html[the Rails API docs].

data/ext/apache2/Bucket.cpp

@@ -1,21 +1,26 @@
 /*
  *  Phusion Passenger - http://www.modrails.com/
- *  Copyright (C) 2008  Phusion
+ *  Copyright (c) 2008, 2009 Phusion
  *
- *  Phusion Passenger is a trademark of Hongli Lai & Ninh Bui.
+ *  "Phusion Passenger" is a trademark of Hongli Lai & Ninh Bui.
  *
- *  This program is free software; you can redistribute it and/or modify
- *  it under the terms of the GNU General Public License as published by
- *  the Free Software Foundation; version 2 of the License.
+ *  Permission is hereby granted, free of charge, to any person obtaining a copy
+ *  of this software and associated documentation files (the "Software"), to deal
+ *  in the Software without restriction, including without limitation the rights
+ *  to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+ *  copies of the Software, and to permit persons to whom the Software is
+ *  furnished to do so, subject to the following conditions:
  *
- *  This program is distributed in the hope that it will be useful,
- *  but WITHOUT ANY WARRANTY; without even the implied warranty of
- *  MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
- *  GNU General Public License for more details.
+ *  The above copyright notice and this permission notice shall be included in
+ *  all copies or substantial portions of the Software.
  *
- *  You should have received a copy of the GNU General Public License along
- *  with this program; if not, write to the Free Software Foundation, Inc.,
- *  51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA.
+ *  THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+ *  IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+ *  FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+ *  AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+ *  LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+ *  OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
+ *  THE SOFTWARE.
  */
 #include "Bucket.h"
 

data/ext/apache2/Bucket.h

@@ -1,21 +1,26 @@
 /*
  *  Phusion Passenger - http://www.modrails.com/
- *  Copyright (C) 2008  Phusion
+ *  Copyright (c) 2008, 2009 Phusion
  *
- *  Phusion Passenger is a trademark of Hongli Lai & Ninh Bui.
+ *  "Phusion Passenger" is a trademark of Hongli Lai & Ninh Bui.
  *
- *  This program is free software; you can redistribute it and/or modify
- *  it under the terms of the GNU General Public License as published by
- *  the Free Software Foundation; version 2 of the License.
+ *  Permission is hereby granted, free of charge, to any person obtaining a copy
+ *  of this software and associated documentation files (the "Software"), to deal
+ *  in the Software without restriction, including without limitation the rights
+ *  to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+ *  copies of the Software, and to permit persons to whom the Software is
+ *  furnished to do so, subject to the following conditions:
  *
- *  This program is distributed in the hope that it will be useful,
- *  but WITHOUT ANY WARRANTY; without even the implied warranty of
- *  MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
- *  GNU General Public License for more details.
+ *  The above copyright notice and this permission notice shall be included in
+ *  all copies or substantial portions of the Software.
  *
- *  You should have received a copy of the GNU General Public License along
- *  with this program; if not, write to the Free Software Foundation, Inc.,
- *  51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA.
+ *  THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+ *  IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+ *  FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+ *  AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+ *  LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+ *  OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
+ *  THE SOFTWARE.
  */
 #ifndef _PASSENGER_BUCKET_H_
 #define _PASSENGER_BUCKET_H_