passenger 1.0.1 → 1.0.2

data/doc/Users guide.html

@@ -422,9 +422,8 @@ How to solve common problems.
 using the commandline.</p></div>
 </div>
 </div>
-<h2 id="_installation">1. Installation</h2>
+<h2 id="_supported_operating_systems">1. Supported operating systems</h2>
 <div class="sectionbody">
-<h3 id="_supported_operating_systems">1.1. Supported operating systems</h3><div style="clear:left"></div>
 <div class="para"><p>Passenger works on any POSIX-compliant operating system. In other words:
 practically any operating system on earth, except Microsoft Windows.</p></div>
 <div class="para"><p>Passenger has been tested on:</p></div>
@@ -491,7 +490,11 @@ fine on them. Please
 or
 <a href="http://groups.google.com/group/phusion-passenger">join our discussion list</a>
 if it doesn't.</p></div>
-<h3 id="install_passenger">1.2. Overview of download and installation methods</h3><div style="clear:left"></div>
+</div>
+<h2 id="_installing_passenger">2. Installing Passenger</h2>
+<div class="sectionbody">
+<h3 id="_generic_installation_instructions">2.1. Generic installation instructions</h3><div style="clear:left"></div>
+<h4 id="install_passenger">2.1.1. Overview of download and installation methods</h4>
 <div class="para"><p>There are two ways to install Passenger:</p></div>
 <div class="olist"><ol>
 <li>
@@ -520,7 +523,7 @@ as <em>root</em>. If the installer fails because of permission errors, it will t
 you.</td>
 </tr></table>
 </div>
-<h3 id="specifying_correct_apache_install">1.3. Specifying the correct Apache installation</h3><div style="clear:left"></div>
+<h4 id="specifying_correct_apache_install">2.1.2. Specifying the correct Apache installation</h4>
 <div class="para"><p>If your system has multiple Apache installations (this is likely the case on
 MacOS X), then you will need to tell the Passenger installer which one to use.
 If you only have one Apache installation (the case on most Linux systems), then
@@ -543,7 +546,7 @@ variable. Suppose that you want to use the Apache installation in
 be located in the <tt>sbin</tt> folder instead of the <tt>bin</tt> folder.</td>
 </tr></table>
 </div>
-<h3 id="specifying_ruby_installation">1.4. Specifying the correct Ruby installation</h3><div style="clear:left"></div>
+<h4 id="specifying_ruby_installation">2.1.3. Specifying the correct Ruby installation</h4>
 <div class="para"><p>If your system has multiple Ruby installations (this is likely the case on
 MacOS X), then you will need to tell the Passenger installer which one to use.
 If you only have one Ruby installation (the case on most Linux systems), then
@@ -568,7 +571,7 @@ following Ruby installations:</p></div>
 <div class="content">
 <pre><tt>export PATH=/opt/myruby/bin:$PATH</tt></pre>
 </div></div>
-<h3 id="_installing_via_the_gem">1.5. Installing via the gem</h3><div style="clear:left"></div>
+<h4 id="_installing_via_the_gem">2.1.4. Installing via the gem</h4>
 <div class="para"><p>Please install the gem and then run the Passenger installer, by typing the
 following commands:</p></div>
 <div class="listingblock">
@@ -577,7 +580,7 @@ following commands:</p></div>
 passenger-install-apache2-module</tt></pre>
 </div></div>
 <div class="para"><p>Please follow the instructions given by the installer.</p></div>
-<h3 id="_installing_via_the_source_tarball">1.6. Installing via the source tarball</h3><div style="clear:left"></div>
+<h4 id="_installing_via_the_source_tarball">2.1.5. Installing via the source tarball</h4>
 <div class="para"><p>Extract the tarball to whatever location you prefer. The Passenger files
 are to reside in that location permanently. For example, if you would like
 Passenger to reside in <tt>/opt/passenger-x.x.x</tt>:</p></div>
@@ -601,8 +604,15 @@ tar xzvf ~/YourDownloadsFolder/passenger-x.x.x.tar.gz</tt></pre>
 installation. Furthermore, the <em>passenger-x.x.x</em> folder must be accessible by Apache.</td>
 </tr></table>
 </div>
+<h3 id="_operating_system_specific_instructions_and_information">2.2. Operating system-specific instructions and information</h3><div style="clear:left"></div>
+<h4 id="_macos_x">2.2.1. MacOS X</h4>
+<div class="para"><p>Ben Ruebenstein has written an excellent
+<a href="http://benr75.com/articles/2008/04/12/setup-mod_rails-phusion-mac-os-x-leopard">tutorial
+on installing Phusion Passenger on OS X</a>.</p></div>
+<h4 id="_ubuntu_linux">2.2.2. Ubuntu Linux</h4>
+<div class="para"><p>Ben Hughes has written an <a href="http://www.railsgarden.com/2008/04/12/configurating-passenger-mod_rails-on-slicehost-with-ubuntu-710/">article on installing Passenger on Ubuntu</a>.</p></div>
 </div>
