0
@@ -2,15 +2,17 @@
0
 
0
 image:images/phusion_banner.png[link="http://www.phusion.nl/"]
0
 
0
-Passenger is an Apache module, which makes deploying Ruby on Rails applications
0
-on Apache a breeze. It follows the usual Ruby on Rails conventions, such as
0
-"Don't-Repeat-Yourself" and ease of setup.
0
+Passenger is an Apache module, which makes deploying Ruby and Ruby on Rails
0
+applications on Apache a breeze. It follows the usual Ruby on Rails conventions,
0
+such as "Don't-Repeat-Yourself" and ease of setup, while at the same time providing
0
+enough flexibility.
0
 
0
 This users guide will teach you:
0
 
0
 - How to install Passenger.
0
 - How to configure Passenger.
0
 - How to deploy a Ruby on Rails application.
0
+- How to deploy a link:http://rack.rubyforge.org/[Rack]-based Ruby application.
0
 - How to solve common problems.
0
 
0
 This guide assumes that the reader is somewhat familiar with Apache and with
0
@@ -155,7 +157,7 @@ Ben Hughes has written an link:http://www.railsgarden.com/2008/04/12/configurati
0
 == Deploying a Ruby on Rails application ==
0
 
0
 Suppose you have a Ruby on Rails application in '/webapps/mycook', and you own
0
-the domain 'www.mycook.com'. You can either deploy your application in the
0
+the domain 'www.mycook.com'. You can either deploy your application to the
0
 virtual host's root (i.e. the application will be accessible from the root URL,
0
 'http://www.mycook.com/'), or in a sub URI (i.e. the application will be
0
 accessible from a sub URL, such as 'http://www.mycook.com/railsapplication').
0
@@ -177,7 +179,7 @@ For example:
0
 -------------------------------------------
0
 Then restart Apache. The application has now been deployed.
0
 
0
-[[deploying_to_sub_uri]]
0
+[[deploying_rails_to_sub_uri]]
0
 === Deploying to a sub URI ===
0
 
0
 Suppose that you already have a virtual host:
0
@@ -198,7 +200,7 @@ folder to a directory in the document root. For example:
0
 ln -s /webapps/mycook/public /websites/phusion/rails
0
 -------------------------------------------
0
 
0
-Next, add a `RailsBaseURI` option to the virtual host configuration:
0
+Next, add a <<RailsBaseURI,RailsBaseURI>> option to the virtual host configuration:
0
 -------------------------------------------
0
 <VirtualHost *:80>
0
     ServerName www.phusion.nl
0
@@ -227,6 +229,140 @@ touch /webapps/mycook/tmp/restart.txt
0
 -------------------------------------------
0
 
0
 
