Intro

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.

Problem

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 (par.pl 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 *
[download]

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 par.pl 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>
[download]

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
);
[download]

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

---

---

• Are you posting in the right place? Check out Where do I post X? to know for sure.
• Posts may use any of the Perl Monks Approved HTML tags. Currently these include the following:

  <code> <a> <b> <big> <blockquote> <br /> <dd> <dl> <dt> <em> <font> <h1> <h2> <h3> <h4> <h5> <h6> <hr /> <i> <li> <nbsp> <ol> <p> <small> <strike> <strong> <sub> <sup> <table> <td> <th> <tr> <tt> <u> <ul>

• Snippets of code should be wrapped in <code> tags not <pre> tags. In fact, <pre> tags should generally be avoided. If they must be used, extreme care should be taken to ensure that their contents do not have long lines (<70 chars), in order to prevent horizontal scrolling (and possible janitor intervention).
• Want more info? How to link or How to display code and escape characters are good places to start.