Installing PET

PET needs a decent version of Perl -- basically anything from 5.6+ -- and Linux.  There is no Win32 version (yet).  PET is developed on Fedora, but we had succesfully run installations on Debian and Darwin -- basically most Linux distributions with Perl and Apache shall have no compatibility problems, where the modules PET uses can be deployed.

In order to get PET, currenntly you need a subversion client (svn).  You can get it from http://subversion.tigris.org, but it is very much likely that your Linux distribution has pre-built binaries (e.g.  RPMs) somewhere : for example on Fedora it should be enought that you execute a “yum install subversion” command.  Soon we will be distributing PET via CPAN (http://www.cpan.org).

First, you have to install -- and configure -- Apache.  We cannot go into the details here -- if you cannot install a webserver, you are most likely cannot use/install PET, either (at least at this stage of the development of PET).

(Note : this chapter discusses an install using Apache as a webserver.  However, PET can be interfaced to many other webservers -- we chose Apache as it is the most widely used webserver currently.)

You have to have mod_proxy, mod_rewrite and mod_fastcgi in order to interface (Apache) to the PET server.  Most modern Linux distributions come with Apache and the first two of these three modules.  Make sure you have them.  You also have to install mod_fastcgi, which you can get from http://www.fastcgi.com if you cannot get a binary for your system.  Note that PET runs in FastCGI external(!) mode.

After you have your webserver running and using these modules, you have to configure a virtualhost and install/configure PET.  From now on we suppose that this virtualhost is at http://www.mydomain.com.

Chose a user

First, chose or create a user you will be running PET under.  We assume from now on that this user will be the user “www” with group “www”.  We also assume that the home of this user is at :

/home/www

Creating the directory structure

First, create the directories!

Become the user you will be running PET under :

su www

Enter the user’s homedir :

cd /home/www

Create the standard PET directories :

mkdir www.mydomain.com
cd www.mydomain.com
mkdir logs apilogs cache session modules html compiled

Configure Apache

Now configure Apache!  Edit your httpd.conf file (it is usually under /etc/httpd/conf/ or /usr/local/apache/conf, but it may vary).

Create the virtualhost as (something like)

FastCgiExternalServer /mypet -socket /home/www/www.mydomain.com/fcgi.sock -pass-header Authorization
<VirtualHost www.mydomain.com:80>
    DocumentRoot    /home/www/www.mydomain.com/html
    ErrorLog    /home/www/www.mydomain.com/logs

    RewriteEngine On
    Alias   /mypet  /mypet

    RewriteCond %{REQUEST_URI}  \.pet   [OR]
    RewriteCond %{REQUEST_URI}  /$
    RewriteRule ^(.*)$  http://www.mydomain.com:80/mypet [PT,QSA]
</VirtualHost>

You also have to set up the PET server, so you will have to have one more line in your httpd.conf later.  However, we skip that part for now!  Save your config and restart your webserver!

Note : you have to have mod_proxy and mod_rewrite in your httpd (Apache), either static (compiled in) or dynamic (loaded as a DSO, e.g.  LoadModule rewrite_module modules/mod_rewrite.so, LoadModule proxy_module modules/mod_proxy.so).  We also consider that you use VirtualHosts and your webserver is bound to port 80.

Let’s test what we have so far!

Enter the documentroot :

cd /home/www/www.mydomain.com/html

Using your favourite text editor, create an index file, say index.html ! Put “Hello, World!” into it.

Now point your browser to : http://www.mydomain.com/index.html “Hello, World!” should be displayed.

Setup PET as an external FastCGI applic ation

Now that the virtualhost is correctly set up, let’s do the real work and set up PET!

Enter the “modules” directory you have just created, and check out PET

svn co svn://ns1.hunreg.com/PET/trunk ./ (Obviously, you must already have SVN installed at this point.)

SVN will create and fetch the directory PET for you now.

PET by default is an external application, which runs as a daemon (similar to Tomcat for Java or ZOPE for Python.)

Copying the glue-scripts

In order to run PET, you need a PET “glue” script.  You can find to of those in PET/scripts : pet_run_cli and pet_run_fcgiprocmanager.  Copy them to your path, e.g.  /usr/sbin, or even /usr/bin.

Enter your BASEPATH

cd /home/www/www.mydomain.com

Copy the gluescript(s) to your PATH

cp modules/PET/scripts/pet_run_* /usr/sbin/

Note : you do not have to use /usr/sbin/, but we will assume now that you do that.  Actually you can even keep them where you have checked them out -- keeping them in the PATH only makes your life easier.

Creating a config (global.conf)

PET needs a config file so that it knows what port/socket it should bind to, and so on.  PET has many configuration parameters, so for the time being, simply copy the file from PET/etc/global.conf-sample to your $BASEPATH as global.conf :

cp modules/PET/etc/global.conf-sample ./global.conf

Note : this implies that we will be using /tmp/pet.sock as a FastCGI socket for the PET external FastCGI server.

Creating an initscript

This is probably the hardest thing to do : you will have to create a script that start and stops the application server.  (If you have more than one instances of PET running on the same server, then you will have to have as much initscripts as installations.)  Writing an initscript is not very hard, but we cannot go into details here.  You will find some sample initscripts in PET/misc/, find the one that suits your operating system and copy it to your initscript directory (usually /etc/init.d/).

For example, on Fedora (RedHat) you would do this :

cp modules/PET/etc/init-fc-sample /etc/init.d/petdemo
chmod a+x /etc/init.d/petdemo

Note that you have to set your application’s directory in the initscript!

If you know Perl rather well, and you have some Linux/UNIX system administration skills, the above description is probably a bit too lengthy for you.  Here is a smaller, less basic description on how to install PET!

1.  Get a user you will be runing PET under ($USER)

2.  Create a directory in $USERHOME as $YOURDOMAIN (that will be $BASEPATH), or some other place owned by $USER

3.  Create directories in $BASEPATH as logs, apilogs, sessions, cache, html, compiled, modules.

4.  Configure a virtualhost in Apache so that it points to $BASEPATH/html

5.  Check out PET tp $BASEPATH/modules/ ($DOCUMENTROOT)

6.  Copy the glue scripts from PET/misc to your PATH

7.  Create an initscript ....

8.  Add a global.conf ...

9.  Configure Apache to have a virtualhost that points to $DOCUMENTROOT, and redirect all “.pet” requests to socket ...

10.  Start the initscript ...

Here is a Hungarian presentation that explains what PET is good for.

Here is a startup tutorial: getting PET, installing, writing your first <Hello, World!> program and so on...

All directories are relative to $BASEPATH (also called $BASEDIR).  We will reference this directoryes simply using their names (e.g.  “html/”).

All PET templates are stored in *html/*.  A file must have the .pet extension in order to be parseable by PET.  We use the Tempalte Toolkit (also know as TT2 or Template.pm) to parse these files.  See also: <config parameters>.

The modules/ directory stores your custom Perl packages.

There are global and local parameters.  Global.conf defines site-wide parameters, while local.conf overrides them on a per-file basis.  [ FIXME: we might use per-directory settings later on.  ] Some config parameters can also be overwritten using the PET::Dispatcher::setConf() method.

See: Config