0
+== Deploying a Rack-based Ruby application ==
0
+
0
+Passenger supports arbitrary Ruby web applications that follow the
0
+link:http://rack.rubyforge.org/[Rack] interface.
0
+
0
+Passenger assumes that Rack application directories have a certain layout.
0
+Suppose that you have a Rack application in '/webapps/rackapp'. Then that
0
+folder must contain at least two entries:
0
+
0
+- 'config.ru', a Rackup file for starting the Rack application. This file must contain
0
+  the complete logic for initializing the application.
0
+- 'public/', a folder containing public static web assets, like images and stylesheets.
0
+- 'tmp/', used for 'restart.txt' (our application restart mechanism). This will
0
+  be explained in a following subsection.
0
+
0
+So '/webapps/rackapp' must, at minimum, look like this:
0
+----------------------
0
+/webapps/rackapp
0
+  |
0
+  +-- config.ru
0
+  |
0
+  +-- public/
0
+  |
0
+  +-- tmp/
0
+----------------------
0
+
0
+Suppose you own the domain 'www.rackapp.com'. You can either deploy your application
0
+to the virtual host's root (i.e. the application will be accessible from the root URL,
0
+'http://www.rackapp.com/'), or in a sub URI (i.e. the application will be
0
+accessible from a sub URL, such as 'http://www.rackapp.com/rackapp').
0
+
0
+NOTE: The default `RACK_ENV` environment in which deployed Rack applications
0
+are run, is ``production''. You can change this by changing the
0
+<<rack_env,'RackEnv'>> configuration option.
0
+
0
+=== Tutorial/example: writing and deploying a Hello World Rack application ===
0
+
0
+First we create a Passenger-compliant Rack directory structure:
0
+
0
+-------------------------------------------
0
+$ mkdir /webapps/rack_example
0
+$ mkdir /webapps/rack_example/public
0
+$ mkdir /webapps/rack_example/tmp
0
+-------------------------------------------
0
+
0
+Next, we write a minimal "hello world" Rack application:
0
+
0
+-------------------------------------------
0
+$ cd /webapps/rack_example
0
+$ some_awesome_editor config.ru
0
+...type in some source code...
0
+$ cat config.ru
0
+app = Proc.new do |env|
0
+    return [200, { "Content-Type" => "text/html" }, "hello <b>world</b>"]
0
+end
0
+run app
0
+-------------------------------------------
0
+
0
+Finally, we deploy it by adding the following configuration options to
0
+the Apache configuration file:
0
+
0
+-------------------------------------------
0
+<VirtualHost *:80>
0
+    ServerName www.rackexample.com
0
+    DocumentRoot /webapps/rack_example/public
0
+</VirtualHost>
0
+-------------------------------------------
0
+
0
+And we're done! After an Apache restart, the above Rack application will be available
0
+under the URL 'http://www.rackexample.com/'.
0
+
0
+=== Deploying to a virtual host's root ===
0
+
0
+Add a virtual host entry to your Apache configuration file. The virtual host's
0
+document root must point to your Rack application's 'public' folder.
0
+For example:
0
+-------------------------------------------
0
+<VirtualHost *:80>
0
+    ServerName www.rackapp.com
0
+    DocumentRoot /webapps/rackapp/public
0
+</VirtualHost>
0
+-------------------------------------------
0
+Then restart Apache. The application has now been deployed.
0
+
0
+[[deploying_rack_to_sub_uri]]
0
+=== Deploying to a sub URI ===
0
+
0
+Suppose that you already have a virtual host:
0
+
0
+-------------------------------------------
0
+<VirtualHost *:80>
0
+    ServerName www.phusion.nl
0
+    DocumentRoot /websites/phusion
0
+</VirtualHost>
0
+-------------------------------------------
0
+
0
+And you want your Rack application to be accessible from the URL
0
+'http://www.phusion.nl/rack'.
0
+
0
+To do this, make a symlink from your Rack application's 'public'
0
+folder to a directory in the document root. For example:
0
+-------------------------------------------
0
+ln -s /webapps/rackapp/public /websites/phusion/rack
0
+-------------------------------------------
0
+
0
+Next, add a <<RackBaseURI,RackBaseURI>> option to the virtual host configuration:
0
+-------------------------------------------
0
+<VirtualHost *:80>
0
+    ServerName www.phusion.nl
0
+    DocumentRoot /websites/phusion
0
+    RackBaseURI /rack                # This line has been added.
0
+</VirtualHost>
0
+-------------------------------------------
0
+Then restart Apache. The application has now been deployed.
0
+
0
+=== Redeploying (restarting the Rack application) ===
0
+
0
+Deploying a new version of a Rack application is as simple as
0
+re-uploading the application files, and restarting the application.
0
+
0
+There are two ways to restart the application:
0
+
0
+1. By restarting Apache.
0
+2. By creating or modifying the file 'tmp/restart.txt' in the Rack
0
+   application's root folder. Passenger will automatically restart the
0
+   application.
0
+
0
+For example, to restart our example application, we type this in the
0
+command line:
0
+-------------------------------------------
0
+touch /webapps/rackapp/tmp/restart.txt
0
+-------------------------------------------
0
+
0
+
0
 == Configuring Passenger ==
0
 
0
 After installation, Passenger does not need any further configurations.
0
@@ -241,14 +377,15 @@ and should usually not be changed manually.
0
 
0
 This required option may only occur once, in the global server configuration.
0
 
0
-=== RailsBaseURI <uri> ===
0
-Used to specify that the given URI is a Rails application. See
0
-<<deploying_to_sub_uri,Deploying to a sub URI>> for an example.
0
+=== PassengerRuby <filename> ===
0
+This option allows one to specify the Ruby interpreter to use.
0
 
0
-This option may occur multiple times, in the global server configuration or in a
0
-virtual host configuration block.
0
+This option may only occur once, in the global server configuration.
0
+The default is 'ruby'.
0
 
0
-=== RailsAutoDetect <on|off> ===
0
+=== Ruby on Rails-specific options ===
0
+
0
+==== RailsAutoDetect <on|off> ====
0
 Whether Passenger should automatically detect whether a virtual host's
0
 document root is a Ruby on Rails application. The default is 'on'.
0
 
0
@@ -270,39 +407,41 @@ the '/webapps/mycook/public' folder, instead of the output of the Ruby on Rails
0
 application.
0
 
0
 It is possible to explicitly specify that the host is a Ruby on Rails
0
-application by using the `RailsBaseURI` configuration option:
0
+application by using the <<RailsBaseURI,RailsBaseURI>> configuration option:
0
 
0
 -----------------------------
0
 RailsAutoDetect off
0
 <VirtualHost *:80>
0
     ServerName www.mycook.com
0
     DocumentRoot /webapps/mycook/public
0
-    RailsBaseURI /
0
+    RailsBaseURI /           # This line has been added.
0
 </VirtualHost>
0
 -----------------------------
0
 
0
+[[RailsBaseURI]]
0
+==== RailsBaseURI <uri> ====
0
+Used to specify that the given URI is a Rails application. See
0
+<<deploying_rails_to_sub_uri,Deploying Rails to a sub URI>> for an example.
0
+
0
+This option may occur multiple times, in the global server configuration or in a
0
+virtual host configuration block.
0
+
0
 [[RailsAllowModRewrite]]
0
-=== RailsAllowModRewrite <on|off> ===
0
+==== RailsAllowModRewrite <on|off> ====
0
 If enabled, Passenger will not override mod_rewrite rules. Please read
