Plack::Handler::Apache2(3pm)

1Plack::Handler::Apache2U(s3e)r Contributed Perl DocumentaPtliaocnk::Handler::Apache2(3)
2
3
4

NAME

6       Plack::Handler::Apache2 - Apache 2.0 mod_perl handler to run PSGI
7       application
8

SYNOPSIS

10         # in your httpd.conf
11         <Location />
12         SetHandler perl-script
13         PerlResponseHandler Plack::Handler::Apache2
14         PerlSetVar psgi_app /path/to/app.psgi
15         </Location>
16
17         # Optionally preload your apps in startup
18         PerlPostConfigRequire /etc/httpd/startup.pl
19
20       See "STARTUP FILE" for more details on writing a "startup.pl".
21

DESCRIPTION

23       This is a mod_perl handler module to run any PSGI application with
24       mod_perl on Apache 2.x.
25
26       If you want to run PSGI applications behind Apache instead of using
27       mod_perl, see Plack::Handler::FCGI to run with FastCGI, or use
28       standalone HTTP servers such as Starman or Starlet proxied with
29       mod_proxy.
30

CREATING CUSTOM HANDLER

32       If you want to create a custom handler that loads or creates PSGI
33       applications using other means than loading from ".psgi" files, you can
34       create your own handler class and use "call_app" class method to run
35       your application.
36
37         package My::ModPerl::Handler;
38         use Plack::Handler::Apache2;
39
40         sub get_app {
41           # magic!
42         }
43
44         sub handler {
45           my $r = shift;
46           my $app = get_app();
47           Plack::Handler::Apache2->call_app($r, $app);
48         }
49

STARTUP FILE

51       Here is an example "startup.pl" to preload PSGI applications:
52
53           #!/usr/bin/env perl
54
55           use strict;
56           use warnings;
57           use Apache2::ServerUtil ();
58
59           BEGIN {
60               return unless Apache2::ServerUtil::restart_count() > 1;
61
62               require lib;
63               lib->import('/path/to/my/perl/libs');
64
65               require Plack::Handler::Apache2;
66
67               my @psgis = ('/path/to/app1.psgi', '/path/to/app2.psgi');
68               foreach my $psgi (@psgis) {
69                   Plack::Handler::Apache2->preload($psgi);
70               }
71           }
72
73           1; # file must return true!
74
75       See
76       <http://perl.apache.org/docs/2.0/user/handlers/server.html#Startup_File>
77       for general information on the "startup.pl" file for preloading perl
78       modules and your apps.
79
80       Some things to keep in mind when writing this file:
81
82       ·   multiple init phases
83
84           You have to check that "restart_count" in Apache2::ServerUtil is ">
85           1", otherwise your app will load twice and the env vars you set
86           with PerlSetEnv
87           <http://perl.apache.org/docs/2.0/user/config/config.html#C_PerlSetEnv_>
88           will not be available when your app is loading the first time.
89
90           Use the example above as a template.
91
92       ·   @INC
93
94           The "startup.pl" file is a good place to add entries to your @INC.
95           Use lib to add entries, they can be in your app or ".psgi" as well,
96           but if your modules are in a local::lib or some such, you will need
97           to add the path for anything to load.
98
99           Alternately, if you follow the example above, you can use:
100
101               PerlSetEnv PERL5LIB /some/path
102
103           or
104
105               PerlSwitches -I/some/path
106
107           in your "httpd.conf", which will also work.
108
109       ·   loading errors
110
111           Any exceptions thrown in your "startup.pl" will stop Apache from
112           starting at all.
113
114           You probably don't want a stray syntax error to bring your whole
115           server down in a shared or development environment, in which case
116           it's a good idea to wrap the "preload" call in an eval, using
117           something like this:
118
119               require Plack::Handler::Apache2;
120
121               my @psgis = ('/path/to/app1.psgi', '/path/to/app2.psgi');
122
123               foreach my $psgi (@psgis) {
124                   eval {
125                       Plack::Handler::Apache2->preload($psgi); 1;
126                   } or do {
127                       my $error = $@ || 'Unknown Error';
128                       # STDERR goes to the error_log
129                       print STDERR "Failed to load psgi '$psgi': $error\n";
130                   };
131               }
132
133       ·   dynamically loaded modules
134
135           Some modules load their dependencies at runtime via e.g.
136           Class::Load. These modules will not get preloaded into your parent
137           process by just including the app/module you are using.
138
139           As an optimization, you can dump %INC from a request to see if you
140           are using any such modules and preload them in your "startup.pl".
141
142           Another method is dumping the difference between the %INC on
143           process start and process exit. You can use something like this to
144           accomplish this:
145
146               my $start_inc = { %INC };
147
148               END {
149                   my @m;
150                   foreach my $m (keys %INC) {
151                       push @m, $m unless exists $start_inc->{$m};
152                   }
153
154                   if (@m) {
155                       # STDERR goes to the error_log
156                       print STDERR "The following modules need to be preloaded:\n";
157                       print STDERR "$_\n" for @m;
158                   }
159               }
160

AUTHOR

162       Tatsuhiko Miyagawa
163

CONTRIBUTORS

165       Paul Driver
166
167       Ævar Arnfjörð Bjarmason
168
169       Rafael Kitover
170