passenger 4.0.44 → 4.0.45

data/doc/DeveloperQuickstart.md

@@ -0,0 +1,70 @@
+# Phusion Passenger Developer QuickStart
+
+<a href="https://vimeo.com/phusionnl/review/97427161/15cb4cc59a"><img src="http://blog.phusion.nl/wp-content/uploads/2014/06/passenger_developer_quickstart.png"></a>
+
+_Watch the Developer QuickStart screencast_
+
+Phusion Passenger provides an easy and convenient development environment that contributors can use. The development environment is a 64-bit Ubuntu 14.04 virtual machine and contains everything that you need. The build toolchain is already setup, all dependencies are installed and web servers are preconfigured. You can start coding almost immediately. And because it's a virtual machine, it doesn't matter which host operating system you're using.
+
+You use this development environment through [Vagrant](http://www.vagrantup.com/) and [VirtualBox](https://www.virtualbox.org/). Vagrant is an extremely useful tool for managing virtual machines, while VirtualBox is virtualization software. Both tools are free and open source. Vagrant allows you to easily share a directory between the host OS and the VM. This means that you can use the editor on your host OS to edit source files, and compile inside the VM.
+
+## Getting started
+
+ 1. Install [Vagrant](http://www.vagrantup.com/).
+ 2. Install [VirtualBox](http://www.virtualbox.org/).
+ 3. Inside the Phusion Passenger source tree, run: `vagrant up`. This will spin up the VM and will set it up. This can take a while so feel free to grab a cup of coffee.
+ 4. Once the VM has been setup, login to it by running: `vagrant ssh`.
+
+## Workflow
+
+The workflow is to:
+
+ * Edit code on the host.
+ * Use git commands on the host.
+ * Compile in the VM.
+ * Run tests in the VM.
+
+The Phusion Passenger source code is located in /vagrant.
+
+When you're done developing Phusion Passenger, you can shut down the VM by running `vagrant halt`. Next time you want to spin it up again, run `vagrant up`.
+
+## Starting and accessing Apache
+
+Apache is installed, but it's not set up with Phusion Passenger by default. So you must first compile the Phusion Passenger Apache module:
+
+    cd /vagrant
+    rake apache2
+
+Next, enable the Phusion Passenger module and restart Apache:
+
+    sudo a2enmod passenger
+    sudo service apache2 restart
+
+You can now access Apache from the host on http://127.0.0.1:8000 through :8005. The VM has a sample Ruby Rack application configured on http://127.0.0.1:8001/. Visit that URL and see it in action. Its source code is located in `dev/rack.test` in the Phusion Passenger source tree.
+
+## Starting and accessing Nginx
+
+The Nginx source code and binaries are located in /home/vagrant/nginx. If this is the first time you use Nginx in this VM, you must install it. Run:
+
+    cd /home/vagrant/nginx
+    rake bootstrap
+
+Next, start Nginx by using a script that the development environment provides:
+
+    ./start
+
+You can now access Nginx from the host on http://127.0.0.1:8100 through :8105. The VM has a sample Ruby Rack application configured on http://127.0.0.1:8101/. Visit that URL and see it in action. Its source code is located in `dev/rack.test` in the Phusion Passenger source tree.
+
+## Running tests
+
+Tests can be run immediately without any setup.
+
+    rake test:cxx
+    rake test:integration:apache2
+    rake test:integration:nginx
+
+## Further reading
+
+ * [Contributors Guide](https://github.com/phusion/passenger/blob/master/CONTRIBUTING.md)
+ * [Design and Architecture](https://www.phusionpassenger.com/documentation/Design%20and%20Architecture.html)
+ * [Coding Tips and Pitfalls](https://github.com/phusion/passenger/blob/master/doc/CodingTipsAndPitfalls.md)

data/doc/Users guide Apache.idmap.txt

@@ -134,33 +134,37 @@
 
 8.3.1. PassengerEnabled <on|off>	=>	passengerenabled-on-off--74rzth
 
-8.3.2. PassengerRuby <filename>	=>	passengerruby-filename--1r3fv73
+8.3.2. PassengerBaseURI <uri>	=>	passengerbaseuri-uri--97i9mm
 
-8.3.3. PassengerPython <filename>	=>	passengerpython-filename--1ssesv3
+8.4. Application loading options	=>	application-loading-options-1uedd4o
 
-8.3.4. PassengerNodejs <filename>	=>	passengernodejs-filename--2mjb1j
+8.4.1. PassengerRuby <filename>	=>	passengerruby-filename--1r3fv73
 
-8.3.5. PassengerAppEnv <string>	=>	passengerappenv-string--s3ojlc
+8.4.2. PassengerPython <filename>	=>	passengerpython-filename--1ssesv3
 
-8.3.6. RailsEnv <string>	=>	railsenv-string--1b0xxvu
+8.4.3. PassengerNodejs <filename>	=>	passengernodejs-filename--2mjb1j
 
-8.3.7. RackEnv <string>	=>	rackenv-string--vve9py
+8.4.4. PassengerAppEnv <string>	=>	passengerappenv-string--s3ojlc
 
-8.3.8. PassengerAppRoot <path/to/root>	=>	passengerapproot-path-to-root--uf24yd
+8.4.5. RailsEnv <string>	=>	railsenv-string--1b0xxvu
 
-8.3.9. PassengerBaseURI <uri>	=>	passengerbaseuri-uri--97i9mm
+8.4.6. RackEnv <string>	=>	rackenv-string--vve9py
 
-8.3.10. PassengerRestartDir <directory>	=>	passengerrestartdir-directory--1fmhmv0
+8.4.7. PassengerAppRoot <path/to/root>	=>	passengerapproot-path-to-root--uf24yd
 
-8.3.11. PassengerRollingRestarts <on|off>	=>	passengerrollingrestarts
+8.4.8. PassengerAppType <name>	=>	passengerapptype-name--62jzqf
 
-8.3.12. PassengerResistDeploymentErrors <on|off>	=>	passengerresistdeploymenterrors
+8.4.9. PassengerStartupFile <filename>	=>	passengerstartupfile-filename--14vhvn9
 
-8.4. Process spawning options	=>	process-spawning-options-v2vscm
+8.4.10. PassengerRestartDir <directory>	=>	passengerrestartdir-directory--1fmhmv0
 
-8.4.1. PassengerSpawnMethod <string>	=>	passengerspawnmethod-string--sodg2y
+8.4.11. PassengerSpawnMethod <string>	=>	passengerspawnmethod-string--sodg2y
 
-8.4.2. PassengerLoadShellEnvvars <on|off>	=>	passengerloadshellenvvars-on-off--1290yz1
+8.4.12. PassengerLoadShellEnvvars <on|off>	=>	passengerloadshellenvvars-on-off--1290yz1
+
+8.4.13. PassengerRollingRestarts <on|off>	=>	passengerrollingrestarts
+
+8.4.14. PassengerResistDeploymentErrors <on|off>	=>	passengerresistdeploymenterrors
 
 8.5. Security options	=>	security-options-1pb75ho
 
@@ -218,6 +222,10 @@
 
 8.7.4. PassengerMaxRequestQueueSize <number>	=>	passenger-max-request-queue-size-number--1f1uocd
 
+8.7.5. PassengerStickySessions <on|off>	=>	passengerstickysessions-on-off--fx1jkt
+
+8.7.6. PassengerStickySessionsCookieName	=>	passenger-sticky-sessions-cookie-name-stktkx
+
 8.8. Compatibility options	=>	compatibility-options-8jve5a
 
 8.8.1. PassengerResolveSymlinksInDocumentRoot <on|off>	=>	passengerresolvesymlinksindocumentroot-on-off--1r0qcp8
@@ -398,15 +406,13 @@
 
 15.2.2. Summary of benefits	=>	summary-of-benefits-1yrihfb
 
-15.3. Smart spawning gotcha #1: unintentional file descriptor sharing	=>	smart-spawning-gotcha-1-unintentional-file-descriptor-sharing-z1y55l
+15.3. Smart spawning caveat #1: unintentional file descriptor sharing	=>	smart-spawning-gotcha-1-unintentional-file-descriptor-sharing-z1y55l
 
 15.3.1. Example 1: Memcached connection sharing (harmful)	=>	example-1-memcached-connection-sharing-harmful--c71wqw
 
 15.3.2. Example 2: Log file sharing (not harmful)	=>	example-2-log-file-sharing-not-harmful--1p2yuol
 
-15.4. Smart spawning gotcha #2: the need to revive threads	=>	smart-spawning-gotcha-2-the-need-to-revive-threads-1k6cj7d
-
-15.5. Smart spawning gotcha #3: code load order	=>	smart-spawning-gotcha-3-code-load-order-nkotiy
+15.4. Smart spawning caveat #2: the need to revive threads	=>	smart-spawning-gotcha-2-the-need-to-revive-threads-1k6cj7d
 
 16. Appendix D: About environment variables	=>	appendix-d-about-environment-variables-1lebv1u
 

data/doc/Users guide Apache.txt

@@ -612,6 +612,24 @@ This way, Phusion Passenger will not interfere with Wordpress.
 
 In each place, it may be specified at most once. The default value is 'on'.
 
+[[PassengerBaseURI]]
+==== PassengerBaseURI <uri> ====
+Used to specify that the given URI is a Phusion Passenger-served application. Please refer
+to the following sections for examples:
+
+ * <<deploying_rails_to_sub_uri,Deploying Rails 1.x and 2.x to a sub URI>>
+ * <<deploying_rack_to_sub_uri,Deploying Rack (including Rails >= 3) to a sub URI>>
+ * <<deploying_python_to_sub_uri,Deploying Python to a sub URI>>
+
+This option may occur in the following places:
+
+ * In the global server configuration.
+ * In a virtual host configuration block.
+ * In a `<Directory>` or `<Location>` block.
+ * In '.htaccess', if `AllowOverride Options` is on.
+
+=== Application loading options
+
 [[PassengerRuby]]
 ==== PassengerRuby <filename>
 The `PassengerDefaultRuby` and `PassengerRuby` directives specify the Ruby interpreter to use. Similarly, the `PassengerPython` and `PassengerNodejs` directives are for specifying the Python interpreter and the Node.js command, respectively.
@@ -746,27 +764,102 @@ Example:
 -----------------------------
 <VirtualHost test.host>
     DocumentRoot /var/rails/zena/sites/example.com/public
-    PassengerAppRoot /var/rails/zena   # <-- normally Phusion Passenger would
-                                       #     have assumed that the application
-                                       #     root is "/var/rails/zena/sites/example.com"
+    # Normally Phusion Passenger would have assumed that the
+    # application root is "/var/rails/zena/sites/example.com".
+    # This overrides it.
+    PassengerAppRoot /var/rails/zena
 </VirtualHost>
 -----------------------------
 
-[[PassengerBaseURI]]
-==== PassengerBaseURI <uri> ====
-Used to specify that the given URI is a Phusion Passenger-served application. Please refer
-to the following sections for examples:
+[[PassengerAppType]]
+==== PassengerAppType <name>
+:version: 4.0.25
+include::users_guide_snippets/since_version.txt[]
 
- * <<deploying_rails_to_sub_uri,Deploying Rails 1.x and 2.x to a sub URI>>
- * <<deploying_rack_to_sub_uri,Deploying Rack (including Rails >= 3) to a sub URI>>
- * <<deploying_python_to_sub_uri,Deploying Python to a sub URI>>
+By default, Phusion Passenger autodetects the type of the application, e.g. whether it's a Ruby, Python, Node.js or Meteor app. If it's unable to autodetect the type of the application (e.g. because you've specified a custom <<PassengerStartupFile,PassengerStartupFile>>) then you can use this option to force Phusion Passenger to recognize the application as a specific type.
+
+Allowed values are:
+
+ * `rack` - Ruby on Rails >= 3.0 and Ruby Rack
+ * `classic-rails` - Ruby on Rails 1.x and 2.0
+ * `wsgi` - Python
+ * `node` - Node.js, or Meteor JS in bundled mode
+ * `meteor` - Meteor JS in non-bundled mode
+
+If you set this option, then you **must** also set <<PassengerAppRoot,PassengerAppRoot>>, otherwise Phusion Passenger does not properly recognize your application.
 
 This option may occur in the following places:
 
  * In the global server configuration.
  * In a virtual host configuration block.
  * In a `<Directory>` or `<Location>` block.
- * In '.htaccess', if `AllowOverride Options` is on.
+ * In '.htaccess'.
+
+In each place, it may be specified at most once.
+
+Example:
+
+-----------------------------
+<VirtualHost test.host>
+    DocumentRoot /webapps/example.com/public
+    # Use server.js as the startup file (entry point file) for
+    # your Node.js application, instead of the default app.js
+    PassengerStartupFile server.js
+    PassengerAppType node
+    PassengerAppRoot /webapps/example.com
+</VirtualHost>
+-----------------------------
+
+[[PassengerStartupFile]]
+==== PassengerStartupFile <filename>
+:version: 4.0.25
+include::users_guide_snippets/since_version.txt[]
+
+This option specifies the startup file that Phusion Passenger should use when loading the application.
+
+Every application has a *startup file* or *entry point file*: a file where the application begins execution. Some languages have widely accepted conventions about how such a file should be called (e.g. Ruby, with its `config.ru`). Other languages have somewhat-accepted conventions (e.g. Node.js, with its `app.js`). In these cases, Phusion Passenger reuses these conventions, and executes applications through those files.
+
+Other languages have no conventions at all, and so Phusion Passenger invents one (e.g. Python WSGI with `passenger_wsgi.py`).
+
+Here's a list of the language-specific conventions that Phusion Passenger accepts:
+
+[options="header"]
+|================================================
+| Language                        | Phusion Passenger convention
+| Ruby on Rails >= 3.0, Ruby Rack | config.ru
+| Ruby on Rails 1.x and 2.x       | config/environment.rb
+| Python                          | passenger_wsgi.py
+| Node.js                         | app.js
+|================================================
+
+But sometimes you might not want to adhere to the convention that Phusion Passenger accepts. For example, on Node.js, you might want to use `server.js` as the startup file instead of the default `app.js`. With this option, you can customize the startup file to any file you like.
+
+Notes:
+
+ * Customizing the startup file affects <<user_switching,user switching>>. After all, if user switching is enabled, the application is executed as the user that owns the startup file.
+ * If you set this option, you **must** also set <<PassengerAppRoot,PassengerAppRoot>> and <<PassengerAppType,PassengerAppType>>, otherwise Phusion Passenger doesn't know what kind of application it is.
+
+This option may occur in the following places:
+
+ * In the global server configuration.
+ * In a virtual host configuration block.
+ * In a `<Directory>` or `<Location>` block.
+ * In '.htaccess'.
+
+In each place, it may be specified at most once.
+
+Example:
+
+-----------------------------
+<VirtualHost test.host>
+    DocumentRoot /webapps/example.com/public
+    # Use server.js as the startup file (entry point file) for
+    # your Node.js application, instead of the default app.js
+    PassengerStartupFile server.js
+    PassengerAppType node
+    PassengerAppRoot /webapps/example.com
+</VirtualHost>
+-----------------------------
 
 ==== PassengerRestartDir <directory>
 As described in the deployment chapters of this document, Phusion Passenger
@@ -826,6 +919,50 @@ allow the attacker to cause a Denial-of-Service.
 You can prevent this from happening by pointing PassengerRestartDir to a
 directory that's readable by Apache, but only writable by administrators.
 
+[[PassengerSpawnMethod]]
+==== PassengerSpawnMethod <string>
+[TIP]
+."What spawn method should I use?"
+=========================================================
+This subsection attempts to describe spawn methods, but it's okay if you don't (want to)
+understand it, as it's mostly a technical detail. You can basically follow this rule of thumb:
+
+************************************************
+If your application works on Mongrel or Thin, but not on Phusion Passenger, then set
+`PassengerSpawnMethod` to 'direct'. Otherwise, leave it at 'smart' (the default).
+************************************************
+
+However, we do recommend you to try to understand it. The 'smart' spawn
+method bring many benefits.
+=========================================================
+
+include::users_guide_snippets/passenger_spawn_method.txt[]
+
+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 'smart'.
+
+[[PassengerLoadShellEnvvars]]
+==== PassengerLoadShellEnvvars <on|off>
+:version: 4.0.20
+include::users_guide_snippets/since_version.txt[]
+
+Enables or disables the loading of shell environment variables before spawning the application.
+
+If this option is turned on, and the user's shell is `bash`, then applications are loaded by running them with `bash -l -c`. Otherwise, they are loaded by running them directly from the `PassengerHelperAgent` process.
+
+This option may occur in the following places:
+
+ * In the global server configuration.
+ * In a virtual host configuration block.
+ * In a `<Directory>` or `<Location>` block.
+ * In '.htaccess', if `AllowOverride Options` is on.
+
+In each place, it may be specified at most once. The default value is 'on'.
+
 [[PassengerRollingRestarts]]
 ==== PassengerRollingRestarts <on|off>
 :version: 3.0.0
@@ -902,52 +1039,6 @@ This option may occur in the following places:
 
 In each place, it may be specified at most once. The default value is 'off'.
 
-=== Process spawning options
-
-[[PassengerSpawnMethod]]
-==== PassengerSpawnMethod <string>
-[TIP]
-."What spawn method should I use?"
-=========================================================
-This subsection attempts to describe spawn methods, but it's okay if you don't (want to)
-understand it, as it's mostly a technical detail. You can basically follow this rule of thumb:
-
-************************************************
-If your application works on Mongrel or Thin, but not on Phusion Passenger, then set
-`PassengerSpawnMethod` to 'direct'. Otherwise, leave it at 'smart' (the default).
-************************************************
-
-However, we do recommend you to try to understand it. The 'smart' spawn
-method bring many benefits.
-=========================================================
-
-include::users_guide_snippets/passenger_spawn_method.txt[]
-
-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 'smart'.
-
-[[PassengerLoadShellEnvvars]]
-==== PassengerLoadShellEnvvars <on|off>
-:version: 4.0.20
-include::users_guide_snippets/since_version.txt[]
-
-Enables or disables the loading of shell environment variables before spawning the application.
-
-If this option is turned on, and the user's shell is `bash`, then applications are loaded by running them with `bash -l -c`. Otherwise, they are loaded by running them directly from the `PassengerHelperAgent` process.
-
-This option may occur in the following places:
-
- * In the global server configuration.
- * In a virtual host configuration block.
- * In a `<Directory>` or `<Location>` block.
- * In '.htaccess', if `AllowOverride Options` is on.
-
-In each place, it may be specified at most once. The default value is 'on'.
-
 === Security options ===
 
 [[PassengerUserSwitching]]
@@ -1206,19 +1297,19 @@ The default value is '300'.
 
 [[PassengerMaxPreloaderIdleTime]]
 ==== PassengerMaxPreloaderIdleTime <integer> ====
-The ApplicationSpawner server (explained in <<spawning_methods_explained,Spawning
+The preloader process(explained in <<spawning_methods_explained,Spawning
 methods explained>>) has an idle timeout, just like the backend processes spawned by
 Phusion Passenger do. That is, it will automatically shutdown if it hasn't done
 anything for a given period.
 
-This option allows you to set the ApplicationSpawner server's idle timeout, in
+This option allows you to set the preloader's idle timeout, in
 seconds. A value of '0' means that it should never idle timeout.
 
-Setting a higher value will mean that the ApplicationSpawner server is kept around
+Setting a higher value will mean that the preloader is kept around
 longer, which may slightly increase memory usage. But as long as the
-ApplicationSpawner server is running, the time to spawn a Ruby on Rails backend
+preloader server is running, the time to spawn a Ruby on Rails backend
 process only takes about 10% of the time that is normally needed, assuming that
-you're using the 'smart' or 'smart-lv2' <<PassengerSpawnMethod,spawning method>>. So if your
+you're using the 'smart' <<PassengerSpawnMethod,spawning method>>. So if your
 system has enough memory, is it recommended that you set this option to a high
 value or to '0'.
 
@@ -1878,6 +1969,53 @@ This option may occur in the following places:
 
 In each place, it may be specified at most once. The default value is '100'.
 
+[[PassengerStickySessions]]
+==== PassengerStickySessions <on|off>
+:version: 4.0.55
+include::users_guide_snippets/since_version.txt[]
+
+When sticky sessions are enabled, all requests that a client sends will be routed to the same originating application process, whenever possible. When sticky sessions are disabled, requests may be distributed over multiple processes, and may not necessarily be routed to the originating process, in order to balance traffic over multiple CPU cores. Because of this, sticky sessions should only be enabled in specific circumstances.
+
+For applications that store important state inside the process's own memory -- that is, as opposed to storing state in a distributed data store, such as the database or Redis -- sticky sessions *should* be enabled. This is because otherwise, some requests could be routed to a different process, which stores different state data. Because processes don't share memory with each other, there's no way for one process to know about the state in another process, and then things can go wrong.
+
+One prominent example is the popular link:http://sockjs.org/[SockJS library], which is capable of emulating WebSockets through long polling. This is implemented through two HTTP endpoints, `/SESSION_ID/xhr_stream` (a long polling end point which sends data from the server to the client), and `/SESSION_ID/xhr_send` (a normal POST endpoint which is used for sending data from the client to the server). SockJS correlates the two requests with each other through a session identifier. At the same time, in its default configuration, it stores all known session identifiers in an in-memory data structure. It is therefore important that a particular `/SESSION_ID/xhr_send` request is sent to the same process where the corresponding `/SESSION_ID/xhr_stream` request originates from; otherwise, SockJS cannot correlate the two requests, and an error occurs.
+
+So prominent examples where sticky sessions should (or even *must*) be enabled, include:
+
+ * Applications that use the SockJS library (unless configured with a distributed data store)
+ * Applications that use the Socket.io library (unless configured with a distributed data store)
+ * Applications that use the faye-websocket gem (unless configured with a distributed data store)
+ * Meteor JS applications (because Meteor uses SockJS)
+
+Sticky sessions work through the use of a special cookie, whose name can be customized with <<PassengerStickySessionsCookieName,PassengerStickySessionsCookieName>>. Phusion Passenger puts an identifier in this cookie, which tells Phusion Passenger what the originating process is. Next time the client sends a request, Phusion Passenger reads this cookie and uses the value in the cookie to route the request back to the originating process. If the originating process no longer exists (e.g. because it has crashed or restarted) then Phusion Passenger will route the request to some other process, and reset the cookie.
+
+If you have a load balancer in front end of Phusion Passenger + Apache, then you must configure sticky sessions on that load balancer too. Otherwise, the load balancer could route the request to a different server.
+
+This option may occur in the following places:
+
+ * In the global server configuration.
+ * In a virtual host configuration block.
+ * In a `<Directory>` or `<Location>` block.
+ * In '.htaccess'.
+
+In each place, it may be specified at most once. The default value is `off`.
+
+[[PassengerStickySessionsCookieName]]
+==== PassengerStickySessionsCookieName
+:version: 4.0.55
+include::users_guide_snippets/since_version.txt[]
+
+Sets the name of the <<PassengerStickySessions,sticky sessions>> cookie.
+
+This option may occur in the following places:
+
+ * In the global server configuration.
+ * In a virtual host configuration block.
+ * In a `<Directory>` or `<Location>` block.
+ * In '.htaccess'.
+
+In each place, it may be specified at most once. The default value is `passenger_route`.
+
 
 === Compatibility options ===