0
 <<conflicting_apache_modules,Conflicting Apache modules>> for details.
0
 
0
 This option may occur once, in the global server configuration or in a virtual host
0
 configuration block. The default value is 'off'.
0
 
0
-=== RailsRuby <filename> ===
0
-This option allows one to specify the Ruby interpreter to use.
0
-
0
-This option may only occur once, in the global server configuration.
0
-The default is 'ruby'.
0
-
0
 [[rails_env]]
0
-=== RailsEnv <string> ===
0
+==== RailsEnv <string> ====
0
 This option allows one to specify the default `RAILS_ENV` value.
0
 
0
 This option may occur once, in the global server configuration or in a virtual host
0
 configuration block. The default value is 'production'.
0
 
0
-=== RailsSpawnMethod <string> ===
0
+==== RailsSpawnMethod <string> ====
0
 [TIP]
0
 ."What spawn method should I use?"
0
 =========================================================
0
@@ -350,7 +489,7 @@ render <<reducing_memory_usage,Ruby Enterprise Edition's memory reduction techno
0
 This option may occur once, in the global server configuration or in a virtual host
0
 configuration block. The default value is 'smart'.
0
 
0
-=== RailsMaxPoolSize <integer> ===
0
+==== RailsMaxPoolSize <integer> ====
0
 The maximum number of Ruby on Rails application instances that may
0
 be simultaneously active. A larger number results in higher memory usage,
0
 but improved ability to handle concurrent HTTP clients.
0
@@ -374,7 +513,7 @@ TIP: We strongly recommend you to <<reducing_memory_usage,use Ruby Enterprise
0
 Edition>>. This allows you to reduce your memory usage by about 33%. And it's
0
 not hard to install.
0
 
0
-=== RailsPoolIdleTime <integer> ===
0
+==== RailsPoolIdleTime <integer> ====
0
 The maximum number of seconds that a Ruby on Rails application instance
0
 may be idle. That is, if an application instance hasn't done anything after
0
 the given number of seconds, then it will be shutdown in order to conserve
0
@@ -394,14 +533,14 @@ This option may only occur once, in the global server configuration.
0
 The default value is '120'.
0
 
0
 [[RailsUserSwitching]]
0
-=== RailsUserSwitching <on|off> ===
0
+==== RailsUserSwitching <on|off> ====
0
 Whether to enable <<user_switching,user switching support>>.
0
 
0
 This option may only occur once, in the global server configuration.
0
 The default value is 'on'.
0
 
0
 [[RailsDefaultUser]]
0
-=== RailsDefaultUser <username> ===
0
+==== RailsDefaultUser <username> ====
0
 Passenger enables <<user_switching,user switching support>> by default.
0
 This configuration option allows one to specify which user Rails
0
 applications must run as, if user switching fails or is disabled.
0
@@ -409,6 +548,58 @@ applications must run as, if user switching fails or is disabled.
0
 This option may only occur once, in the global server configuration.
0
 The default value is 'nobody'.
0
 
0
+=== Rack-specific options ===
0
+
0
+==== RackAutoDetect <on|off> ====
0
+Whether Passenger should automatically detect whether a virtual host's
0
+document root is a Rack application. The default is 'on'.
0
+
0
+This option may occur in the global server configuration or in a virtual host
0
+configuration block.
0
+
0
+For example, consider the following configuration:
0
+
0
+-----------------------------
0
+RackAutoDetect off
0
+<VirtualHost *:80>
0
+    ServerName www.rackapp.com
0
+    DocumentRoot /webapps/my_rack_app/public
0
+</VirtualHost>
0
+-----------------------------
0
+
0
+If one goes to 'http://www.rackapp.com/', the visitor will see the contents of
0
+the '/webapps/my_rack_app/public' folder, instead of the output of the Rack
0
+application.
0
+
0
+It is possible to explicitly specify that the host is a Rack
0
+application by using the <<RackBaseURI,RackBaseURI>> configuration option:
0
+
0
+-----------------------------
0
+RackAutoDetect off
0
+<VirtualHost *:80>
0
+    ServerName www.rackapp.com
0
+    DocumentRoot /webapps/my_rack_app/public
0
+    RackBaseURI /       # This line was added
0
+</VirtualHost>
0
+-----------------------------
0
+
0
+[[RackBaseURI]]
0
+==== RackBaseURI <uri> ====
0
+Used to specify that the given URI is a Rack application. See
0
+<<deploying_rack_to_sub_uri,Deploying Rack to a sub URI>> for an example.
0
+
0
+This option may occur multiple times, in the global server configuration or in a
0
+virtual host configuration block.
0
+
0
+[[rack_env]]
0
+==== RackEnv <string> ====
0
+The given value will be accessible in Rack applications in the `RACK_ENV`
0
+environment variable. This allows one to define the environment in which
0
+Rack applications are run, very similar to `RAILS_ENV`.
0
+
0
+This option may occur once, in the global server configuration or in a virtual host
0
+configuration block. The default value is 'production'.
0
+
0
 
0
 == Troubleshooting ==
0