passenger 2.1.3 → 2.2.0

data/doc/{Users guide.txt → Users guide Apache.txt }

@@ -103,12 +103,15 @@ be located in the `sbin` folder instead of the `bin` folder.
 NOTE: You can skip this section if you've installed Phusion Passenger via a
 native Linux package, because no compilation is necessary.
 
-If your system has multiple Ruby installations (this is likely the case on
-MacOS X), then you will need to tell the Phusion Passenger installer which one
-to use. If you only have one Ruby installation (the case on most Linux systems),
-then you can skip this section because Phusion Passenger will automatically detect it.
-
-To specify the Ruby installation, prepend your Ruby installation's `bin`
+If your system has multiple Ruby installations -- which is likely the case on
+MacOS X, or if you've also installed
+link:http://www.rubyenterpriseedition.com[Ruby Enterprise Edition] -- then you
+will need to tell the operating system which Ruby installation to use, prior to
+running the Phusion Passenger installer. If you only have one Ruby installation
+(the case on most Linux systems), then you can skip this section because Phusion
+Passenger will automatically detect it.
+
+To specify a Ruby installation, prepend your Ruby installation's `bin`
 directory to the `PATH` environment variable. For example, if you have the
 following Ruby installations:
 
@@ -148,8 +151,8 @@ sudo apt-get install libapache2-mod-passenger
 
 ==== Installing via the source tarball ====
 
-Extract the tarball to whatever location you prefer. The Phusion Passenger files
-are to reside in that location permanently. For example, if you would like
+Extract the tarball to whatever location you prefer. *The Phusion Passenger files
+are to reside in that location permanently.* For example, if you would like
 Phusion Passenger to reside in `/opt/passenger-x.x.x`:
 ------------------------------------------------------
 cd /opt
@@ -178,6 +181,11 @@ on installing Phusion Passenger on OS X].
 
 Ben Hughes has written an link:http://www.railsgarden.com/2008/04/12/configurating-passenger-mod_rails-on-slicehost-with-ubuntu-710/[article on installing Phusion Passenger on Ubuntu].
 
+==== OpenSolaris ====
+
+J. Aaron Farr has written a link:http://cubiclemuses.com/cm/articles/2009/04/09/rails-passenger-open-solaris-ec2/[guide]
+about setting up Ruby on Rails and Phusion Passenger on OpenSolaris and EC2.
+
 
 == Deploying a Ruby on Rails application ==
 
@@ -433,82 +441,7 @@ touch /webapps/rackapp/tmp/restart.txt
 -------------------------------------------
 
 === Rackup specifications for various web frameworks ===
-
-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
-------------------------------------------------------
+include::users_guide_snippets/rackup_specifications.txt[]
 
 
 == Configuring Phusion Passenger ==
@@ -520,8 +453,12 @@ following configuration options:
 
 === PassengerRoot <directory> ===
 The location to the Phusion Passenger root directory. This configuration option
-is essential to Phusion Passenger. The correct value is given by the installer,
-and should usually not be changed manually.
+is essential to Phusion Passenger, and allows Phusion Passenger to locate its own
+data files. The correct value is given by the installer.
+
+If you've moved Phusion Passenger to a different directory then you need to update
+this option as well. Please read
+<<moving_phusion_passenger,Moving Phusion Passenger to a different directory>> for more information.
 
 This required option may only occur once, in the global server configuration.
 
@@ -589,84 +526,7 @@ In each place, it may be specified at most once. The default value is 'off'.
 
 'This feature is sponsored by http://www.37signals.com/[37signals].'
 
-.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.
+include::users_guide_snippets/global_queueing_explained.txt[]
 
 
 [[PassengerUserSwitching]]
@@ -678,7 +538,7 @@ The default value is 'on'.
 
 [[PassengerDefaultUser]]
 === PassengerDefaultUser <username> ===
-Passenger enables <<user_switching,user switching support>> by default.
+Phusion Passenger enables <<user_switching,user switching support>> by default.
 This configuration option allows one to specify which user Rails/Rack
 applications must run as, if user switching fails or is disabled.
 
@@ -1080,54 +940,7 @@ However, we do recommend you to try to understand it. The 'smart' and 'smart-lv2
 methods bring many benefits.
 =========================================================
 