-<h2 id="_deploying_a_ruby_on_rails_application">2. Deploying a Ruby on Rails application</h2>
+<h2 id="_deploying_a_ruby_on_rails_application">3. Deploying a Ruby on Rails application</h2>
 <div class="sectionbody">
 <div class="para"><p>Suppose you have a Ruby on Rails application in <em>/webapps/mycook</em>, and you own
 the domain <em>www.mycook.com</em>. You can either deploy your application in the
@@ -619,7 +629,7 @@ are run, is &#8220;production&#8221;. You can change this by changing the
 <a href="#rails_env"><em>RailsEnv</em></a> configuration option.</td>
 </tr></table>
 </div>
-<h3 id="_deploying_to_a_virtual_host_s_root">2.1. Deploying to a virtual host's root</h3><div style="clear:left"></div>
+<h3 id="_deploying_to_a_virtual_host_s_root">3.1. Deploying to a virtual host's root</h3><div style="clear:left"></div>
 <div class="para"><p>Add a virtual host entry to your Apache configuration file. The virtual host's
 document root must point to your Ruby on Rails application's <em>public</em> folder.
 For example:</p></div>
@@ -631,7 +641,7 @@ For example:</p></div>
 &lt;/VirtualHost&gt;</tt></pre>
 </div></div>
 <div class="para"><p>Then restart Apache. The application has now been deployed.</p></div>
-<h3 id="deploying_to_sub_uri">2.2. Deploying to a sub URI</h3><div style="clear:left"></div>
+<h3 id="deploying_to_sub_uri">3.2. Deploying to a sub URI</h3><div style="clear:left"></div>
 <div class="para"><p>Suppose that you already have a virtual host:</p></div>
 <div class="listingblock">
 <div class="content">
@@ -658,7 +668,7 @@ folder to a directory in the document root. For example:</p></div>
 &lt;/VirtualHost&gt;</tt></pre>
 </div></div>
 <div class="para"><p>Then restart Apache. The application has now been deployed.</p></div>
-<h3 id="_redeploying_restarting_the_ruby_on_rails_application">2.3. Redeploying (restarting the Ruby on Rails application)</h3><div style="clear:left"></div>
+<h3 id="_redeploying_restarting_the_ruby_on_rails_application">3.3. Redeploying (restarting the Ruby on Rails application)</h3><div style="clear:left"></div>
 <div class="para"><p>Deploying a new version of a Ruby on Rails application is as simple as
 re-uploading the application files, and restarting the application.</p></div>
 <div class="para"><p>There are two ways to restart the application:</p></div>
@@ -683,7 +693,7 @@ command line:</p></div>
 <pre><tt>touch /webapps/mycook/tmp/restart.txt</tt></pre>
 </div></div>
 </div>
-<h2 id="_configuring_passenger">3. Configuring Passenger</h2>
+<h2 id="_configuring_passenger">4. Configuring Passenger</h2>
 <div class="sectionbody">
 <div class="para"><p>After installation, Passenger does not need any further configurations.
 Nevertheless, the system administrator may be interested in changing
@@ -874,10 +884,27 @@ The default value is <em>nobody</em>.</p></div>
 </dd>
 </dl></div>
 </div>
-<h2 id="_troubleshooting">4. Troubleshooting</h2>
+<h2 id="_troubleshooting">5. Troubleshooting</h2>
 <div class="sectionbody">
-<h3 id="_problems_during_installation">4.1. Problems during installation</h3><div style="clear:left"></div>
-<h4 id="installing_ruby_dev">4.1.1. Ruby development headers aren't installed</h4>
+<h3 id="_operating_system_specific_problems">5.1. Operating system-specific problems</h3><div style="clear:left"></div>
+<h4 id="_macos_x_the_installer_cannot_locate_mamp_s_apache">5.1.1. MacOS X: The installer cannot locate MAMP's Apache</h4>
+<div class="sidebarblock">
+<div class="sidebar-content">
+<div class="sidebar-title">Symptoms</div>
+<div class="para"><p>The installer finds Apache 2 development headers at <tt>/Applications/MAMP/Library/bin/apxs</tt>.
+However, Apache cannot be found. The installer also outputs the following error:</p></div>
+<div class="listingblock">
+<div class="content">
+<pre><tt>cannot open /Applications/MAMP/Library/build/config_vars.mk:
+No such file or directory at /Applications/MAMP/Library/bin/apxs line 218.</tt></pre>
+</div></div>
+</div></div>
+<div class="para"><p>Your MAMP installation seems to be broken. In particular, <em>config_vars.mk</em> is missing.
+Please read <a href="http://forum.mamp.info/viewtopic.php?t=1866">this forum topic</a> to learn how
+to fix this problem.</p></div>
+<div class="para"><p>See also <a href="http://code.google.com/p/phusion-passenger/issues/detail?id=12">this bug report</a>.</p></div>
+<h3 id="_problems_during_installation">5.2. Problems during installation</h3><div style="clear:left"></div>
+<h4 id="installing_ruby_dev">5.2.1. Ruby development headers aren't installed</h4>
 <div class="sidebarblock">
 <div class="sidebar-content">
 <div class="sidebar-title">Symptoms</div>
