SwitchPipe has been designed specifically to make it as easy as possible to deploy apps. Hopefully this page will demonstrate that!

This page will, for now, assume you are using Apache and are generally deploying Ruby applications. However, SwitchPipe is technology agnostic (except for HTTP) so you can adapt these instructions to fit most other arrangements.

Deploying a Rails Application

 

This assumes you are using a virtual host under Apache, etc, have .htaccess functionality and Mongrel is installed. It also assumes SwitchPipe is installed and running in /usr/local/switchpipe. Note that these instructions are easily tailored to deploying Merb, Ramaze, Camping or other frameworks' applications.

1) Upload a Rails application to your Web space. For the purposes of this guide, let's say into a folder "myapp". Make sure your app is considered suitable to run under the "production" environment (there's no point using development environment when SwitchPipe can time out your app within several seconds!).

 

2) Create a configuration file for your app at /usr/local/switchpipe/apps/myapp.yml containing:

 

path: /home/your_sites_user_name/public_html/myapp
type: mongrel_rails
max_instances: 3
timeout: 15
user: your_sites_user_name
group: your_sites_user_name

The "path" line must have the full, absolute path to the base folder of your Rails app. If you wish to use "thin" rather than Mongrel, just use "type: thin". Tweak the max instances and timeout to taste.

 

3) Create a .htaccess file in the root folder of your public Web space, containing the following: 

  RewriteEngine On
  RewriteCond %{REQUEST_FILENAME} !-f
  RewriteRule ^(.*)$ http://127.0.0.1:10000/myapp/$1 [P]

 

4) Access your site from your regular Web browser and enjoy!

Maintaining Subdirectories When a Rails App is in a Subdirectory Only

 

If your Rails app in is a subdirectory and you want it to appear that way, so that links in the app like /stylesheets become /yourappfolder/stylesheets, and so on, you need to add this line to your config/environments/production.rb:

 

ActionController::AbstractRequest.relative_url_root = "/yourappfolder"

 

The correct folder name is then prefixed to URLs sent out by the application.

 

 

Doing It Without .htaccess / mod_rewrite

If you cannot use .htaccess, you will need to use directives in the <VirtualHost> block for your site in /etc/httpd/conf/httpd.conf (or wherever these settings are kept on your system), like so:

ProxyPass / http://127.0.0.1:10000/myapp/

ProxyPassReverse / http://127.0.0.1:10000/myapp/

This is a lot less powerful than the opportunities that the .htaccess / mod_rewrite method will allow.

Letting Apache Serve The Static Files

Even though the above will get your Rails app up and running, you might like Apache to take some of the slack and serve up any static files it can. To do this you must make sure the DocumentRoot (as defined in the VirtualHost block within Apache's configuration) points directly to the "public" folder of your Rails application. Alternatively, you can place static files in your regular Web site's root folder and they will serve statically thanks to the rewrite rules used above. If you use the ProxyPass technique, you're stuck unless you wish to proxy only a specific directory to SwitchPipe, e.g. ProxyPass /app http://127.0.0.1:10000/myapp/

...

... Do other types of application later ...

 

...

 

Application Configuration File Format

 

The most bare bones configuration file would look like this:

    path: demo_apps
    cmd: ruby webrick_thing [[PORT]]

No timeout is specified (internal default of 300 seconds is used), no user/group is
specified, no maximum number of instances is specified. It's really bare bones.

A more advanced configuration file, using many features, however, looks like this:

    path: /Users/peter/dev/rails/app1
    type: thin
    max_instances: 12
    timeout: 9
    user: peter
    group: peter
    socket_type: unix
   
This configuration file runs a Rails app using the Thin HTTP daemon (an alternative
to Mongrel) on the backend, uses up to 12 concurrent instances, times out any
processes unused for over 9 seconds, enforces a user and group to run the application
under, and uses SwitchPipe's alpha UNIX socket support (which Thin can use).

A more typical Rails deployment would look like this (this is actually used for
http://www.jrubyinside.com/ in production):

    path: /home/jruby/inside
    type: mongrel_rails
    max_instances: 3
    timeout: 15
    user: jruby
    group: jruby

The settings you can use are:

            path: Specify the directory to change to before running a command,
                  such as mongrel_rails, thin, or whatever is necessary to launch
                  a single instance of the backend application.
   
               cmd: The actual command to run to get an instance of the backend
                  application running. For a Rails app, this could be something
                  like: mongrel_rails start -p [[PORT]] -e production

                  It is necessary to use the placeholder [[PORT]] in all cmd lines
                  so that SwitchPipe can tell the backend application which port to
                  run on. (For UNIX sockets, merely use the [[PORT]] within a socket
                  filename as a unique identifier.)

              type: A shortcut to avoid remembering and typing in many cmd lines.
                  Currently only "mongrel_rails" and "thin" are supported. The cmd
                  lines are automatically adjusted if users / groups are specified
                  (or, on "thin" only, UNIX sockets are used).

   max_instances: The maximum number of concurrent instances of the backend app
                  to run. All concurrency is handled "behind the scenes" by
                  SwitchPipe, so if you have the resources, be generous. For a
                  quiet Rails app, 2 or 3 instances might work okay, but try up to
                  10 or 15 if things get busy.

         timeout: The maximum number of seconds a backend application can "idle"
                  without getting any requests before it is killed by SwitchPipe.
                  The timeout enables your server to be clean of processes that are
                  sitting around doing nothing but hogging memory!

            user: Specify a group and user to run the backend application as.
           group: Currently this is only of use if you use the "type" field or
                  use [[USER]] and [[GROUP]] placeholders in your cmd line. No
                  suEXEC-type arrangements or support yet. The backend app must
                  deal with that for now (luckily things like Mongrel and Thin do!)