Quick Navigator

Search Site

Unix VPS
A - Starter
B - Basic
C - Preferred
D - Commercial
MPS - Dedicated
Previous VPSs
* Sign Up! *

Contact Us
Online Help
Domain Status
Man Pages

Virtual Servers

Topology Map

Server Agreement
Year 2038

USA Flag



Man Pages

Manual Reference Pages  -  PLACK::HANDLER::APACHE2 (3)

.ds Aq ’


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



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

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

See STARTUP FILE for more details on writing a


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.


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);


Here is an example 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;

        require Plack::Handler::Apache2;

        my @psgis = (/path/to/app1.psgi, /path/to/app2.psgi);
        foreach my $psgi (@psgis) {

    1; # file must return true!

See <> for general information on the file for preloading perl modules and your apps.

Some things to keep in mind when writing this file:
o 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 <> will not be available when your app is loading the first time.

Use the example above as a template.

o @INC

The 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


    PerlSwitches -I/some/path

in your httpd.conf, which will also work.

o loading errors

Any exceptions thrown in your 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";

o 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

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;


Tatsuhiko Miyagawa


Paul Driver

AEvar Arnfjoerd` Bjarmason

Rafael Kitover


Search for    or go to Top of page |  Section 3 |  Main Index

perl v5.20.3 PLACK::HANDLER::APACHE2 (3) 2015-06-03

Powered by GSP Visit the GSP FreeBSD Man Page Interface.
Output converted with manServer 1.07.