@@ -970,7 +997,7 @@ installation you want to use. Please read
 <a href="#specifying_ruby_installation">Specifying the correct Ruby installation</a>.</td>
 </tr></table>
 </div>
-<h4 id="_apache_development_headers_aren_t_installed">4.1.2. Apache development headers aren't installed</h4>
+<h4 id="_apache_development_headers_aren_t_installed">5.2.2. Apache development headers aren't installed</h4>
 <div class="sidebarblock">
 <div class="sidebar-content">
 <div class="sidebar-title">Symptoms</div>
@@ -1055,7 +1082,7 @@ Other operating systems
 </p>
 </dd>
 </dl></div>
-<h4 id="_apr_development_headers_aren_t_installed">4.1.3. APR development headers aren't installed</h4>
+<h4 id="_apr_development_headers_aren_t_installed">5.2.3. APR development headers aren't installed</h4>
 <div class="sidebarblock">
 <div class="sidebar-content">
 <div class="sidebar-title">Symptoms</div>
@@ -1135,11 +1162,11 @@ Other operating systems
 </p>
 </dd>
 </dl></div>
-<h4 id="_passenger_is_using_the_wrong_apache_during_installation">4.1.4. Passenger is using the wrong Apache during installation</h4>
+<h4 id="_passenger_is_using_the_wrong_apache_during_installation">5.2.4. Passenger is using the wrong Apache during installation</h4>
 <div class="para"><p>Please <a href="#specifying_correct_apache_install">Specifying the correct Apache installation</a>, and re-run the Passenger installer.</p></div>
-<h4 id="_passenger_is_using_the_wrong_ruby_during_installation">4.1.5. Passenger is using the wrong Ruby during installation</h4>
+<h4 id="_passenger_is_using_the_wrong_ruby_during_installation">5.2.5. Passenger is using the wrong Ruby during installation</h4>
 <div class="para"><p>Please <a href="#specifying_ruby_installation">Specifying the correct Ruby installation</a>, and re-run the Passenger installer.</p></div>
-<h3 id="_problems_after_installation">4.2. Problems after installation</h3><div style="clear:left"></div>
+<h3 id="_problems_after_installation">5.3. Problems after installation</h3><div style="clear:left"></div>
 <div class="admonitionblock">
 <table><tr>
 <td class="icon">
@@ -1153,7 +1180,7 @@ inside the Apache error logs. It will tell you what exactly went wrong.</p></div
 </td>
 </tr></table>
 </div>
-<h4 id="_passenger_has_been_compiled_against_the_wrong_apache_installation">4.2.1. Passenger has been compiled against the wrong Apache installation</h4>
+<h4 id="_passenger_has_been_compiled_against_the_wrong_apache_installation">5.3.1. Passenger has been compiled against the wrong Apache installation</h4>
 <div class="sidebarblock">
 <div class="sidebar-content">
 <div class="sidebar-title">Symptoms</div>
@@ -1163,7 +1190,39 @@ says &#8220;<em>seg fault or similar nasty error detected in the parent process&
 <div class="para"><p>This problem is most likely to occur on MacOS X. Most OS X users have multiple
 Apache installations on their system.</p></div>
 <div class="para"><p>To solve this problem, please <a href="#specifying_correct_apache_install">specify the correct Apache installation</a>, and <a href="#install_passenger">reinstall Passenger</a>.</p></div>
-<h4 id="_the_apache_error_log_says_that_the_spawn_manager_script_does_not_exist_or_that_it_does_not_have_permission_to_execute_it">4.2.2. The Apache error log says that the spawn manager script does not exist, or that it does not have permission to execute it</h4>
+<h4 id="_i_get_a_304_forbidden_error">5.3.2. I get a "304 Forbidden" error</h4>
+<div class="para"><p>See next subsection.</p></div>
+<h4 id="_static_assets_such_as_images_and_stylesheets_aren_t_being_displayed">5.3.3. Static assets such as images and stylesheets aren't being displayed</h4>
+<div class="para"><p>Static assets are accelerated, i.e. they are served directly by Apache and do not
+go through the Rails stack. There are two reasons why Apache doesn't serve static
+assets correctly:</p></div>
+<div class="olist"><ol>
+<li>
+<p>
+Your Apache configuration is too strict, and does not allow HTTP clients to
+   access static assets. This can be achieved with an <tt>Allow from all</tt> directive
+   in the correct place. For example:
+</p>
+<div class="listingblock">
+<div class="content">
+<pre><tt>&lt;Directory "/webapps/mycook/public"&gt;
+   Options FollowSymLinks
+   AllowOverride None
+   Order allow,deny
+   Allow from all
+&lt;/Directory&gt;</tt></pre>
+</div></div>
+<div class="para"><p>See also <a href="http://groups.google.com/group/phusion-passenger/browse_thread/thread/9699a639a87f85f4/b9d71a03bf2670a5">this discussion</a>.</p></div>
+</li>
+<li>
+<p>
+The Apache process doesn't have permission to access your Rails application's folder.
+   Please make sure that the Rails application's folder, as well as all of its parent folders,
+   have the correct permissions and/or ownerships.
+</p>
+</li>
+</ol></div>
+<h4 id="_the_apache_error_log_says_that_the_spawn_manager_script_does_not_exist_or_that_it_does_not_have_permission_to_execute_it">5.3.4. The Apache error log says that the spawn manager script does not exist, or that it does not have permission to execute it</h4>
 <div class="para"><p>If you are sure that the RailsSpawnServer configuration option is set correctly,
 then this problem is most likely caused by the fact that you're running Apache
 with SELinux. On Fedora, CentOS and RedHat Enterprise Linux, Apache is locked
