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 |
0e820331 |
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. |
1d2376f3 |
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 | |
0191b435 |
73 | =head2 3. Configure your application |
1d2376f3 |
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 | |
0191b435 |
96 | =head2 Test It |
1d2376f3 |
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 | |
0191b435 |
101 | =head1 Other Options |
1d2376f3 |
102 | |
0191b435 |
103 | =head2 Non-root location |
1d2376f3 |
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 | |
0191b435 |
117 | =head2 Static file handling |
1d2376f3 |
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 | |
1d2376f3 |
130 | Note the path of the application needs to be stated explicitly in the |
0191b435 |
131 | web server configuration for this recipes. |
c62b44f3 |
132 | |
1d2376f3 |
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 | |