=head3 Page Caching
Another method of caching is to cache the entire HTML page. While this is
-traditionally handled by a front-end proxy server like Squid, the Catalyst
+traditionally handled by a frontend proxy server like Squid, the Catalyst
PageCache plugin makes it trivial to cache the entire output from
frequently-used or slow actions.
requests for / and /?foo=bar will result in different cache items. Also,
only GET requests will be cached by the plugin.
-You can even get that front-end Squid proxy to help out by enabling HTTP
+You can even get that frontend Squid proxy to help out by enabling HTTP
headers for the cached page.
MyApp->config(
=head1 DEPLOYMENT OPTIONS
-Catalyst applications most often deployed as a FastCGI or mod_perl application,
-however as Catalyst is based on the L<PSGI> specification, any web handler
-implementing that specification can be used to run Catalyst applications.
+Catalyst applications are most often deployed as a FastCGI or mod_perl
+application (with FastCGI being the recommended option). However, as
+Catalyst is based on the L<PSGI> specification, any web handler
+implementing that specification can be used to run Catalyst
+applications.
This documentation most thoroughly covers the normal and traditional deployment
options, but will mention alternate methods of deployment, and we welcome
additional documentation from people deploying Catalyst in non-standard
environments.
-=head2 Deployment for shared hosting
+=head2 Deployment in a shared hosting environment
-Almost all shared hosting environments involve deploying Catalyst as a FastCGI
-on Apache.
+Almost all shared hosting environments involve deploying Catalyst as a
+FastCGI application on Apache. You will usually want to have a set of
+libraries specific to your application installed on your shared host.
-You will usually want to have a set of libraries specific to your application
-installed on your shared host, and there are instructions about this in
+Full details of deploying Catalyst in a shared hosting enviroment are at
L<Catalyst::Manual::Deployment::SharedHosting>.
=head2 FastCGI
-FastCGI is the most common Catalyst deployment option, it is documented
+FastCGI is the most common Catalyst deployment option. It is documented
generally in L<Catalyst::Manual::Deployment::FastCGI>, and there are specific
-instructions for common web servers linked below:
+instructions for using FastCGI with common web servers below:
=head3 Apache
=head2 mod_perl
-Traditionally a common deployment option for dedicated applications, with some
-advantages and disadvantages over FastCGI. This is documented in
+Traditionally a common deployment option for dedicated applications,
+mod_perl has some advantages and disadvantages over FastCGI. Use of
+mod_perl is documented in
L<Catalyst::Manual::Deployment::Apache::mod_perl>.
=head2 Development Server
-It is possible to deploy the Catalyst development server behind a reverse
-proxy. This may work well for small scale applications which are in an early
-development phase, but you want to be able to show to people. See:
-L<Catalyst::Manual::Deployment::DevelopmentServer>.
+It is possible to deploy the Catalyst development server behind a
+reverse proxy. This may work well for small-scale applications which are
+in an early development phase, but which you want to be able to show to
+people. See L<Catalyst::Manual::Deployment::DevelopmentServer>.
=head2 PSGI
-Catalyst can be deployed with any PSGI compliant handler. See L<Catalyst::PSGI>
-for more information, and a list of possible deployment servers are shown
+Catalyst can be deployed with any PSGI-compliant handler. See L<Catalyst::PSGI>
+for more information; a list of possible deployment servers are shown
below:
=head3 Starman
-L<Starman> is a high performance perl server implementation, which is designed
+L<Starman> is a high-performance Perl server implementation, which is designed
to be used directly (rather than behind a reverse proxy). It includes HTTP/1.1
-support, chunked requests and responses, keep-alive xxand pipeline requests.
+support, chunked requests and responses, keep-alive, and pipeline requests.
-=head3 Starlet.
+=head3 Starlet
Starlet is a standalone HTTP/1.0 server with keep‐alive support which is
suitable for running HTTP application servers behind a reverse proxy.
=head3 Twiggy
-L<Twiggy> is a high-performance asynchronous web server. It can be used in
-conjunction with Catalyst, but with a number of caveats which mean that it is
-not suitable for most deployments.
+L<Twiggy> is a high-performance asynchronous web server. It can be used
+in conjunction with Catalyst, but there are a number of caveats which
+mean that it is not suitable for most deployments.
=head1 AUTHORS
=head3 1. Install Apache with mod_fastcgi
-mod_fastcgi for Apache is a third party module, and can be found at
-L<http://www.fastcgi.com/>. It is also packaged in many distributions,
-for example, libapache2-mod-fastcgi in Debian. You will also need to install
-the L<FCGI> module from cpan.
+mod_fastcgi for Apache is a third-party module, and can be found at
+L<http://www.fastcgi.com/>. It is also packaged in many distributions
+(for example, libapache2-mod-fastcgi in Debian). You will also need to
+install the L<FCGI> module from CPAN.
Important Note! If you experience difficulty properly rendering pages,
try disabling Apache's mod_deflate (Deflate Module), e.g. 'a2dismod deflate'.
The FastCgiExternalServer directive tells Apache that when serving
-/tmp/myapp to use the FastCGI application listenting on the socket
+/tmp/myapp to use the FastCGI application listening on the socket
/tmp/mapp.socket. Note that /tmp/myapp.fcgi B<MUST NOT> exist --
it's a virtual file name. With some versions of C<mod_fastcgi> or
C<mod_fcgid>, you can use any name you like, but some require that the
=head1 mod_perl Deployment
-mod_perl is not the best solution for many applications, but we'll list some
-pros and cons so you can decide for yourself.
+The recommended method of deploying Catalyst applications is FastCGI. In
+many cases, mod_perl is not the best solution, but we'll list some pros
+and cons so you can decide for yourself.
=head2 Pros
=head3 Speed
-mod_perl is fast and your app will be loaded in memory
-within each Apache process.
+mod_perl is fast, and your entire app will be loaded in memory within
+each Apache process.
=head3 Shared memory for multiple apps
=head3 Reloading
-Any changes made to the core code of your app require a full Apache restart.
-Catalyst does not support Apache::Reload or StatINC. This is another good
-reason to run a frontend web server where you can set up an
-C<ErrorDocument 502> page to report that your app is down for maintenance.
+Any changes made to the code of your app require a full restart of
+Apache. Catalyst does not support Apache::Reload or StatINC. This is
+another good reason to run a frontend web server where you can set up an
+C<ErrorDocument 502> page to report that your app is down for
+maintenance.
=head4 Cannot run multiple versions of the same app
It is not possible to run two different versions of the same application in
the same Apache instance because the namespaces will collide.
-=head3 Cannot run different versions of libraries.
+=head3 Cannot run different versions of libraries
If you have two different applications which run on the same machine,
-which need two different versions of a library then the only way to do
-this is to have per-vhost perl interpreters (with different library paths).
-This is entirely possible, but nullifies all the memory sharing benefits that
-you get from having multiple applications sharing the same interpreter.
+and each application needs a different versions of a library, the only
+way to do this is to have per-vhost perl interpreters (with different
+library paths). This is entirely possible, but nullifies all the memory
+sharing benefits that you get from having multiple applications sharing
+the same interpreter.
=head1 Setup
Catalyst::Manual::DevelopmentServer - Development server deployment
-The development server is a mini web server written in perl. However if
-you supply the C<-f> option to the development server, it will load
-the higher performance L<Starman> server, which can be used as an
+The development server is a mini web server written in Perl. However, if
+you supply the C<-f> option to the development server, it will load the
+higher performance L<Starman> server, which can be used as an
application server with a lightweight proxy web server at the front.
=head1 Setup
=head2 Other web servers
-The proxy configuration above can also be replicated with a different front end
-server or proxy such as varnish, nginx or lighttpd.
+The proxy configuration above can also be replicated with a different
+frontend server or proxy, such as varnish, nginx, or lighttpd.
=head1 AUTHORS
=head3 Load-balancing
-You can launch your application on multiple backend servers and allow the
-frontend web server to load-balance between all of them. And of course, if
-one goes down, your app continues to run fine.
+You can launch your application on multiple backend servers and allow
+the frontend web server to perform load-balancing among all of them. And
+of course, if one goes down, your app continues to run.
=head3 Multiple versions of the same app
=head3 Widely supported.
-FastCGI is compatible with a lot more server implementations than Apache.
+FastCGI is compatible with many server implementations, not just Apache.
=head2 Cons
Any web server which supports FastCGI should work with Catalyst. Configuration
recipies for well-known web servers are linked below, and we would welcome
-contributions from people deploying Catalyst against other web servers.
+contributions from people deploying Catalyst on other web servers.
=head2 Apache
=head1 Microsoft IIS
-It is possible to run Catalyst under IIS with FastCGI, but only on IIS 6.0
-(Microsoft Windows 2003), IIS 7.0 (Microsoft Windows 2008 and Vista) and
-hopefully its successors.
+It is possible to run Catalyst under IIS with FastCGI, but only on IIS
+6.0 (Microsoft Windows 2003), IIS 7.0 (Microsoft Windows 2008 and
+Vista), and (hopefully) its successors.
-Even if it is declared that FastCGI is supported on IIS 5.1 (Windows XP) it
-does not support some features (specifically: wildcard mappings) that prevents
-running Catalyst application.
+FastCGI is sometimes said to be supported on IIS 5.1 (Windows XP), but
+some features (specifically, wildcard mappings) are not supported. This
+prevents Catalyst applications from running on the server.
Let us assume that our server has the following layout:
=item Install FastCGI extension for IIS 6.0
-FastCGI is not a standard part of IIS 6 - you have to install it separately. For
-more info and download go to L<http://www.iis.net/extensions/FastCGI>. Choose
-approptiate version (32-bit/64-bit), installation is quite simple
-(in fact no questions, no options).
+FastCGI is not a standard part of IIS 6 - you have to install it
+separately. For more info and the download, go to
+L<http://www.iis.net/extensions/FastCGI>. Choose the appropriate version
+(32-bit/64-bit); installation is quite simple (in fact no questions, no
+options).
=item Create a new website
=item Set website properties
-On tab "Web site" set proper values for:
-Site Description, IP Address, TCP Port, SSL Port etc.
+On the tab "Web site", set proper values for: Site Description, IP
+Address, TCP Port, SSL Port, etc.
-On tab "Home Directory" set the following:
+On the tab "Home Directory" set the following:
Local path: "d:\WWW\WebApp\root"
Local path permission flags: check only "Read" + "Log visits"
Execute permitions: "Scripts only"
Click "Configuration" button (still on Home Directory tab) then click "Insert"
-the wildcard application mapping and in the next dialog set:
+the wildcard application mapping, and in the next dialog set:
Executable: "c:\windows\system32\inetsrv\fcgiext.dll"
Uncheck: "Verify that file exists"
=item Necessary steps during IIS7 installation
-During IIS7 installation after you have added role "Web Server (IIS)" you need
-to check to install role feature "CGI" (do not be nervous that it is not
-FastCGI). If you already have IIS7 installed you can add "CGI" role feature
-through "Control panel" > "Programs and Features".
+During IIS7 installation, after you have added role "Web Server (IIS)"
+you need to check to install the role feature "CGI" (do not be nervous
+that it is not FastCGI). If you already have IIS7 installed you can add
+the "CGI" role feature through "Control panel" > "Programs and
+Features".
=item Create a new website
appcmd.exe set config "CatalystSite" -section:system.webServer/handlers /+"[name='CatalystFastCGI',path='*',verb='GET,HEAD,POST',modules='FastCgiModule',scriptProcessor='d:\strawberry\perl\bin\perl.exe|d:\www\WebApp\script\webapp_fastcgi.pl -e',resourceType='Unspecified',requireAccess='Script']" /commit:apphost
-Note: before launching the commands above do not forget to change site
-name and paths to values relevant for your server setup.
+Note: before launching the commands above, do not forget to change the
+site name and paths to values relevant for your server setup.
=back
=head1 Catalyst on shared hosting
-So, you want to put your Catalyst app out there for the whole world to
-see, but you don't want to break the bank. There is an answer - if you
-can get shared hosting with FastCGI and a shell, you can install your
-Catalyst app in a local directory on your shared host. First, run
+So, you want to put your Catalyst application out there for the whole
+world to see, but you don't want to break the bank. There is an answer -
+if you can get shared hosting with FastCGI and a shell, you can install
+your Catalyst app in a local directory on your shared host. First, run
perl -MCPAN -e shell
-and go through the standard CPAN configuration process. Then exit out
+and go through the standard CPAN configuration process. Then exit
without installing anything. Next, download the latest L<local::lib>
-package and follow it's 'bootstrap' instructions to get it installed
+package and follow its 'bootstrap' instructions to get it installed
and the local configuration added to your C<< ~/.bashrc >>.
Now log out, then back in again (or run C<". .bashrc"> if you
prefer).
-Now you can install the modules you need using CPAN as normal; they
-will be installed into your local directory, and perl will pick them
-up. Finally, change directory into the root of your virtual host and
-symlink your application's script directory in:
+Now you can install the modules you need using CPAN as normal; they will
+be installed into your local directory, and Perl will pick them up.
+Finally, change into the root directory of your virtual host, and
+symlink your application's script directory:
cd path/to/mydomain.com
ln -s ~/lib/MyApp/script script
)
}
-Which serves everything in the img, static, css directories
-statically, as well as the favicon file.
+This will serve everything in the C<img>, C<static>, and C<css>
+directories statically, as well as the favicon file.
=head1 AUTHORS
This library is free software. You can redistribute it and/or modify it under
the same terms as Perl itself.
-=cut
\ No newline at end of file
+=cut
=head1 nginx
Catalyst runs under nginx via FastCGI in a similar fashion as the lighttpd
-standalone server as described above.
+standalone server.
nginx does not have its own internal FastCGI process manager, so you must run
the FastCGI service separately.
C<$fastcgi_script_name> would be "/myapp/path/of/the/action". Catalyst will
process this accordingly and setup the application base as expected.
-This behavior is somewhat different than Apache and Lighttpd, but is still
+This behavior is somewhat different from Apache and lighttpd, but is still
functional.
For more information on nginx, visit:
projects / catagits/Catalyst-Manual.git / commitdiff