@@ -1173,26 +1232,20 @@ folders, so that Apache can access them.</p></div>
 <div class="ilist"><ul>
 <li>
 <p>
-If you've installed Passenger via a gem, then you must first find out the
-  location in which RubyGems stores gem files. Type the following command:
+If you've installed Passenger via a gem, then run this command to determine
+  Passenger's root folder:
 </p>
 <div class="listingblock">
 <div class="content">
-<pre><tt>gem environment | grep 'INSTALLATION DIRECTORY'</tt></pre>
-</div></div>
-<div class="para"><p>It should show something along the lines of:</p></div>
-<div class="listingblock">
-<div class="content">
-<pre><tt>  - INSTALLATION DIRECTORY: /usr/lib/ruby/gems/1.8</tt></pre>
+<pre><tt>passenger-config --root</tt></pre>
 </div></div>
-<div class="para"><p>The directory name that you see in the output is the RubyGems gem folder.
-Next, we'll fix the Passenger folder permissions as follows:</p></div>
+<div class="para"><p>Next, run the following command:</p></div>
 <div class="listingblock">
 <div class="content">
-<pre><tt>cd /usr/lib/ruby/gems/1.8     # Replace this with whatever your gem folder is.
-cd gems
-chcon -R -h -t httpd_sys_content_t passenger-*</tt></pre>
+<pre><tt>chcon -R -h -t httpd_sys_content_t /path-to-passenger-root</tt></pre>
 </div></div>
+<div class="para"><p>where <em>/path-to-passenger-root</em> should be replaced with whatever
+<tt>passenger-config &#8212;root</tt> printed.</p></div>
 </li>
 <li>
 <p>
@@ -1206,7 +1259,7 @@ If you've installed Passenger via the source tarball, then run the following
 </li>
 </ul></div>
 <div class="para"><p>Once the permissions are fixed, restart Apache.</p></div>
-<h3 id="_the_rails_application_reports_that_it_s_unable_to_start_because_of_a_permission_error">4.3. The Rails application reports that it's unable to start because of a permission error</h3><div style="clear:left"></div>
+<h4 id="_the_rails_application_reports_that_it_s_unable_to_start_because_of_a_permission_error">5.3.5. The Rails application reports that it's unable to start because of a permission error</h4>
 <div class="para"><p>Please check whether your Rails application's folder has the correct
 permissions. By default, Rails applications are started as the owner of the
 file <em>config/environment.rb</em>, except if the file is owned by root. If the
@@ -1214,10 +1267,63 @@ file is owned by root, then the Rails application will be started as <em>nobody<
 (or as the user specify by <a href="#RailsDefaultUser">RailsDefaultUser</a>, if that's
 specified).</p></div>
 <div class="para"><p>Please read <a href="#user_switching">User switching (security)</a> for details.</p></div>
