various format code fixups

[catagits/Catalyst-Manual.git] / lib / Catalyst / Manual / Deployment.pod

diff --git a/lib/Catalyst/Manual/Deployment.pod b/lib/Catalyst/Manual/Deployment.pod
index 665eff8..816d3ed 100644 (file)
--- a/lib/Catalyst/Manual/Deployment.pod
+++ b/lib/Catalyst/Manual/Deployment.pod
@@ -1,20 +1,36 @@
+=encoding utf8
+
 =head1 NAME
 
 Catalyst::Manual::Deployment - Deploying Catalyst
 
 =head1 DEPLOYMENT OPTIONS
 
-=head2 Deployment for shared hosting
+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.
 
-L<Catalyst::Manual::Deployment::SharedHosting>
+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 mod_perl
+=head2 Deployment in a shared hosting environment
 
-L<Catalyst::Manual::Deployment::Apache::mod_perl>
+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.
+
+Full details of deploying Catalyst in a shared hosting environment are at
+L<Catalyst::Manual::Deployment::SharedHosting>.
 
 =head2 FastCGI
 
-L<Catalyst::Manual::Deployment::FastCGI>
+FastCGI is the most common Catalyst deployment option. It is documented
+generally in L<Catalyst::Manual::Deployment::FastCGI>, and there are specific
+instructions for using FastCGI with common web servers below:
 
 =head3 Apache
 
@@ -32,12 +48,51 @@ L<Catalyst::Manual::Deployment::lighttpd::FastCGI>
 
 L<Catalyst::Manual::Deployment::IIS::FastCGI>
 
+=head2 mod_perl
+
+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
 
-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; a list of possible deployment servers are shown
+below:
+
+=head3 Starman
+
+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, and pipeline requests.
+
+=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 there are a number of caveats which
+mean that it is not suitable for most deployments.
+
+=head2 Chef
+
+L<Chef|http://www.opscode.com/chef/> is an open-source systems integration
+framework built specifically for automating cloud computing deployments. A
+Cookbooks demonstrating how to deploy a Catalyst application using Chef is
+available at L<http://community.opscode.com/cookbooks/catalyst> and
+L<https://github.com/melezhik/cookbooks/wiki/Catalyst-cookbook-intro>.
+
 =head1 AUTHORS
 
 Catalyst Contributors, see Catalyst.pm