Beefy Boxes and Bandwidth Generously Provided by pair Networks
No such thing as a small change

PAR / Apache::PAR Test Drive

by trs80 (Priest)
on Aug 14, 2003 at 20:45 UTC ( #284001=perlmeditation: print w/replies, xml ) Need Help??


I got bitten this week with the Better Way(tm) bug after a clients server had to be swapped out to a new system. I realized that I really didn't want to have to remember and do all the hand (re)placement of files in all the various directories like I had in the past. I remembered hearing and reading a little bit about PAR and thought I would give it a try.

PAR stands for Perl ARchive. A PAR is a zip file of your application and/or a stand alone executable. When used in conjunction with Apache::PAR it mimics in some ways how a Java WAR (web archive) file works.

This is a summary of my inital experience with the above modules. PAR and especially Apache::PAR are emerging Perl tools that are still improving so this document maybe out of date sooner rather then later. Anyway on to the fun.


Current application deployment model was less then perfect, relied on installing modules and scripts in several directories that might not be available on server that are not owned or operated by my client.

Paritial Cure

Put as much of the application components as possible into a single directory structure and turn that into a PAR file, which in turn can be used by Apache::PAR (Apache::PAR only works on a mod_perl enabled server)

The Process

The first step is good development practice regardless of whether you want to use PAR or not, but it is required if you want to use PAR. Which is move all your files into a single directory tree. The PAR documentation outlines the directories followed by default (you can add anything you like beyond the *magic* ones), these are important because they will be auto included in your @INC (lib location), or used as the default location of scripts. See PAR docs for complete details.

In my case I didn't want to disrupt my current development model in case something went horribly wrong so I created a script to pull in my existing files (or update in the future) to create my par and then copy it to its final location. The final location is something that you will want to give some thought to since the web server will need to access it, but you don't want to make it available for download most likely.

So what you will wind up with is something like this:

directory my-app/lib all the module files that are unique to your project and under your control*. This is auto included in @INC at run time via the PAR apps
directory my-app/script Stick all the perl apps you want to run from within PAR in here. The PAR utilities ( and family) will automatically look for files here if you attempt to execute a script without a path. see below
directory my-app/htdocs This is a directory where you store your web pages (and scripts if so inclined). see Apache::PAR docs
file my-app/web.conf This file contains additional directives to be passed to the Apache server when used in conjunction with Apache::PAR. You can put this under sub directories, the Apache::PAR module will find it.

Once you have your files in place you can create the PAR itself. There are a number of ways you can do this and various parameters you can pass to get different files or locations included. My needs and personal taste allowed for:
zip -r my-app.par *

As you might notice a PAR is really "just" a zip file and can be created with the zip utility. If you need to include core modules or CPAN modules outside of your directory tree you will need to use the utility to create you PAR file, again the documentation covers this in detail.

Add Apache::PAR to the Mix

Now that we have the PAR file we can add it as a self contained unit to Apache with just a copy of changes to the httpd.conf file or your perl startup file**.

See the Apache;:PAR docs for details on this. Basically I did this:

1) Inside of my web.conf file I put:
Alias /my-app/ ##PARFILE##/ <Location /my-app> Options +ExecCGI # example directive # (More Apache directives go here) # see docs for more info PerlHandler Apache::PAR::Static # if you have static files in your + PAR file # PerlHandler Apache::PAR::Registry # PerlHandler Apache::PAR::PerlRun </Location>
The ##PARFILE## is replaced with the name of par file it found the web.conf in. See below for issues with Embperl pages and an alternate work around. 2) Inside of my perl startup file I added:
use Apache::PAR qw( /usr/local/apache/par );
That is all that is required for the magic to happen. Notice the location is a directory and not a file. You can specify a single .par file if you need to, you specific a directory all .par files will be included. The 'Alias' directive is important because it tells

The process above works fine for Apache::Registry or Apache::PerlRun based projects, but if you use Embperl, Apache::ASP, Mason , etc. you run into a problem since those apps are not PAR aware. At the time of this writing there is a module available to allow for Mason to be used in a PAR environment. I contacted the author in regards to the other template/framework modules and he happened to be working on the problem already. In the mean time I put together a quick hack to replace Apache::PAR with a module called Apache::PARTemp that will extract your PAR files into a directory on load. This allows me to package up my Embperl based projects into a single file and have them extracted to the directory of my choice when Apache starts up. My workaround was more proof of concept then production grade, but the future looks bright.

Apache::PAR will hopefully open some doors for distributing Perl based web applications with less fuss, have fun.

* There is a way to pull in existing modules, but I am not covering that here. This node assumes you are working on systems with a full install of Perl and will be sharing modules with

** A perl startup file is a file that contains perl code indicating addtional configuration options for Apache, two of its benefit are. 1) it is a Perl script and not Apache directive/conf markup 2) it lives outside of the httpd.conf

Replies are listed 'Best First'.
Re: PAR / Apache::PAR Test Drive
by liz (Monsignor) on Aug 15, 2003 at 09:27 UTC
    ...I created a script to pull in my existing files (or update in the future) to create my par..

    Is there a particular reason why you didn't use (symbolic) links to set up your shadow tree at the final location? Copying files always has the danger of getting out of sync, whereas links do not have that problem. Unless you purposely want to be able to get out of sync.

    Just wondering.


      There are dozens of methods/techniques that could be used, copying to a new clean physical directory was mine. I can now symlink the old locations back to the new content if I want to use the packages outside of a PAR. Furthermore I think it is better to use a physical location when explaining a concept that might be used on platforms that don't support symbolic links. But at the time of the writing and creating my script it simple made sense to me, but I encourage others to do what makes sense for their environment/mindset.
Re: PAR / Apache::PAR Test Drive
by techy (Scribe) on Sep 10, 2003 at 01:20 UTC

    First, thanks for the writeup here on PM and for your help with Apache::PAR!

    As of Apache::PAR 0.30, the inability to use templating modules has been addressed in a manner similar to what you describe above with Apache::PARTemp. To use this feature, set an environment variable or mod_perl var to ##UNPACKDIR## in your web.conf file. This will enable content unpacking. For instance (inside a web.conf)

    PerlSetEnv FooTemplateDir ##UNPACKDIR##/templates

    will set an environment variable of FooTemplateDir to a subdirectory under the location where the content is unpacked into during Apache startup (a subdirectory under platform specify temporary directory unless changed through the Apache config.) There are also options to control the location of unpacking, the ability to reload changed archives, etc. See the Apache::PAR documentation for more information.

    0.31, when it is released, should expand on this ability by allowing only parts of an archive to be unpacked, as well as some other features related to reloading archives.

    Also, I haven't yet worked on it, but am planning a new module to allow the use of PAR archives from other web servers (as CGI, or maybe FastCGI etc).

    If anyone has additional suggestions for new features, or would like to report a problem, please let me know.



Log In?

What's my password?
Create A New User
Node Status?
node history
Node Type: perlmeditation [id://284001]
Approved by Corion
Front-paged by Corion
and the web crawler heard nothing...

How do I use this? | Other CB clients
Other Users?
Others lurking in the Monastery: (8)
As of 2020-08-12 16:26 GMT
Find Nodes?
    Voting Booth?
    Which rocket would you take to Mars?

    Results (66 votes). Check out past polls.