+<h4 id="_my_rails_application_s_log_file_is_not_being_written_to">5.3.6. My Rails application's log file is not being written to</h4>
+<div class="para"><p>There are a couple things that you should be aware of:</p></div>
+<div class="ilist"><ul>
+<li>
+<p>
+By default, Passenger runs Rails applications in <em>production</em> mode, so please
+  be sure to check <em>production.log</em> instead of <em>development.log</em>. See
+  <a href="#RailsEnv">RailsEnv</a> for configuration.
+</p>
+</li>
+<li>
+<p>
+By default, Passenger runs Rails applications as the owner of <em>environment.rb</em>.
+  So the log file can only be written to if that user has write permission to the
+  log file. Please <em>chmod</em> or <em>chown</em> your log file accordingly.
+</p>
+<div class="para"><p>See <a href="#User_switching">User switching (security)</a> for details.</p></div>
+</li>
+</ul></div>
+<div class="para"><p>If you're using a RedHat-derived Linux distribution (such as Fedora or CentOS)
+then it is <a href="http://code.google.com/p/phusion-passenger/issues/detail?id=4">possible
+that SELinux is interfering</a>. RedHat's SELinux policy only allows Apache to read/write
+directories that have the <em>httpd_sys_content_t</em> security context. Please run the
+following command to give your Rails application folder that context:</p></div>
+<div class="listingblock">
+<div class="content">
+<pre><tt>chcon -R -h -t httpd_sys_content_t /path/to/your/rails/app</tt></pre>
+</div></div>
+<h3 id="conflicting_apache_modules">5.4. Conflicting Apache modules</h3><div style="clear:left"></div>
+<h4 id="_mod_rewrite_and_mod_alias">5.4.1. mod_rewrite and mod_alias</h4>
+<div class="para"><p>Passenger conflicts with <em>mod_rewrite</em> and <em>mod_alias</em>. Those modules may be
+installed and loaded together with <em>mod_passenger</em>, and they will work fine
+outside virtual hosts that contain a Rails application, but we recommend you
+not to use their features inside virtual hosts that contain a Rails
+application.</p></div>
+<div class="para"><p>By default, Passenger will override mod_rewrite rules on Rails hosts. This is
+because the default .htaccess, as provided by Ruby on Rails, redirects all
+requests to `dispatch.cgi' using mod_rewrite. This is a CGI application which
+loads the entire Ruby on Rails framework for every request, and thus is very
+slow. If we do not override mod_rewrite, then Ruby on Rails apps will be slow
+on Passenger by default &#8212; but we want a good out-of-the-box experience.</p></div>
+<div class="para"><p>Furthermore, the primary reason why people use mod_rewrite with Rails
+applications, is to accelerate page caching. Passenger supports page caching
+out-of-the-box, without mod_rewrite.</p></div>
+<div class="para"><p>It is not fully understood how mod_alias conflicts with Passenger, but we
+recommend you not to use it on Rails virtual hosts. mod_alias rules can result
+in surprising problems.</p></div>
+<div class="para"><p>If you really want to use mod_rewrite on Rails virtual hosts, then please set
+the <a href="#RailsAllowModRewrite">RailsAllowModRewrite</a> configuration option. But
+please note that you will have to delete Rails applications' default .htaccess
+file, or add rewrite rules to negate its effects.</p></div>
+<h4 id="_mod_userdir">5.4.2. mod_userdir</h4>
+<div class="para"><p><em>mod_userdir</em> is not compatible with Phusion Passenger at the moment.</p></div>
 </div>
-<h2 id="_tips_and_notes">5. Tips and notes</h2>
+<h2 id="_tips_and_notes">6. Tips and notes</h2>
 <div class="sectionbody">
-<h3 id="user_switching">5.1. User switching (security)</h3><div style="clear:left"></div>
+<h3 id="user_switching">6.1. User switching (security)</h3><div style="clear:left"></div>
 <div class="para"><p>There is a problem that plagues most PHP web host, 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
@@ -1252,11 +1358,11 @@ Under no circumstances will Rails applications be run as <em>root</em>. If
 </ul></div>
 <div class="para"><p>User switching can be disabled with the
 <a href="#RailsUserSwitching">RailsUserSwitching</a> option.</p></div>
-<h3 id="reducing_memory_usage">5.2. Reducing memory consumption of Ruby on Rails apps by 33%</h3><div style="clear:left"></div>
+<h3 id="reducing_memory_usage">6.2. Reducing memory consumption of Ruby on Rails apps by 33%</h3><div style="clear:left"></div>
 <div class="para"><p>Is it possible to reduce memory consumption of your Rails apps by 33% on average,
 by using <a href="http://www.rubyenterpriseedition.com/">Ruby Enterprise Edition</a>.
 Please visit the website for details.</p></div>
-<h3 id="_moving_passenger_to_a_different_directory">5.3. Moving Passenger to a different directory</h3><div style="clear:left"></div>
+<h3 id="_moving_passenger_to_a_different_directory">6.3. Moving Passenger to a different directory</h3><div style="clear:left"></div>
 <div class="para"><p>It is possible to relocate the Passenger files to a different directory. It
 involves two steps:</p></div>
 <div class="olist"><ol>
@@ -1293,7 +1399,7 @@ Edit your Apache configuration file, and set:
 </div></div>
 </li>
 </ol></div>
-<h3 id="_installing_multiple_ruby_on_rails_versions">5.4. Installing multiple Ruby on Rails versions</h3><div style="clear:left"></div>
+<h3 id="_installing_multiple_ruby_on_rails_versions">6.4. Installing multiple Ruby on Rails versions</h3><div style="clear:left"></div>
 <div class="para"><p>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:</p></div>
@@ -1304,33 +1410,11 @@ this command:</p></div>
 <div class="para"><p>where <em>X.X.X</em> is the version number of Ruby on Rails.</p></div>
 <div class="para"><p>All of these versions will exist in parallel, and will not conflict with each
 other. Passenger will automatically make use of the correct version.</p></div>
-<h3 id="_x_sendfile_support">5.5. X-Sendfile support</h3><div style="clear:left"></div>
+<h3 id="_x_sendfile_support">6.5. X-Sendfile support</h3><div style="clear:left"></div>
 <div class="para"><p>Passenger does not provide X-Sendfile support by itself. Please install
 <a href="http://tn123.ath.cx/mod_xsendfile/">mod_xsendfile</a> for X-Sendfile support.</p></div>
-<h3 id="conflicting_apache_modules">5.6. Conflicting Apache modules</h3><div style="clear:left"></div>
-<div class="para"><p>Passenger conflicts with <em>mod_rewrite</em> and <em>mod_alias</em>. Those modules may be
-installed and loaded together with <em>mod_passenger</em>, and they will work fine
-outside virtual hosts that contain a Rails application, but we recommend you
-not to use their features inside virtual hosts that contain a Rails
-application.</p></div>
-<div class="para"><p>By default, Passenger will override mod_rewrite rules on Rails hosts. This is
-because the default .htaccess, as provided by Ruby on Rails, redirects all
-requests to `dispatch.cgi' using mod_rewrite. This is a CGI application which
-loads the entire Ruby on Rails framework for every request, and thus is very
-slow. If we do not override mod_rewrite, then Ruby on Rails apps will be slow
-on Passenger by default &#8212; but we want a good out-of-the-box experience.</p></div>
-<div class="para"><p>Furthermore, the primary reason why people use mod_rewrite with Rails
-applications, is to accelerate page caching. Passenger supports page caching
-out-of-the-box, without mod_rewrite.</p></div>
-<div class="para"><p>It is not fully understood how mod_alias conflicts with Passenger, but we
-recommend you not to use it on Rails virtual hosts. mod_alias rules can result
-in surprising problems.</p></div>
-<div class="para"><p>If you really want to use mod_rewrite on Rails virtual hosts, then please set
-the <a href="#RailsAllowModRewrite">RailsAllowModRewrite</a> configuration option. But
-please note that you will have to delete Rails applications' default .htaccess
-file, or add rewrite rules to negate its effects.</p></div>
 </div>
