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