3 Catalyst::Manual::Deployment::Apache::mod_perl - Deploying Catalyst with mod_perl
5 =head1 mod_perl Deployment
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.
14 mod_perl is fast and your app will be loaded in memory
15 within each Apache process.
17 =head3 Shared memory for multiple apps
19 If you need to run several Catalyst apps on the same server, mod_perl will
20 share the memory for common modules.
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
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.
40 =head4 Cannot run multiple versions of the same app
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.
45 =head3 Cannot run different versions of libraries.
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.
55 Now that we have that out of the way, let's talk about setting up mod_perl
56 to run a Catalyst app.
58 =head2 2. Install Apache with mod_perl
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.
67 In Debian, the following commands should get you going.
69 apt-get install apache2-mpm-prefork
70 apt-get install libapache2-mod-perl2
72 =head2 3. Configure your application
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.
78 PerlSwitches -I/var/www/MyApp/lib
83 PerlResponseHandler MyApp
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
92 For an example Apache 1.3 configuration, please see the documentation for
93 L<Catalyst::Engine::Apache::MP13>.
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/.
102 =head2 Non-root location
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
110 PerlResponseHandler MyApp
113 When running this way, it is best to make use of the C<uri_for> method in
114 Catalyst for constructing correct links.
116 =head2 Static file handling
118 Static files can be served directly by Apache for a performance boost.
120 DocumentRoot /var/www/MyApp/root
122 SetHandler default-handler
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.
129 Note the path of the application needs to be stated explicitly in the
130 web server configuration for this recipes.
134 Catalyst Contributors, see Catalyst.pm
138 This library is free software. You can redistribute it and/or modify it under
139 the same terms as Perl itself.