====== Catalyst/Perl and LiteSpeed How-To ======

This guide is based the on a Catalyst how-to written by Conundrum at http://www.dev411.com/wiki/Installing_LiteSpeed_and_FastCGI_for_Catalyst.

Make sure you have LiteSpeed Web Server installed.

===== Configuring LiteSpeed =====

Login to LiteSpeed Web Admin.

Configure Virtual Host

  * Click on "Server Configuration" on the admin server home page.
  * There is a Listener called Default enabled already. To add a virtual host to that listener, in the left nav column, click on the 'Default' link under the 'Listeners' link. This will bring up a page with the "Address Settings" and "Virtual Host Mappings". There's a virtual host called Example already configured.
  * To use the Example virtual host, click on 'Edit' and add the domains you'd like to use. Use commas to separate multiple domains like [myapp.com, www.myapp.com]. Click 'Save' and then 'Apply Changes' which is in the upper left corner and red now. The 'Add' link here doesn't seem to work as it brings you to the Example virtual host. To add a vitual host click on the 'Virtual Hosts' link in the left nav column and then click 'Add.' We won't do this for this quick setup. 

===== Create Catalyst FastCGI "External App" =====

    * While in "Server Configuration" click 'Server' in the left nav column and then click the 'External Apps' tab on top of the page body. There shouldn't be any apps loaded yet.
    * Click 'Add' in the upper right corner of the table and then select 'Fast CGI App' from the drop down before clicking 'Next'.
    * This brings you to the "FastCGI App Definition" page where you'll tell LiteSpeed how to run the FastCGI app. The FastCGI app can be a stand-alone server (listing via *NIX sockets or TCP) or it can be a local "static" FastCGI started by the server. A stand-alone FastCGI server has been tested successfully with sockets and TCP. There is a setting called 'Persistent Connection' to make a persistent connection to the FastCGI server. Ruby FCGI does not support persistent connection to the FCGI instance. It is unknown if Perl has problems with LiteSpeed's persistent FastCGI connection. To configure this page use the following settings and then click 'Save' and 'Apply Changes'. The 'Name' is just an internal reference and can be anything. 

<code>
Name: MyApp
Address: UDS://tmp/myapp.sock
Initial Request Timeout: 60
Retry Timeout: 0
Memory Soft Limit: 80M
Memory Hard Limit: 100M
Process Soft Limit: 200
Process Hard Limit: 200
</code>

To use TCP, use the something like the following for 'Address':

<code>
Address: 10.0.0.2:1030
</code>

Make sure the FastCGI server is running on the port you select with something like either of the following depending on whether you're using sockets or TCP:

<code>
MyApp/script/myapp_fastcgi.pl -l /tmp/myapp.socket -n 5 -d
MyApp/script/myapp_fastcgi.pl -l 1030 -n 5 -d
</code>

NOTE: From LiteSpeed staff: When an application's internal process manager is prefered, you can still let LiteSpeed start the parent process automatically, in that case, just set "instances" to "1", and set the command line parameter '-n' to match "Max Connections" and get rid of "-d" option.] This will be incorporated after it has been tested.

===== Create Catalyst FastCGI App "Context" =====

Now that the FastCGI app is configured, we need to let LiteSpeed know what URLs will bind to the Catalyst FCGI app. This is done by setting a LiteSpeed "Context".

    * Go back to the "Server Configuration" page and click on the 'Example' virtual host link at the bottom of the left nav column.
    * Click on the 'Context' tab that appears above the page body and you will see a number of mapped URLs. Click 'Add' and on the next page select 'Fast CGI' from the drop down before clicking 'Next'.
    * This brings you to the "Static Context Definition" page. To have the Catalyst app handle the root directory enter / for URI and make sure 'FastCGI App' is set to the name you configured when setting the 'External App'. Click 'Save' and then 'Apply Changes'
    * You're done. Now just restart the webserver. 

===== Restart LiteSpeed =====

Gracefully restart LiteSpeed via web admin or commandline:

<code>
/mylswsinstall/bin/lswsctrl restart
</code>