-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.
+include::users_guide_snippets/rails_spawn_method.txt[]
 
 This option may occur in the following places:
 
@@ -1153,8 +966,12 @@ you're using the 'smart' <<RailsSpawnMethod,spawning method>>. So if your
 system has enough memory, is it recommended that you set this option to a high
 value or to '0'.
 
-This option may only occur in the global server configuration, and may occur at
-most once. The default value is '1800' (30 minutes).
+This option may occur in the following places:
+
+ * In the global server configuration.
+ * In a virtual host configuration block.
+
+In each place, it may be specified at most once. The default value is '1800' (30 minutes).
 
 ==== RailsAppSpawnerIdleTime <integer> ====
 The ApplicationSpawner server (explained in <<spawning_methods_explained,Spawning
@@ -1173,8 +990,12 @@ you're using the 'smart' or 'smart-lv2' <<RailsSpawnMethod,spawning method>>. So
 system has enough memory, is it recommended that you set this option to a high
 value or to '0'.
 
-This option may only occur in the global server configuration, and may occur at
-most once. The default value is '600' (10 minutes).
+This option may occur in the following places:
+
+ * In the global server configuration.
+ * In a virtual host configuration block.
+
+In each place, it may be specified at most once. The default value is '600' (10 minutes).
 
 === Rack-specific options ===
 
@@ -1578,291 +1399,12 @@ VirtualDocumentRoot is not compatible with Phusion Passenger at the moment.
 
 == Analysis and system maintenance tools ==
 
-Phusion Passenger provides a set of tools, which are useful for system analysis,
-maintenance and troubleshooting.
-
-
-=== Inspecting memory usage ===
-
-Process inspection tools such as `ps` and `top` are useful, but they
-link:http://groups.google.com/group/phusion-passenger/msg/1fd1c233456d3180[rarely show the correct memory usage].
-The real memory usage is usually lower than what `ps` and `top` report.
-
-There are many technical reasons why this is so, but an explanation is beyond
-the scope of this Users Guide. We kindly refer the interested reader to
-operating systems literature about 'virtual memory' and 'copy-on-write'.
-
-The tool `passenger-memory-stats` allows one to easily analyze Phusion Passenger's
-and Apache's real memory usage. For example:
-
--------------------------------------------------------
-[bash@localhost root]# passenger-memory-stats
-------------- Apache processes --------------.
-PID    PPID  Threads  VMSize   Private  Name
----------------------------------------------.
-5947   1     9        90.6 MB  0.5 MB   /usr/sbin/apache2 -k start
-5948   5947  1        18.9 MB  0.7 MB   /usr/sbin/fcgi-pm -k start
-6029   5947  1        42.7 MB  0.5 MB   /usr/sbin/apache2 -k start
-6030   5947  1        42.7 MB  0.5 MB   /usr/sbin/apache2 -k start
-6031   5947  1        42.5 MB  0.3 MB   /usr/sbin/apache2 -k start
-6033   5947  1        42.5 MB  0.4 MB   /usr/sbin/apache2 -k start
-6034   5947  1        50.5 MB  0.4 MB   /usr/sbin/apache2 -k start
-23482  5947  1        82.6 MB  0.4 MB   /usr/sbin/apache2 -k start
-### Processes: 8
-### Total private dirty RSS: 3.50 MB
-
---------- Passenger processes ---------.
-PID    Threads  VMSize   Private  Name
----------------------------------------.
-6026   1        10.9 MB  4.7 MB   Passenger spawn server
-23481  1        26.7 MB  3.0 MB   Passenger FrameworkSpawner: 2.0.2
-23791  1        26.8 MB  2.9 MB   Passenger ApplicationSpawner: /var/www/projects/app1-foobar
-23793  1        26.9 MB  17.1 MB  Rails: /var/www/projects/app1-foobar
-### Processes: 4
-### Total private dirty RSS: 27.76 M
--------------------------------------------------------
-
-The 'Private' or 'private dirty RSS' field shows the *real* memory usage of processes. Here,
-we see that all the Apache worker processes only take less than 1 MB memory each.
-This is a lot less than the 50 MB-ish memory usage as shown in the 'VMSize' column
-(which is what a lot of people think is the real memory usage, but is actually not).
-
-NOTE: This tool only works on Linux. Unfortunately other operating systems don't
-provide facilities for determining processes' private dirty RSS.
-
-
-=== Inspecting Phusion Passenger's internal status ===
-
-One can inspect Phusion Passenger's internal status with the tool `passenger-status`.
-This tool must typically be run as root. For example:
-
---------------------------------------------------
-[bash@localhost root]# passenger-status
------------ General information -----------
-max      = 6
-count    = 1
-active   = 0
-inactive = 1
-
------------ Domains -----------
-/var/www/projects/app1-foobar: 
-  PID: 9617      Sessions: 0    Processed: 7       Uptime: 2m 23s
---------------------------------------------------
-
-The 'general information' section shows the following information:
-
-max:: The maximum number of application instances that Phusion Passenger will
-spawn. This equals the value given for <<PassengerMaxPoolSize,PassengerMaxPoolSize>>.
-count:: The number of application instances that are currently alive. This value
-is always less than or equal to 'max'.
-active:: The number of application instances that are currently processing
-requests. This value is always less than or equal to 'count'.
-inactive:: The number of application instances that are currently *not* processing
-requests, i.e. are idle. Idle application instances will be shutdown after a while,
-as can be specified with <<PassengerPoolIdleTime,PassengerPoolIdleTime>> (unless this
-value is set to 0, in which case application instances are never shut down via idle
-time). The value of 'inactive' equals `count - active`.
-
-The 'domains' section shows, for each application directory, information about running
-application instances:
-
-Sessions:: Shows how many HTTP client are currently in the queue of that application
-Instance, waiting to be processed.
-Processed:: Indicates how many requests the instance has served until now. *Tip:* it's
-possible to limit this number with the <<PassengerMaxRequests,PassengerMaxRequests>>
-configuration directive.
-Uptime:: Shows for how long the application instance has been running.
-
-Since Phusion Passenger uses fair load balancing by default, the number of sessions for the
-application instances should be fairly close to each other. For example, this is fairly
-normal:
---------------------------------
-  PID: 4281      Sessions: 2      Processed: 7      Uptime: 5m 11s
-  PID: 4268      Sessions: 0      Processed: 5      Uptime: 4m 52s
-  PID: 4265      Sessions: 1      Processed: 6      Uptime: 5m 38s
-  PID: 4275      Sessions: 1      Processed: 7      Uptime: 3m 14s
---------------------------------
-
-But if you see a "spike", i.e. an application instance has an unusually high number of
-sessions compared to the others, then there might be a problem:
---------------------------------
-  PID: 4281      Sessions: 2      Processed: 7      Uptime: 5m 11s
-  PID: 17468     Sessions: 8 <-+  Processed: 2      Uptime: 4m 47s
-  PID: 4265      Sessions: 1   |  Processed: 6      Uptime: 5m 38s
-  PID: 4275      Sessions: 1   |  Processed: 7      Uptime: 3m 14s
-                               |
-                               +---- "spike"
---------------------------------
-
-Possible reasons why spikes can occur:
-
-. Your application is busy processing a request that takes a very long time.
-  If this is the case, then you might want to turn
-  <<PassengerUseGlobalQueue,global queuing>> on.
-. Your application is frozen, i.e. has stopped responding. See
-  <<debugging_frozen,Debugging frozen applications>> for tips.
-
-
-[[debugging_frozen]]
-=== Debugging frozen applications ===
-
-If one of your application instances is frozen (stopped responding), then you
-can figure out where it is frozen by killing it with 'SIGABRT'. This will cause the
-application to raise an exception, with a backtrace.
-
-The exception (with full backtrace information) is normally logged into the Apache
-error log. But if your application or if its web framework has its own exception logging
-routines, then exceptions might be logged into the application's log files instead.
-This is the case with Ruby on Rails. So if you kill a Ruby on Rails application with
-'SIGABRT', please check the application's 'production.log' first (assuming that you're
-running it in a 'production' environment). If you don't see a backtrace there, check
-the Apache error log.
-
-NOTE: It is safe to kill application instances, even in live environments. Phusion Passenger
-will restart killed application instances, as if nothing bad happened.
+include::users_guide_snippets/analysis_and_system_maintenance_tools.txt[]
 
 
 == Tips ==
 
