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 | |
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 | |
0191b435 |
10 | =head2 Pros |
1d2376f3 |
11 | |
0191b435 |
12 | =head3 Speed |
1d2376f3 |
13 | |
14 | mod_perl is fast and your app will be loaded in memory |
15 | within each Apache process. |
16 | |
0191b435 |
17 | =head3 Shared memory for multiple apps |
1d2376f3 |
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 | |
0191b435 |
22 | =head2 Cons |
1d2376f3 |
23 | |
0191b435 |
24 | =head3 Memory usage |
1d2376f3 |
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 | |
0191b435 |
33 | =head3 Reloading |
1d2376f3 |
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 | |
0191b435 |
45 | =head3 Cannot run different versions of libraries. |
1d2376f3 |
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 | |
0191b435 |
53 | =head1 Setup |
1d2376f3 |
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 | |
0191b435 |
58 | =head2 2. Install Apache with mod_perl |
1d2376f3 |
59 | |
60 | Both Apache 1.3 and Apache 2 are supported, although Apache 2 is highly |
17fad97e |
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. |
1d2376f3 |
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 | |
0191b435 |
72 | =head2 3. Configure your application |
1d2376f3 |
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 | |
0191b435 |
95 | =head2 Test It |
1d2376f3 |
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 | |
0191b435 |
100 | =head1 Other Options |
1d2376f3 |
101 | |
0191b435 |
102 | =head2 Non-root location |
1d2376f3 |
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 | |
0191b435 |
116 | =head2 Static file handling |
1d2376f3 |
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 | |
1d2376f3 |
129 | Note the path of the application needs to be stated explicitly in the |
0191b435 |
130 | web server configuration for this recipes. |
c62b44f3 |
131 | |
1d2376f3 |
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 | |