-<h2 id="_appendix_a_about_this_document">6. Appendix A: About this document</h2>
+<h2 id="_appendix_a_about_this_document">7. Appendix A: About this document</h2>
 <div class="sectionbody">
 <div class="para"><p>The text of this document is licensed under the
 <a href="http://creativecommons.org/licenses/by-sa/3.0/">Creative Commons
@@ -1349,7 +1433,7 @@ Attribution-Share Alike 3.0 Unported License</a>.</p></div>
 </div>
 <div id="footer">
 <div id="footer-text">
-Last updated 2008-04-10 21:31:28 CEST
+Last updated 2008-04-29 15:25:34 CEST
 </div>
 </div>
 </body>

data/doc/Users guide.txt

@@ -17,9 +17,7 @@ This guide assumes that the reader is somewhat familiar with Apache and with
 using the commandline.
 
 
-== Installation ==
-
-=== Supported operating systems ===
+== Supported operating systems ==
 
 Passenger works on any POSIX-compliant operating system. In other words:
 practically any operating system on earth, except Microsoft Windows.
@@ -45,8 +43,13 @@ or
 link:http://groups.google.com/group/phusion-passenger[join our discussion list]
 if it doesn't.
 
+
+== Installing Passenger ==
+
+=== Generic installation instructions ===
+
 [[install_passenger]]
-=== Overview of download and installation methods ===
+==== Overview of download and installation methods ====
 
 There are two ways to install Passenger:
 
@@ -65,7 +68,7 @@ as 'root'. If the installer fails because of permission errors, it will tell
 you.
 
 [[specifying_correct_apache_install]]
-=== Specifying the correct Apache installation ===
+==== Specifying the correct Apache installation ====
 
 If your system has multiple Apache installations (this is likely the case on
 MacOS X), then you will need to tell the Passenger installer which one to use.
@@ -85,7 +88,7 @@ NOTE: On some systems, the `apxs` program might be called `apxs2`, and it might
 be located in the `sbin` folder instead of the `bin` folder.
 
 [[specifying_ruby_installation]]
-=== Specifying the correct Ruby installation ===
+==== Specifying the correct Ruby installation ====
 
 If your system has multiple Ruby installations (this is likely the case on
 MacOS X), then you will need to tell the Passenger installer which one to use.
@@ -106,7 +109,7 @@ export PATH=/opt/myruby/bin:$PATH
 ----------------------------------
 
 
-=== Installing via the gem ===
+==== Installing via the gem ====
 
 Please install the gem and then run the Passenger installer, by typing the
 following commands:
@@ -116,7 +119,7 @@ passenger-install-apache2-module
 ------------------------------------------------------
 Please follow the instructions given by the installer.
 
