doc/Users guide Standalone.html in passenger-4.0.35 vs doc/Users guide Standalone.html in passenger-4.0.36
- old
+ new
@@ -1126,10 +1126,12 @@
<div class="foo toclevel3"><a href="#_command_line_options">4.1. Command line options</a></div>
<div class="foo toclevel3"><a href="#config_file">4.2. Configuration file</a></div>
<div class="foo toclevel3"><a href="#advanced_configuration">4.3. Advanced configuration</a></div>
<div class="foo toclevel2"><a href="#_using_passenger_standalone_in_production">5. Using Passenger Standalone in production</a></div>
<div class="foo toclevel3"><a href="#starting_at_system_boot">5.1. Starting Passenger Standalone at system boot</a></div>
+<div class="foo toclevel3"><a href="#sharing_port">5.2. Sharing the same port between multiple Passenger Standalone instances</a></div>
+<div class="foo toclevel3"><a href="#_installing_passenger_standalone_behind_nginx">5.3. Installing Passenger Standalone behind Nginx</a></div>
<div class="foo toclevel2"><a href="#mass_deployment">6. Mass deployment</a></div>
<div class="foo toclevel2"><a href="#troubleshooting">7. Troubleshooting</a></div>
<div class="foo toclevel3"><a href="#_generic_troubleshooting_tips">7.1. Generic troubleshooting tips</a></div>
<div class="foo toclevel3"><a href="#_upon_uploading_a_file_phusion_passenger_reports_client_body_temp_00000000xx_failed_2_no_such_file_or_directory">7.2. Upon uploading a file, Phusion Passenger reports "client_body_temp/00000000xx failed (2: No such file or directory)"</a></div>
<div class="foo toclevel2"><a href="#about_environment_variables">8. Appendix: About environment variables</a></div>
@@ -2275,9 +2277,252 @@
<span style="font-style: italic"><span style="color: #9A1900"># normal user. Replace 'someusername' with the user you want to run your</span></span>
<span style="font-style: italic"><span style="color: #9A1900"># application under.</span></span>
passenger start --daemonize --port <span style="color: #993399">80</span> --user someusername</tt></pre>
</div>
</div>
+<div class="paragraph"><p>To stop Passenger Standalone, run:</p></div>
+<div class="listingblock">
+<div class="content">
+<!-- Generator: GNU source-highlight 2.11.1
+by Lorenzo Bettini
+http://www.lorenzobettini.it
+http://www.gnu.org/software/src-highlite -->
+<pre><tt>cd /path-to-your-webapp
+
+<span style="font-style: italic"><span style="color: #9A1900"># If you use RVM, use 'rvmsudo' instead of 'sudo'</span></span>
+sudo passenger stop</tt></pre>
+</div>
+</div>
+</div>
+<div class="sect2">
+<a href="javascript:void(0)" class="comments empty" title="Add a comment"><span class="count"></span></a><span class="anchor_helper" id="sharing_port"></span><h3 data-comment-topic="sharing-the-same-port-between-multiple-passenger-standalone-instances-3lcmc5" data-anchor="sharing_port">5.2. Sharing the same port between multiple Passenger Standalone instances</h3>
+<div class="paragraph"><p>If you have multiple applications on your server then it is desirable to have all of them listen on the same port (e.g. port 80), with the HTTP request’s host name determining which Passenger Standalone instance should handle the request. There are three ways to achieve this.</p></div>
+<div class="olist arabic"><ol class="arabic">
+<li>
+<p>
+The first way is to use the <a href="#mass_deployment">Mass deployment</a> feature, which allows Passenger Standalone to directly host multiple applications at the same time. Please refer to that section to learn more.
+</p>
+</li>
+<li>
+<p>
+The second way is to run multiple Passenger Standalone instances — one for each application — and to put all of them behind a <strong>reverse proxy</strong> or <strong>load balancer</strong>. The reverse proxy/load balancer can for example be Nginx, Apache or HAProxy. The reverse proxy/load balancer listens on port 80, determines which Passenger Standalone instance should handle the request, and forwards the request to that instance.
+</p>
+</li>
+<li>
+<p>
+The third way is to use <a href="Users%20guide%20Nginx.html">Phusion Passenger for Nginx</a> or <a href="Users%20guide%20Apache.html">Phusion Passenger for Apache</a>. These are two modes of Phusion Passenger that are distinct from the Standalone mode, which this document describes. In the Nginx and Apache modes, Phusion Passenger integrates directly into Nginx and Apache, and makes it very easy to host multiple applications directly on Nginx or Apache.
+</p>
+<div class="paragraph"><p>Compared method 2 — putting Passenger Standalone behind a reverse proxy or load balancer — the Nginx or Apache modes are easier to use and require less configuration. On the other hand, the Nginx modes requires reinstalling or recompiling Nginx, while the Apache mode requires that the Phusion Passenger Apache module is installed.</p></div>
+</li>
+</ol></div>
+<div class="paragraph"><p><strong>The rest of this subsection describes method 2.</strong></p></div>
+<span class="anchor_helper" id="_step_1_starting_all_applications"></span><h4 class="float" data-anchor="_step_1_starting_all_applications">Step 1: starting all applications</h4>
+<div class="paragraph"><p>Putting Passenger Standalone behind a reverse proxy requires three steps. First, you must start all Passenger Standalone instances that you want. Each one must be listening on a different port, because two applications can’t listen on the same port. Suppose that you have two applications, <span class="monospaced">/webapps/foo</span> and <span class="monospaced">/webapps/bar</span>. Here’s how you may start them:</p></div>
+<div class="listingblock">
+<div class="content">
+<!-- Generator: GNU source-highlight 2.11.1
+by Lorenzo Bettini
+http://www.lorenzobettini.it
+http://www.gnu.org/software/src-highlite -->
+<pre><tt><span style="font-style: italic"><span style="color: #9A1900"># Start foo on port 4000</span></span>
+cd /webapps/foo
+passenger start --daemonize --address <span style="color: #993399">127.0</span><span style="color: #990000">.</span><span style="color: #993399">0.1</span> --port <span style="color: #993399">4000</span>
+
+<span style="font-style: italic"><span style="color: #9A1900"># Start bar on port 4010</span></span>
+cd /webapps/bar
+passenger start --daemonize --address <span style="color: #993399">127.0</span><span style="color: #990000">.</span><span style="color: #993399">0.1</span> --port <span style="color: #993399">4010</span></tt></pre>
+</div>
+</div>
+<div class="paragraph"><p>Notice the fact that we pass <span class="monospaced">--address 127.0.0.1</span>, which tells Passenger Standalone to only listen for requests that originate from the local machine. This is because the reverse proxy/load balancer, not Passenger Standalone, is supposed to be responsible for receiving external HTTP requests. The reverse proxy/load balancer will be running on the same machine only, so limiting Passenger Standalone in this manner improves security.</p></div>
+<span class="anchor_helper" id="_step_2_install_and_configure_the_reverse_proxy_load_balancer"></span><h4 class="float" data-anchor="_step_2_install_and_configure_the_reverse_proxy_load_balancer">Step 2: install and configure the reverse proxy/load balancer</h4>
+<div class="paragraph"><p>The next step is to <strong>install a reverse proxy/load balancer</strong>, and to <strong>configure</strong> it to do the following:</p></div>
+<div class="ulist"><ul>
+<li>
+<p>
+To listen on port 80.
+</p>
+</li>
+<li>
+<p>
+To forward requests to either <em>foo</em> or <em>bar</em>, depending on the request’s HTTP host name.
+</p>
+</li>
+</ul></div>
+<div class="paragraph"><p>You can use any reverse proxy/load balancer you want, but we’re going to show an example using <a href="http://www.nginx.org/">Nginx</a> because it’s a pretty popular choice. Install Nginx as follows:</p></div>
+<table class="tableblock frame-all grid-all" style="
+width:100%;
+">
+<col style="width:50%;">
+<col style="width:50%;">
+<tbody>
+<tr>
+<td class="tableblock halign-left valign-top"><p class="tableblock">Debian, Ubuntu</p></td>
+<td class="tableblock halign-left valign-top"><p class="tableblock"><span class="monospaced">sudo apt-get update</span><br><span class="monospaced">sudo apt-get install nginx-extras</span></p></td>
+</tr>
+<tr>
+<td class="tableblock halign-left valign-top"><p class="tableblock">Red Hat, CentOS, ScientificLinux, Amazon Linux</p></td>
+<td class="tableblock halign-left valign-top"><p class="tableblock">Enable <a href="http://fedoraproject.org/wiki/EPEL">EPEL</a>, then run as root:<br><span class="monospaced">yum install nginx</span></p></td>
+</tr>
+<tr>
+<td class="tableblock halign-left valign-top"><p class="tableblock">Mac OS X (Homebrew)</p></td>
+<td class="tableblock halign-left valign-top"><p class="tableblock"><span class="monospaced">brew install nginx</span></p></td>
+</tr>
+<tr>
+<td class="tableblock halign-left valign-top"><p class="tableblock">Other operating systems</p></td>
+<td class="tableblock halign-left valign-top"><p class="tableblock">Install Nginx from <a href="http://www.nginx.org/">the Nginx website</a>.</p></td>
+</tr>
+</tbody>
+</table>
+<div class="paragraph"><p>Open the Nginx configuration file:</p></div>
+<table class="tableblock frame-all grid-all" style="
+width:100%;
+">
+<col style="width:50%;">
+<col style="width:50%;">
+<tbody>
+<tr>
+<td class="tableblock halign-left valign-top"><p class="tableblock">Debian, Ubuntu</p></td>
+<td class="tableblock halign-left valign-top"><p class="tableblock"><span class="monospaced">/etc/nginx/nginx.conf</span></p></td>
+</tr>
+<tr>
+<td class="tableblock halign-left valign-top"><p class="tableblock">Red Hat, CentOS, ScientificLinux, Amazon Linux</p></td>
+<td class="tableblock halign-left valign-top"><p class="tableblock"><span class="monospaced">/etc/nginx/nginx.conf</span></p></td>
+</tr>
+<tr>
+<td class="tableblock halign-left valign-top"><p class="tableblock">Mac OS X (Homebrew)</p></td>
+<td class="tableblock halign-left valign-top"><p class="tableblock"><span class="monospaced">/usr/local/etc/nginx/nginx.conf</span></p></td>
+</tr>
+<tr>
+<td class="tableblock halign-left valign-top"><p class="tableblock">Other operating systems</p></td>
+<td class="tableblock halign-left valign-top"><p class="tableblock">It depends on how you installed Nginx, but it’s usually <span class="monospaced">$PREFIX/conf/nginx.conf</span>, where <span class="monospaced">$PREFIX</span> is the prefix you installed Nginx to.</p></td>
+</tr>
+</tbody>
+</table>
+<div class="paragraph"><p>Add virtual host entries for your applications foo and bar. While making the virtual host entries, you must determine what host names foo and bar should respond to. Let’s say that foo should respond to <em>www.foo.com</em> and bar should respond to <em>www.bar.com</em>. Then the following entries will tell Nginx to listen on port 80, and to handle requests for the domains <em>www.foo.com</em> and <em>www.bar.com</em> differently.</p></div>
+<div class="listingblock">
+<div class="content monospaced">
+<pre>http {
+ ...
+
+ # These are some "magic" Nginx configuration options that aid in making
+ # WebSockets work properly with Passenger Standalone. Please learn more
+ # at http://nginx.org/en/docs/http/websocket.html
+ map $http_upgrade $connection_upgrade {
+ default upgrade;
+ '' close;
+ }
+
+ server {
+ listen 80;
+ server_name www.foo.com;
+
+ # Tells Nginx to serve static assets from this directory.
+ root /webapps/foo/public;
+
+ location / {
+ # Tells Nginx to forward all requests for www.foo.com
+ # to the Passenger Standalone instance listening on port 4000.
+ proxy_pass http://127.0.0.1:4000;
+
+ # These are "magic" Nginx configuration options that
+ # should be present in order to make the reverse proxying
+ # work properly. Also contains some options that make WebSockets
+ # work properly with Passenger Standalone. Please learn more at
+ # http://nginx.org/en/docs/http/ngx_http_proxy_module.html
+ proxy_http_version 1.1;
+ proxy_set_header Host $http_host;
+ proxy_set_header Upgrade $http_upgrade;
+ proxy_set_header Connection $connection_upgrade;
+ proxy_buffering off;
+ }
+ }
+
+ # We handle bar in a similar manner.
+ server {
+ listen 80;
+ server_name www.bar.com;
+
+ root /webapps/bar/public;
+
+ location / {
+ # bar is listening on port 4010 instead of 4000, we
+ # change the URL here.
+ proxy_pass http://127.0.0.1:4010;
+
+ proxy_http_version 1.1;
+ proxy_set_header Host $http_host;
+ proxy_set_header Upgrade $http_upgrade;
+ proxy_set_header Connection $connection_upgrade;
+ proxy_buffering off;
+ }
+ }
+}</pre>
+</div>
+</div>
+<div class="paragraph"><p>Once you’re done editing the Nginx configuration file, restart Nginx:</p></div>
+<table class="tableblock frame-all grid-all" style="
+width:100%;
+">
+<col style="width:50%;">
+<col style="width:50%;">
+<tbody>
+<tr>
+<td class="tableblock halign-left valign-top"><p class="tableblock">Debian, Ubuntu</p></td>
+<td class="tableblock halign-left valign-top"><p class="tableblock"><span class="monospaced">sudo /etc/init.d/nginx restart</span></p></td>
+</tr>
+<tr>
+<td class="tableblock halign-left valign-top"><p class="tableblock">Red Hat, CentOS, ScientificLinux, Amazon Linux</p></td>
+<td class="tableblock halign-left valign-top"><p class="tableblock"><span class="monospaced">sudo service nginx restart</span></p></td>
+</tr>
+<tr>
+<td class="tableblock halign-left valign-top"><p class="tableblock">Mac OS X (Homebrew)</p></td>
+<td class="tableblock halign-left valign-top"><p class="tableblock">1. Run <span class="monospaced">sudo kill $(cat /usr/local/var/run/nginx.pid)</span><br>
+ 2. You you installed the Nginx launchd plist that Homebrew provides (see <span class="monospaced">brew info nginx</span> to learn more), then you don’t have to do anything, and launchd will automatically restart Nginx. Otherwise, you have to manually start Nginx again: <span class="monospaced">sudo /usr/local/bin/nginx</span>.</p></td>
+</tr>
+<tr>
+<td class="tableblock halign-left valign-top"><p class="tableblock">Other operating systems</p></td>
+<td class="tableblock halign-left valign-top">
+<p class="tableblock">It depends on how you installed Nginx, but it’s usually as follows:</p>
+<p class="tableblock"> 1. Lookup the PID of the Nginx master process using <span class="monospaced">ps aux</span>.<br>
+ 2. Run <span class="monospaced">sudo kill <PID></span><br>
+ 3. Start Nginx again: <span class="monospaced">sudo $PREFIX/sbin/nginx</span>, where <span class="monospaced">$PREFIX</span> is the prefix you installed Nginx to.</p>
+</td>
+</tr>
+</tbody>
+</table>
+<span class="anchor_helper" id="_step_3_testing"></span><h4 class="float" data-anchor="_step_3_testing">Step 3: testing</h4>
+<div class="paragraph"><p>Nginx should now be listening on port 80, and should forward requests to foo and bar respectively. Let’s test it out by accessing <a href="http://www.foo.com">http://www.foo.com</a> and <a href="http://www.bar.com">http://www.bar.com</a>. But first, we need to ensure that any requests to <em>www.foo.com</em> and <em>www.bar.com</em>, that originate from the local machine, actually end up at the local host, and not at the IP address specified in the DNS records. To do this, edit <span class="monospaced">/etc/hosts</span> and add:</p></div>
+<div class="listingblock">
+<div class="content monospaced">
+<pre>127.0.0.1 www.foo.com www.bar.com</pre>
+</div>
+</div>
+<div class="paragraph"><p>Now visit <a href="http://www.foo.com">http://www.foo.com</a> and <a href="http://www.bar.com">http://www.bar.com</a>, and verify that it works.</p></div>
+<span class="anchor_helper" id="_step_4_making_all_apps_start_at_system_boot"></span><h4 class="float" data-anchor="_step_4_making_all_apps_start_at_system_boot">Step 4: making all apps start at system boot</h4>
+<div class="paragraph"><p>Once you restart the server, the reverse proxy/load balancer will no longer be able to serve <em>www.foo.com</em> or <em>www.bar.com</em> because the Passenger Standalone instances that host them are no longer running. You must therefore configure the system to start Passenger Standalone at system boot. Please refer to <a href="#starting_at_system_boot">Starting Passenger Standalone at system boot</a> for more information.</p></div>
+<div class="paragraph"><p>For example, you can put this in <span class="monospaced">/etc/rc.local</span> to make the system start foo and bar at system boot:</p></div>
+<div class="listingblock">
+<div class="content">
+<!-- Generator: GNU source-highlight 2.11.1
+by Lorenzo Bettini
+http://www.lorenzobettini.it
+http://www.gnu.org/software/src-highlite -->
+<pre><tt><span style="font-style: italic"><span style="color: #9A1900"># If you installed Phusion Passenger from tarball, add its `bin` directory to PATH.</span></span>
+<span style="font-style: italic"><span style="color: #9A1900">#export PATH=/path-to-passenger/bin:$PATH</span></span>
+
+cd /webapps/foo
+passenger start --daemonize --port <span style="color: #993399">4000</span> --user someusername1
+
+cd /webapps/bar
+passenger start --daemonize --port <span style="color: #993399">4010</span> --user someusername2</tt></pre>
+</div>
+</div>
+<span class="anchor_helper" id="_step_5_wrapping_up"></span><h4 class="float" data-anchor="_step_5_wrapping_up">Step 5: wrapping up</h4>
+<div class="paragraph"><p>Edit <span class="monospaced">/etc/hosts</span> and remove the entry that you added in step 3.</p></div>
+</div>
+<div class="sect2">
+<a href="javascript:void(0)" class="comments empty" title="Add a comment"><span class="count"></span></a><span class="anchor_helper" id="_installing_passenger_standalone_behind_nginx"></span><h3 data-comment-topic="installing-passenger-standalone-behind-nginx-1xylsfk" data-anchor="_installing_passenger_standalone_behind_nginx">5.3. Installing Passenger Standalone behind Nginx</h3>
+<div class="paragraph"><p>This is described in <a href="#sharing_port">Sharing the same port between multiple Passenger Standalone instances</a>.</p></div>
</div>
</div>
</div>
<div class="sect1">
<a href="javascript:void(0)" class="comments empty" title="Add a comment"><span class="count"></span></a><span class="anchor_helper" id="mass_deployment"></span><h2 data-comment-topic="mass-deployment-1xqriy4" data-anchor="mass_deployment">6. Mass deployment</h2>