-[[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>>.
-
-User switching can be disabled with the
-<<PassengerUserSwitching,PassengerUserSwitching>> 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
---------------------------------------------------
-
-You may notice that after each deploy, a new spawner server is
-created (it'll show up in `passenger-memory-stats`). Indeed, Capistrano will deploy
-to a path ending with '/current' (ie : '/u/apps/yourapp/current'), so that you don't
-have to care about revisions in your virtual host configuration. This '/current' directory
-is a symlink to the current revision deployed ('/path_to_app/releases/date_of_the_release').
-Phusion Passenger recognizes applications by their full canonical path, so after
-deploying a new version, Phusion Passenger will think that the new version is
-a totally different application, thereby creating a new spawner server:
-
---------------------------------------------------
-1001   30291   [...]   Passenger ApplicationSpawner: /u/apps/my_app/releases/20080509104413
-1001   31371   [...]   Passenger ApplicationSpawner: /u/apps/my_app/releases/20080509104632
---------------------------------------------------
-
-Don't worry about this. The (old) spawner server will terminate itself after its
-timeout period (10 minutes by default), so you will not run out of memory.
-
-If you really want to release the spawner server's memory immediately, then you can add a command
-to your Capistrano script to terminate the Passenger spawn server after each deploy. That
-command is as follows:
-
---------------------------------------------------
-kill $( passenger-memory-stats | grep 'Passenger spawn server' | awk '{ print $1 }' )
---------------------------------------------------
-
-Killing the spawn server is completely safe, because Phusion Passenger will restart the
-spawn server if it has been terminated.
-
-
-=== 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.
+include::users_guide_snippets/tips.txt[]
 
 === X-Sendfile support ===
 
@@ -1875,447 +1417,9 @@ Phusion Passenger does not provide upload progress support by itself. Please
 try drogus's link:http://github.com/drogus/apache-upload-progress-module/tree/master[
 Apache upload progress module] instead.
 
-=== 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].
-
-
-== Appendix A: About this document ==
-
-The text of this document is licensed under the
-link:http://creativecommons.org/licenses/by-sa/3.0/[Creative Commons
-Attribution-Share Alike 3.0 Unported License].
-
-image:images/by_sa.png[link="http://creativecommons.org/licenses/by-sa/3.0/"]
-
-Phusion Passenger is brought to you by link:http://www.phusion.nl/[Phusion].
-
-image:images/phusion_banner.png[link="http://www.phusion.nl/"]
-
-Phusion Passenger is a trademark of Hongli Lai & Ninh Bui.
-
-== Appendix B: Terminology ==
-
-[[application_root]]
-=== Application root ===
-The root directory of an application that's served by Phusion Passenger.
-
-In case of Ruby on Rails applications, this is the directory that contains
-'Rakefile', 'app/', 'config/', 'public/', etc. In other words, the directory
-pointed to by `RAILS_ROOT`. For example, take the following directory structure:
-
------------------------------------------
-/apps/foo/       <------ This is the Rails application's application root!
-   |
-   +- app/
-   |   |
-   |   +- controllers/
-   |   |
-   |   +- models/
-   |   |
-   |   +- views/
-   |
-   +- config/
-   |   |
-   |   +- environment.rb
-   |   |
-   |   +- ...
-   |
-   +- public/
-   |   |
-   |   +- ...
-   |
-   +- ...
------------------------------------------
-
-In case of Rack applications, this is the directory that contains 'config.ru'.
-For example, take the following directory structure:
-
------------------------------------------
-/apps/bar/      <----- This is the Rack application's application root!
-   |
-   +- public/
-   |    |
-   |    +- ...
-   |
-   +- config.ru
-   |
-   +- ...
------------------------------------------
-
-In case of Python (WSGI) applications, this is the directory that contains
-'passenger_wsgi.py'. For example, take the following directory structure:
-
------------------------------------------
-/apps/baz/      <----- This is the WSGI application's application root!
-   |
-   +- public/
-   |    |
-   |    +- ...
-   |
-   +- passenger_wsgi.py
-   |
-   +- ...
------------------------------------------
 