-=== Installing via the source tarball ===
+==== Installing via the source tarball ====
 
 Extract the tarball to whatever location you prefer. The Passenger files
 are to reside in that location permanently. For example, if you would like
@@ -136,6 +139,19 @@ IMPORTANT: Please do not remove the 'passenger-x.x.x' folder after
 installation. Furthermore, the 'passenger-x.x.x' folder must be accessible by Apache.
 
 
+=== Operating system-specific instructions and information ===
+
+==== MacOS X ====
+
+Ben Ruebenstein has written an excellent
+link:http://benr75.com/articles/2008/04/12/setup-mod_rails-phusion-mac-os-x-leopard[tutorial
+on installing Phusion Passenger on OS X].
+
+==== Ubuntu Linux ====
+
+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 Passenger on Ubuntu].
+
+
 == Deploying a Ruby on Rails application ==
 
 Suppose you have a Ruby on Rails application in '/webapps/mycook', and you own
@@ -355,6 +371,27 @@ The default value is 'nobody'.
 
 == Troubleshooting ==
 
+=== Operating system-specific problems ===
+
+==== MacOS X: The installer cannot locate MAMP's Apache ====
+
+.Symptoms
+*******************************************************************************
+The installer finds Apache 2 development headers at `/Applications/MAMP/Library/bin/apxs`.
+However, Apache cannot be found. The installer also outputs the following error:
+------------------------------------
+cannot open /Applications/MAMP/Library/build/config_vars.mk:
+No such file or directory at /Applications/MAMP/Library/bin/apxs line 218.
+------------------------------------
+*******************************************************************************
+
+Your MAMP installation seems to be broken. In particular, 'config_vars.mk' is missing.
+Please read link:http://forum.mamp.info/viewtopic.php?t=1866[this forum topic] to learn how
+to fix this problem.
+
+See also link:http://code.google.com/p/phusion-passenger/issues/detail?id=12[this bug report].
+
+
 === Problems during installation ===
 
 [[installing_ruby_dev]]
@@ -533,6 +570,35 @@ Apache installations on their system.
 To solve this problem, please <<specifying_correct_apache_install,specify the
 correct Apache installation>>, and <<install_passenger,reinstall Passenger>>.
 
+==== I get a "304 Forbidden" error ====
+
+See next subsection.
+
+==== Static assets such as images and stylesheets aren't being displayed ====
+
+Static assets are accelerated, i.e. they are served directly by Apache and do not
+go through the Rails stack. There are two reasons why Apache doesn't serve static
+assets correctly:
+
+1. Your Apache configuration is too strict, and does not allow HTTP clients to
+   access static assets. This can be achieved with an `Allow from all` directive
+   in the correct place. For example:
++
+-----------------------------------------
+<Directory "/webapps/mycook/public">
+   Options FollowSymLinks
+   AllowOverride None
+   Order allow,deny
+   Allow from all
+</Directory>
+-----------------------------------------
++
+See also link:http://groups.google.com/group/phusion-passenger/browse_thread/thread/9699a639a87f85f4/b9d71a03bf2670a5[this discussion].
+
+2. The Apache process doesn't have permission to access your Rails application's folder.
+   Please make sure that the Rails application's folder, as well as all of its parent folders,
+   have the correct permissions and/or ownerships.
+
 ==== The Apache error log says that the spawn manager script does not exist, or that it does not have permission to execute it ====
 
 If you are sure that the RailsSpawnServer configuration option is set correctly,
@@ -543,27 +609,22 @@ down by SELinux policies.
 To solve this problem, you must set some permissions on the Passenger files and
 folders, so that Apache can access them.
 
-- If you've installed Passenger via a gem, then you must first find out the
-  location in which RubyGems stores gem files. Type the following command:
+- If you've installed Passenger via a gem, then run this command to determine
+  Passenger's root folder:
 +
 ------------------------------------------------------------------
-gem environment | grep 'INSTALLATION DIRECTORY'
+passenger-config --root
 ------------------------------------------------------------------
 +
-It should show something along the lines of:
+Next, run the following command:
 +
 ------------------------------------------------------------------
-  - INSTALLATION DIRECTORY: /usr/lib/ruby/gems/1.8
+chcon -R -h -t httpd_sys_content_t /path-to-passenger-root
 ------------------------------------------------------------------
 +
-The directory name that you see in the output is the RubyGems gem folder.
-Next, we'll fix the Passenger folder permissions as follows:
-+
-------------------------------------------------------------------
-cd /usr/lib/ruby/gems/1.8     # Replace this with whatever your gem folder is.
-cd gems
-chcon -R -h -t httpd_sys_content_t passenger-*
-------------------------------------------------------------------
+where '/path-to-passenger-root' should be replaced with whatever
+`passenger-config --root` printed.
+
 - If you've installed Passenger via the source tarball, then run the following
   command:
 +
@@ -573,7 +634,7 @@ chcon -R -h -t httpd_sys_content_t /path/to/passenger/folder
 
 Once the permissions are fixed, restart Apache.
 
