Plack::Handler::Apache2(3pm)

NAME
Plack::Handler::Apache2 - Apache 2.0 mod_perl handler to run PSGI application

SYNOPSIS
  # in your httpd.conf
  <Location />
  SetHandler perl-script
  PerlResponseHandler Plack::Handler::Apache2
  PerlSetVar psgi_app /path/to/app.psgi
  </Location>

  # Optionally preload your apps in startup
  PerlPostConfigRequire /etc/httpd/startup.pl

See "STARTUP FILE" for more details on writing a "startup.pl".

DESCRIPTION
This is a mod_perl handler module to run any PSGI application with mod_perl on Apache 2.x.

If you want to run PSGI applications behind Apache instead of using mod_perl, see Plack::Handler::FCGI to run with FastCGI, or use standalone HTTP servers such as Starman or Starlet proxied with mod_proxy.

CREATING CUSTOM HANDLER
If you want to create a custom handler that loads or creates PSGI applications using other means than loading from ".psgi" files, you can create your own handler class and use "call_app" class method to run your application.

  package My::ModPerl::Handler;
  use Plack::Handler::Apache2;

  sub get_app {
    # magic!
  }

  sub handler {
    my $r = shift;
    my $app = get_app();
    Plack::Handler::Apache2->call_app($r, $app);
  }

STARTUP FILE
Here is an example "startup.pl" to preload PSGI applications:

    #!/usr/bin/env perl

    use strict;
    use warnings;
    use Apache2::ServerUtil ();

    BEGIN {
        return unless Apache2::ServerUtil::restart_count() > 1;

        require lib;
        lib->import('/path/to/my/perl/libs');

        require Plack::Handler::Apache2;

        my @psgis = ('/path/to/app1.psgi', '/path/to/app2.psgi');
        foreach my $psgi (@psgis) {
            Plack::Handler::Apache2->preload($psgi);
        }
    }

    1; # file must return true!

See <http://perl.apache.org/docs/2.0/user/handlers/server.html#Startup_File> for general information on the "startup.pl" file for preloading perl modules and your apps.

Some things to keep in mind when writing this file:

•   multiple init phases

    You have to check that "restart_count" in Apache2::ServerUtil is "> 1", otherwise your app will load twice and the env vars you set with PerlSetEnv <http://perl.apache.org/docs/2.0/user/config/config.html#C_PerlSetEnv_> will not be available when your app is loading the first time.

    Use the example above as a template.

•   @INC

    The "startup.pl" file is a good place to add entries to your @INC. Use lib to add entries, they can be in your app or ".psgi" as well, but if your modules are in a local::lib or some such, you will need to add the path for anything to load.

    Alternately, if you follow the example above, you can use:

        PerlSetEnv PERL5LIB /some/path

    or

        PerlSwitches -I/some/path

    in your "httpd.conf", which will also work.

•   loading errors

    Any exceptions thrown in your "startup.pl" will stop Apache from starting at all.

    You probably don't want a stray syntax error to bring your whole server down in a shared or development environment, in which case it's a good idea to wrap the "preload" call in an eval, using something like this:

        require Plack::Handler::Apache2;

        my @psgis = ('/path/to/app1.psgi', '/path/to/app2.psgi');

        foreach my $psgi (@psgis) {
            eval {
                Plack::Handler::Apache2->preload($psgi); 1;
            } or do {
                my $error = $@ || 'Unknown Error';
                # STDERR goes to the error_log
                print STDERR "Failed to load psgi '$psgi': $error\n";
            };
        }

•   dynamically loaded modules

    Some modules load their dependencies at runtime via e.g. Class::Load. These modules will not get preloaded into your parent process by just including the app/module you are using.

    As an optimization, you can dump %INC from a request to see if you are using any such modules and preload them in your "startup.pl".

    Another method is dumping the difference between the %INC on process start and process exit. You can use something like this to accomplish this:

        my $start_inc = { %INC };

        END {
            my @m;
            foreach my $m (keys %INC) {
                push @m, $m unless exists $start_inc->{$m};
            }

            if (@m) {
                # STDERR goes to the error_log
                print STDERR "The following modules need to be preloaded:\n";
                print STDERR "$_\n" for @m;
            }
        }

AUTHOR
Tatsuhiko Miyagawa

CONTRIBUTORS
Paul Driver

Ævar Arnfjörð Bjarmason

Rafael Kitover

SEE ALSO
Plack