+include::users_guide_snippets/appendix_a_about.txt[]
 
-[[spawning_methods_explained]]
-== Appendix C: Spawning methods explained ==
-
-At its core, Phusion Passenger is an HTTP proxy and process manager. It spawns
-Ruby on Rails/Rack/WSGI worker processes (which may also be referred to as
-'backend processes'), and forwards incoming HTTP request to one of the worker
-processes.
-
-While this may sound simple, there's not just one way to spawn worker processes.
-Let's go over the different spawning methods. For simplicity's sake, let's
-assume that we're only talking about Ruby on Rails applications.
-
-=== The most straightforward and traditional way: conservative spawning ===
-
-Phusion Passenger could create a new Ruby process, which will then load the
-Rails application along with the entire Rails framework. This process will then
-enter an request handling main loop.
-
-This is the most straightforward way to spawn worker processes. If you're
-familiar with the Mongrel application server, then this approach is exactly
-what mongrel_cluster performs: it creates N worker processes, each which loads
-a full copy of the Rails application and the Rails framework in memory. The Thin
-application server employs pretty much the same approach.
-
-Note that Phusion Passenger's version of conservative spawning differs slightly
-from mongrel_cluster. Mongrel_cluster creates entirely new Ruby processes. In
-programmers jargon, mongrel_cluster creates new Ruby processes by forking the
-current process and exec()-ing a new Ruby interpreter. Phusion Passenger on the
-other hand creates processes that reuse the already loaded Ruby interpreter. In
-programmers jargon, Phusion Passenger calls fork(), but not exec().
-
-=== The smart spawning method ===
-
-NOTE: Smart spawning is only available for Ruby on Rails applications, not for
-      Rack applications or WSGI applications.
-
-While conservative spawning works well, it's not as efficient as it could be
-because each worker process has its own private copy of the Rails application
-as well as the Rails framework. This wastes memory as well as startup time.
-
-image:images/conservative_spawning.png[Worker processes and conservative spawning] +
-'Figure: Worker processes and conservative spawning. Each worker process has its
-own private copy of the application code and Rails framework code.'
-
-It is possible to make the different worker processes share the memory occupied
-by application and Rails framework code, by utilizing so-called
-copy-on-write semantics of the virtual memory system on modern operating
-systems. As a side effect, the startup time is also reduced. This is technique
-is exploited by Phusion Passenger's 'smart' and 'smart-lv2' spawn methods.
-
-==== How it works ====
-
-When the 'smart-lv2' spawn method is being used, Phusion Passenger will first
-create a so-called 'ApplicationSpawner server' process. This process loads the
-entire Rails application along with the Rails framework, by loading
-'environment.rb'. Then, whenever Phusion Passenger needs a new worker process,
-it will instruct the ApplicationSpawner server to do so. The ApplicationSpawner
-server will create a worker new process
-that reuses the already loaded Rails application/framework. Creating a worker
-process through an already running ApplicationSpawner server is very fast, about
-10 times faster than loading the Rails application/framework from scratch. If
-the Ruby interpreter is copy-on-write friendly (that is, if you're running
-<<reducing_memory_usage,Ruby Enterprise Edition>>) then all created worker
-processes will share as much common
-memory as possible. That is, they will all share the same application and Rails
-framework code.
-
-image:images/smart-lv2.png[] +
-'Figure: Worker processes and the smart-lv2 spawn method. All worker processes,
-as well as the ApplicationSpawner, share the same application code and Rails
-framework code.'
-
-The 'smart' spawn method goes even further, by caching the Rails framework in
-another process called the 'FrameworkSpawner server'. This process only loads
-the Rails framework, not the application. When a FrameworkSpawner server is
-instructed to create a new worker process, it will create a new
-ApplicationSpawner to which the instruction will be delegated. All those
-ApplicationSpawner servers, as well as all worker processes created by those
-ApplicationSpawner servers, will share the same Rails framework code.
-
-The 'smart-lv2' method allows different worker processes that belong to the same
-application to share memory. The 'smart' method allows different worker
-processes - that happen to use the same Rails version - to share memory, even if
-they don't belong to the same application.
-
-Notes:
-
-- Vendored Rails frameworks cannot be shared by different applications, even if
-  both vendored Rails frameworks are the same version. So for efficiency reasons
-  we don't recommend vendoring Rails.
-- ApplicationSpawner and FrameworkSpawner servers have an idle timeout just
-  like worker processes. If an ApplicationSpawner/FrameworkSpawner server hasn't
-  been instructed to do anything for a while, it will be shutdown in order to
-  conserve memory. This idle timeout is configurable.
-
-==== Summary of benefits ====
-
-Suppose that Phusion Passenger needs a new worker process for an application
-that uses Rails 2.2.1.
-
-- If the 'smart-lv2' spawning method is used, and an ApplicationSpawner server
-  for this application is already running, then worker process creation time is
-  about 10 times faster than conservative spawning. This worker process will also
-  share application and Rails framework code memory with the ApplicationSpawner
-  server and the worker processes that had been spawned by this ApplicationSpawner
-  server.
-- If the 'smart' spawning method is used, and a FrameworkSpawner server for
-  Rails 2.2.1 is already running, but no ApplicationSpawner server for this
-  application is running, then worker process creation time is about 2 times
-  faster than conservative spawning. If there is an ApplicationSpawner server
-  for this application running, then worker process creation time is about 10
-  times faster. This worker process will also share application and Rails
-  framework code memory with the ApplicationSpawner and FrameworkSpawner
-  servers.
-
-You could compare ApplicationSpawner and FrameworkSpawner servers with stem
-cells, that have the ability to quickly change into more specific cells (worker
-process).
-
-In practice, the smart spawning methods could mean a memory saving of about 33%,
-assuming that your Ruby interpreter is <<reducing_memory_usage,copy-on-write friendly>>.
-
-Of course, smart spawning is not without gotchas. But if you understand the
-gotchas you can easily reap the benefits of smart spawning.
-
-=== Smart spawning gotcha #1: unintential file descriptor sharing ===
-
-Because worker processes are created by forking from an ApplicationSpawner
-server, it will share all file descriptors that are opened by the
-ApplicationSpawner server. (This is part of the semantics of the Unix
-'fork()' system call. You might want to Google it if you're not familiar with
-it.) A file descriptor is a handle which can be an opened file, an opened socket
-connection, a pipe, etc. If different worker processes write to such a file
-descriptor at the same time, then their write calls will be interleaved, which
-may potentially cause problems.
-
-The problem commonly involves socket connections that are unintentially being
-shared. You can fix it by closing and reestablishing the connection when Phusion
-Passenger is creating a new worker process. Phusion Passenger provides the API
-call `PhusionPassenger.on_event(:starting_worker_process)` to do so. So you
-could insert the following code in your 'environment.rb':
-
-[source, ruby]
------------------------------------------
-if defined?(PhusionPassenger)
-    PhusionPassenger.on_event(:starting_worker_process) do |forked|
-        if forked
-            # We're in smart spawning mode.
-            ... code to reestablish socket connections here ...
-        else
-            # We're in conservative spawning mode. We don't need to do anything.
-        end
-    end
-end
------------------------------------------
-
-Note that Phusion Passenger automatically reestablishes the connection to the
-database upon creating a new worker process, which is why you normally do not
-encounter any database issues when using smart spawning mode.
-
-==== Example 1: Memcached connection sharing (harmful) ====
-
-Suppose we have a Rails application that connects to a Memcached server in
-'environment.rb'. This causes the ApplicationSpawner to have a socket connection
-(file descriptor) to the Memcached server, as shown in the following figure:
-
- +--------------------+
- | ApplicationSpawner |-----------[Memcached server]
- +--------------------+
-
-Phusion Passenger then proceeds with creating a new Rails worker process, which
-is to process incoming HTTP requests. The result will look like this:
-
- +--------------------+
- | ApplicationSpawner |------+----[Memcached server]
- +--------------------+      |
-                             |
- +--------------------+      |
- | Worker process 1   |-----/
- +--------------------+
-
-Since a 'fork()' makes a (virtual) complete copy of a process, all its file
-descriptors will be copied as well. What we see here is that ApplicationSpawner
-and Worker process 1 both share the same connection to Memcached.
-
-Now supposed that your site gets Slashdotted and Phusion Passenger needs to
-spawn another worker process. It does so by forking ApplicationSpawner. The
-result is now as follows:
-
- +--------------------+
- | ApplicationSpawner |------+----[Memcached server]
- +--------------------+      |
-                             |
- +--------------------+      |
- | Worker process 1   |-----/|
- +--------------------+      |
-                             |
- +--------------------+      |
- | Worker process 2   |-----/
- +--------------------+
-
-As you can see, Worker process 1 and Worker process 2 have the same Memcache
-connection.
-
-Suppose that users Joe and Jane visit your website at the same time. Joe's
-request is handled by Worker process 1, and Jane's request is handled by Worker
-process 2. Both worker processes want to fetch something from Memcached. Suppose
-that in order to do that, both handlers need to send a "FETCH" command to Memcached.
-
-But suppose that, after worker process 1 having only sent "FE", a context switch
-occurs, and worker process 2 starts sending a "FETCH" command to Memcached as
-well. If worker process 2 succeeds in sending only one bye, 'F', then Memcached
-will receive a command which begins with "FEF", a command that it does not
-recognize. In other words: the data from both handlers get interleaved. And thus
-Memcached is forced to handle this as an error.
-
-This problem can be solved by reestablishing the connection to Memcached after forking:
-
- +--------------------+
- | ApplicationSpawner |------+----[Memcached server]
- +--------------------+      |                   |
-                             |                   |
- +--------------------+      |                   |
- | Worker process 1   |-----/|                   |
- +--------------------+      |                   |  <--- created this
-                             X                   |       new
-                                                 |       connection
-                             X <-- closed this   |
- +--------------------+      |     old           |
- | Worker process 2   |-----/      connection    |
- +--------------------+                          |
-           |                                     |
-           +-------------------------------------+
-
-Worker process 2 now has its own, separate communication channel with Memcached.
-The code in 'environment.rb' looks like this:
-
-[source, ruby]
------------------------------------------
-if defined?(PhusionPassenger)
-    PhusionPassenger.on_event(:starting_worker_process) do |forked|
-        if forked
-            # We're in smart spawning mode.
-            reestablish_connection_to_memcached
-        else
-            # We're in conservative spawning mode. We don't need to do anything.
-        end
-    end
-end
------------------------------------------
-
-==== Example 2: Log file sharing (not harmful) ====
-
-There are also cases in which unintential file descriptor sharing is not harmful.
-One such case is log file file descriptor sharing. Even if two processes write
-to the log file at the same time, the worst thing that can happen is that the
-data in the log file is interleaved.
-
-To guarantee that the data written to the log file is never interleaved, you
-must synchronize write access via an inter-process synchronization mechanism,
-such as file locks. Reopening the log file, like you would have done in the
-Memcached example, doesn't help.
-
-=== Smart spawning gotcha #2: the need to revive threads ===
-
-Another part of the 'fork()' system call's semantics is the fact that threads
-disappear after a fork call. So if you've created any threads in environment.rb,
-then those threads will no longer be running in newly created worker process.
-You need to revive them when a new worker process is created. Use the
-`:starting_worker_process` event that Phusion Passenger provides, like this:
-
-[source, ruby]
------------------------------------------
-if defined?(PhusionPassenger)
-    PhusionPassenger.on_event(:starting_worker_process) do |forked|
-        if forked
-            # We're in smart spawning mode.
-            ... code to revive threads here ...
-        else
-            # We're in conservative spawning mode. We don't need to do anything.
-        end
-    end
-end
------------------------------------------
+include::users_guide_snippets/appendix_b_terminology.txt[]
 
-=== Smart spawning gotcha #3: code load order ===
-
-This gotcha is only applicable to the 'smart' spawn method, not the 'smart-lv2'
-spawn method.
-
-If your application expects the Rails framework to be not loaded during the
-beginning of 'environment.rb', then it can cause problems when an
-ApplicationSpawner is created from a FrameworkSpawner, which already has the
-Rails framework loaded. The most common case is when applications try to patch
-Rails by dropping a modified file that has the same name as Rails's own file,
-in a path that comes earlier in the Ruby search path.
-
-For example, suppose that we have an application which has a patched version
-of 'active_record/base.rb' located in 'RAILS_ROOT/lib/patches', and
-'RAILS_ROOT/lib/patches' comes first in the Ruby load path. When conservative
-spawning is used, the patched version of 'base.rb' is properly loaded. When
-'smart' (not 'smart-lv2') spawning is used, the original 'base.rb' is used
-because it was already loaded, so a subsequent `require "active_record/base"`
-has no effect.
+include::users_guide_snippets/appendix_c_spawning_methods.txt[]