-=== The Rails application reports that it's unable to start because of a permission error ===
+==== The Rails application reports that it's unable to start because of a permission error ====
 
 Please check whether your Rails application's folder has the correct
 permissions. By default, Rails applications are started as the owner of the
@@ -584,6 +645,64 @@ specified).
 
 Please read <<user_switching,User switching (security)>> for details.
 
+==== My Rails application's log file is not being written to ====
+
+There are a couple things that you should be aware of:
+
+- By default, Passenger runs Rails applications in 'production' mode, so please
+  be sure to check 'production.log' instead of 'development.log'. See
+  <<RailsEnv,RailsEnv>> for configuration.
+- By default, Passenger runs Rails applications as the owner of 'environment.rb'.
+  So the log file can only be written to if that user has write permission to the
+  log file. Please 'chmod' or 'chown' your log file accordingly.
++
+See <<User_switching,User switching (security)>> for details.
+
+If you're using a RedHat-derived Linux distribution (such as Fedora or CentOS)
+then it is link:http://code.google.com/p/phusion-passenger/issues/detail?id=4[possible
+that SELinux is interfering]. RedHat's SELinux policy only allows Apache to read/write
+directories that have the 'httpd_sys_content_t' security context. Please run the
+following command to give your Rails application folder that context:
+
+-----------------------------------------------------------
+chcon -R -h -t httpd_sys_content_t /path/to/your/rails/app
+-----------------------------------------------------------
+
+[[conflicting_apache_modules]]
+=== Conflicting Apache modules ===
+
+==== mod_rewrite and mod_alias ====
+
+Passenger conflicts with 'mod_rewrite' and 'mod_alias'. Those modules may be
+installed and loaded together with 'mod_passenger', and they will work fine
+outside virtual hosts that contain a Rails application, but we recommend you
+not to use their features inside virtual hosts that contain a Rails
+application.
+
+By default, Passenger will override mod_rewrite rules on Rails hosts. This is
+because the default .htaccess, as provided by Ruby on Rails, redirects all
+requests to `dispatch.cgi' using mod_rewrite. This is a CGI application which
+loads the entire Ruby on Rails framework for every request, and thus is very
+slow. If we do not override mod_rewrite, then Ruby on Rails apps will be slow
+on Passenger by default -- but we want a good out-of-the-box experience.
+
+Furthermore, the primary reason why people use mod_rewrite with Rails
+applications, is to accelerate page caching. Passenger supports page caching
+out-of-the-box, without mod_rewrite.
+
+It is not fully understood how mod_alias conflicts with Passenger, but we
+recommend you not to use it on Rails virtual hosts. mod_alias rules can result
+in surprising problems.
+
+If you really want to use mod_rewrite on Rails virtual hosts, then please set
+the <<RailsAllowModRewrite,RailsAllowModRewrite>> configuration option. But
+please note that you will have to delete Rails applications' default .htaccess
+file, or add rewrite rules to negate its effects.
+
+==== mod_userdir ====
+
+'mod_userdir' is not compatible with Phusion Passenger at the moment.
+
 
 == Tips and notes ==
 
@@ -663,35 +782,6 @@ other. Passenger will automatically make use of the correct version.
 Passenger does not provide X-Sendfile support by itself. Please install
 link:http://tn123.ath.cx/mod_xsendfile/[mod_xsendfile] for X-Sendfile support.
 
-[[conflicting_apache_modules]]
-=== Conflicting Apache modules ===
-
-Passenger conflicts with 'mod_rewrite' and 'mod_alias'. Those modules may be
-installed and loaded together with 'mod_passenger', and they will work fine
-outside virtual hosts that contain a Rails application, but we recommend you
-not to use their features inside virtual hosts that contain a Rails
-application.
-
-By default, Passenger will override mod_rewrite rules on Rails hosts. This is
-because the default .htaccess, as provided by Ruby on Rails, redirects all
-requests to `dispatch.cgi' using mod_rewrite. This is a CGI application which
-loads the entire Ruby on Rails framework for every request, and thus is very
-slow. If we do not override mod_rewrite, then Ruby on Rails apps will be slow
-on Passenger by default -- but we want a good out-of-the-box experience.
-
-Furthermore, the primary reason why people use mod_rewrite with Rails
-applications, is to accelerate page caching. Passenger supports page caching
-out-of-the-box, without mod_rewrite.
-
-It is not fully understood how mod_alias conflicts with Passenger, but we
-recommend you not to use it on Rails virtual hosts. mod_alias rules can result
-in surprising problems.
-
-If you really want to use mod_rewrite on Rails virtual hosts, then please set
-the <<RailsAllowModRewrite,RailsAllowModRewrite>> configuration option. But
-please note that you will have to delete Rails applications' default .htaccess
-file, or add rewrite rules to negate its effects.
-
 
 == Appendix A: About this document ==