lib/Catalyst/Manual/Deployment/Apache/mod_perl.pod

   1 =head1 NAME
   2
   3 Catalyst::Manual::Deployment::Apache::mod_perl - Deploying Catalyst with mod_perl
   4
   5 =head1 mod_perl Deployment
   6
   7 mod_perl is not the best solution for many applications, but we'll list some
   8 pros and cons so you can decide for yourself.
   9
  10 =head2 Pros
  11
  12 =head3 Speed
  13
  14 mod_perl is fast and your app will be loaded in memory
  15 within each Apache process.
  16
  17 =head3 Shared memory for multiple apps
  18
  19 If you need to run several Catalyst apps on the same server, mod_perl will
  20 share the memory for common modules.
  21
  22 =head2 Cons
  23
  24 =head3 Memory usage
  25
  26 Since your application is fully loaded in memory, every Apache process will
  27 be rather large.  This means a large Apache process will be tied up while
  28 serving static files, large files, or dealing with slow clients.  For this
  29 reason, it is best to run a two-tiered web architecture with a lightweight
  30 frontend server passing dynamic requests to a large backend mod_perl
  31 server.
  32
  33 =head3 Reloading
  34
  35 Any changes made to the core code of your app require a full Apache restart.
  36 Catalyst does not support Apache::Reload or StatINC.  This is another good
  37 reason to run a frontend web server where you can set up an
  38 C<ErrorDocument 502> page to report that your app is down for maintenance.
  39
  40 =head4 Cannot run multiple versions of the same app
  41
  42 It is not possible to run two different versions of the same application in
  43 the same Apache instance because the namespaces will collide.
  44
  45 =head3 Cannot run different versions of libraries.
  46
  47 If you have two different applications which run on the same machine,
  48 which need two different versions of a library then the only way to do
  49 this is to have per-vhost perl interpreters (with different library paths).
  50 This is entirely possible, but nullifies all the memory sharing benefits that
  51 you get from having multiple applications sharing the same interpreter.
  52
  53 =head1 Setup
  54
  55 Now that we have that out of the way, let's talk about setting up mod_perl
  56 to run a Catalyst app.
  57
  58 =head2 2. Install Apache with mod_perl
  59
  60 Both Apache 1.3 and Apache 2 are supported, although Apache 2 is highly
  61 recommended.  Apache 1.3 will no longer be supported with Catalyst 5.9.  With
  62 Apache 2, make sure you are using the prefork MPM and not the worker MPM.  The
  63 reason for this is that many Perl modules are not thread-safe and may have
  64 problems running within the threaded worker environment.  Catalyst is
  65 thread-safe however, so if you know what you're doing, you may be able to run
  66 using worker.
  67
  68 In Debian, the following commands should get you going.
  69
  70     apt-get install apache2-mpm-prefork
  71     apt-get install libapache2-mod-perl2
  72
  73 =head2 3. Configure your application
  74
  75 Every Catalyst application will automagically become a mod_perl handler
  76 when run within mod_perl.  This makes the configuration extremely easy.
  77 Here is a basic Apache 2 configuration.
  78
  79     PerlSwitches -I/var/www/MyApp/lib
  80     PerlModule MyApp
  81
  82     <Location />
  83         SetHandler          modperl
  84         PerlResponseHandler MyApp
  85     </Location>
  86
  87 The most important line here is C<PerlModule MyApp>.  This causes mod_perl
  88 to preload your entire application into shared memory, including all of your
  89 controller, model, and view classes and configuration.  If you have -Debug
  90 mode enabled, you will see the startup output scroll by when you first
  91 start Apache.
  92
  93 For an example Apache 1.3 configuration, please see the documentation for
  94 L<Catalyst::Engine::Apache::MP13>.
  95
  96 =head2 Test It
  97
  98 That's it, your app is now a full-fledged mod_perl application!  Try it out
  99 by going to http://your.server.com/.
 100
 101 =head1 Other Options
 102
 103 =head2 Non-root location
 104
 105 You may not always want to run your app at the root of your server or virtual
 106 host.  In this case, it's a simple change to run at any non-root location
 107 of your choice.
 108
 109     <Location /myapp>
 110         SetHandler          modperl
 111         PerlResponseHandler MyApp
 112     </Location>
 113
 114 When running this way, it is best to make use of the C<uri_for> method in
 115 Catalyst for constructing correct links.
 116
 117 =head2 Static file handling
 118
 119 Static files can be served directly by Apache for a performance boost.
 120
 121     DocumentRoot /var/www/MyApp/root
 122     <Location /static>
 123         SetHandler default-handler
 124     </Location>
 125
 126 This will let all files within root/static be handled directly by Apache.  In
 127 a two-tiered setup, the frontend server should handle static files.
 128 The configuration to do this on the frontend will vary.
 129
 130 Note the path of the application needs to be stated explicitly in the
 131 web server configuration for this recipes.
 132
 133 =head1 AUTHORS
 134
 135 Catalyst Contributors, see Catalyst.pm
 136
 137 =head1 COPYRIGHT
 138
 139 This library is free software. You can redistribute it and/or modify it under
 140 the same terms as Perl itself.
 141
 142 =cut
 143