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.  With Apache 2, make sure you are using the prefork MPM and not
  62 the worker MPM.  The reason for this is that many Perl modules are not
  63 thread-safe and may have problems running within the threaded worker
  64 environment.  Catalyst is thread-safe however, so if you know what you're
  65 doing, you may be able to run using worker.
  66
  67 In Debian, the following commands should get you going.
  68
  69     apt-get install apache2-mpm-prefork
  70     apt-get install libapache2-mod-perl2
  71
  72 =head2 3. Configure your application
  73
  74 Every Catalyst application will automagically become a mod_perl handler
  75 when run within mod_perl.  This makes the configuration extremely easy.
  76 Here is a basic Apache 2 configuration.
  77
  78     PerlSwitches -I/var/www/MyApp/lib
  79     PerlModule MyApp
  80
  81     <Location />
  82         SetHandler          modperl
  83         PerlResponseHandler MyApp
  84     </Location>
  85
  86 The most important line here is C<PerlModule MyApp>.  This causes mod_perl
  87 to preload your entire application into shared memory, including all of your
  88 controller, model, and view classes and configuration.  If you have -Debug
  89 mode enabled, you will see the startup output scroll by when you first
  90 start Apache.
  91
  92 For an example Apache 1.3 configuration, please see the documentation for
  93 L<Catalyst::Engine::Apache::MP13>.
  94
  95 =head2 Test It
  96
  97 That's it, your app is now a full-fledged mod_perl application!  Try it out
  98 by going to http://your.server.com/.
  99
 100 =head1 Other Options
 101
 102 =head2 Non-root location
 103
 104 You may not always want to run your app at the root of your server or virtual
 105 host.  In this case, it's a simple change to run at any non-root location
 106 of your choice.
 107
 108     <Location /myapp>
 109         SetHandler          modperl
 110         PerlResponseHandler MyApp
 111     </Location>
 112
 113 When running this way, it is best to make use of the C<uri_for> method in
 114 Catalyst for constructing correct links.
 115
 116 =head2 Static file handling
 117
 118 Static files can be served directly by Apache for a performance boost.
 119
 120     DocumentRoot /var/www/MyApp/root
 121     <Location /static>
 122         SetHandler default-handler
 123     </Location>
 124
 125 This will let all files within root/static be handled directly by Apache.  In
 126 a two-tiered setup, the frontend server should handle static files.
 127 The configuration to do this on the frontend will vary.
 128
 129 Note the path of the application needs to be stated explicitly in the
 130 web server configuration for this recipes.
 131
 132 =head1 AUTHORS
 133
 134 Catalyst Contributors, see Catalyst.pm
 135
 136 =head1 COPYRIGHT
 137
 138 This library is free software. You can redistribute it and/or modify it under
 139 the same terms as Perl itself.
 140
 141 =cut
 142