The Penguin Greetings Installation Guide
Edouard Lagache

Copyright © 2003-2005 (Penguin Greetings 1.0.0 edition)

A introduction to installing the Penguin Greetings web-based ecards system.

Table of Contents:

  1. Overview of Penguin Greetings
  2. Penguin Greetings Legalese
  3. Quickie recipe for the impatient
  4. Setting up environment
  5. Installing the application
  6. Creating Databases and starting Penguin Greetings
  7. Installing secondary ecard sites
  8. Troubleshooting
Overview of Penguin Greetings

Penguin Greetings is a Perl CGI based system for implementing web-based ecards.  It is also a complete "drop in" ecards solution for any web site which includes 240+ ecards for many occasions that are similar in style and taste to Apple's iCards content.   Penguin Greetings uses HTML templates that contain embedded Perl expressions to represent the cards and the web-pages that users need to fill out in order to send an ecard.  Penguin Greetings is able to send MIME multipart HTML messages, so users with rich-text supporting email clients can read their cards directly.  Penguin Greetings also supports ecard scheduling so that cards can be sent on a special day such as someone's birthday.

The Perl CGI script can now be run as a persistent server by using the SpeedyCGI application.  This avoids the overhead of launching Perl with each new request and allows for greater control of how Penguin Greetings is executed on the server.

Penguin Greetings Legalese

Penguin Greetings is copyright © Edouard Lagache, 2003-2005. Penguin Greetings is released under the GNU General Public License, Version 2. For more information, see the COPYING file included with this software or visit: http://www.gnu.org/copyleft/gpl.html

The artistic content included with this software is also copyright © Edouard Lagache, 2003-2005. It is released under the Design Science License. For more information, see the DSL.txt file included with the software or visit: http://www.dsl.org/copyleft/.

Powered by Penguin Greetings web badge

If you use Penguin Greetings in your own web cards application.  Please give credit were credit is due by displaying the following web badge or something equivalent on your web site:

Powered by Penguin Greetings

There are now quite a few different badges included in Penguin Greetings with the various secondary ecard sites, so take a look if you want something different.  Better still, if you make a nicer web badge, please share it with me so that I can spread the wealth! :-)

[Table of Contents]
Quickie recipe for the impatient

New to version 0.9.0 of Penguin Greetings is a greatly simplified installation process.  The new installer internalizes many tasks including the installation of the external CPAN modules.  Still, Penguin Greetings is a complex application with multiple programs and configuration files.  So here is a Geeker's Digest version of the install.  Hyperlinks are provided to the "gotchas" and remember ... the mistakes you make are your own!
  [Table of Contents]
Setting up environment

Penguin Greetings uses a large number of Perl modules in order simplify its work and to avoid unexpected code conflicts.  Many of the modules it uses are included with Perl 5.8.x.  While the Penguin Greetings programs do not depend on anything internal to Perl 5.8.x, unless you are desperately clinging to an older version of Perl for some reason, you'll be much better off to upgrade to Perl 5.8.  The instructions on installing Perl can be found here.  If you are using an operating system distribution such as RedHat, Mandrake, Caldera, or FreeBSD, there may be other mechanisms for installing the latest version of Perl which may (or may not!) be more convenient.

In addition to the modules that "ship" with Perl 5.8.0, you will need the following modules:  Log::Dispatch, MIME::Lite,Apache::Htpasswd,  Date::Pcalc,Config::General, String::Checker, Digest::MD5, I18N::AcceptLanguage, and Embperl .  If you wish to use SpeedyCGI, you'll need to also install CGI::SpeedyCGI. The Penguin Greetings installer will now install all these modules for you, but you may wish to do this "manually."  Instructions on how to download and install these modules can be found here. 

Even if you choose to allow the Penguin Greetings installer to handle the module installation, you may wish to set up the CPAN module beforehand to configure the required disk caches and so on.  This can be done with a command like the following  (as super-user or root):

    perl -MCPAN -e 'install CPAN'

For more information on using the CPAN module see its documentation here.

The perl module Embperl is not the older module HTML::Embperl but new beta 2.0 version.  You can obtain Embperl from its website as part of the Perl/Apache integration project: http://perl.apache.org/embperl/ or from CPAN.  While getting Embperl to run with Apache's mod_perl can be tricky, this capability isn't used by Penguin Greetings.  Since Penguin Greetings runs for the moment as a CGI script, simply installing the Embperl module will do the trick. 

In addition, The String::Checker module will give a warning if you don't install the Date::Manip module.  However, it will install without that module and Penguin Greetings doesn't use it.  So it is up to you if want to install yet another Perl module.

New to version-0.9.9 of Penguin Greetings is support of the alternative Embedded Perl within HTML framework: HTML::Mason.  The new secondary ecard site: Savoring the sights of Seattle (PgSeattle) uses Mason instead of Embperl for it's templates.  However, HTML::Mason is not installed by Install.PL.  If you which to use that site, you'll need to install Mason "manually" (say by using CPAN installer suggested above.)  Version-0.9.9 also changes the way four of the five bilingual secondary ecard sites are localized by using the Perl module: Locale::Maketext.  This is now included in Perl and can be installed using the CPAN installer for older versions of Perl.

Once you have a complete Perl environment, you can begin creating the environment for running Penguin Greetings.  To keep things secure and tidy, Penguin Greetings is designed so that most of the ecard content is kept separate from your web server and your system applications.  The location of most files can be defined in the configuration file so that you could scatter files all over the place if you like. Practically speaking through, you'll want to keep all Penguin Greeting files in either one or two locations.  You must create a new user pgreet on your system and create a directory with access controls based on that user.  You can use variations on the following two commands on most UNIX systems to accomplish this trick.  Of course, adjust as needed for your system.

groupadd pgreet

useradd -g pgreet -c "Penguin Greetings Agent" -s /bin/false -d /home/pgreet pgreet

It is probably wise to assign a group and user ID number rather than simply allowing the system to pick the next available ID numbers. For that reason, a GUI user manager such as Linuxconf may be more convenient.  Whatever you do, record the user and group ID numbers as you need to add this information to the pgreet.conf file.  The installer will do this for you but only if you remember what they are! :-)

The exact location of the pgreet directory depends on how your organize your system.  A case can be made for placing it under the equivalent of /usr/local/share.  However, the security conscious may prefer to have it off of the /home directory.  Those with a low regard of such things may wish to drop it somewhere in the /var partition.  You will normally want to create three subdirectories in the pgreet account directory: conf, data, and card_queue.  Each directory should be owned by pgreet and have chmod recursive permissions of 644.  If you prefer, you can also put the HTML related directories  images and templates in this same account directory, but it is probably more practical to create a new pgreet subdirectory off of your HTML document tree.
 
[Table of Contents]
Installing the application

At this point, if you haven't done so already, you should download and unpack the pgreet-X.X.X.tar.gz distribution.  The next task is to move the files to their required location and update configuration files appropriately.  The new installer with Penguin Greetings (Install.PL) will take care of localizing files, adjusting your configuration file (at least approximately) and moving the files to the right location.   It has a caching system so that once you install Penguin Greetings, you'll be able to install updates easily.

To install Penguin Greetings, you'll need the to provide the following items to the installer, so you may wish to keep that information handy:
Running the installer is as simple as involving it.  For an installation on a real system, you'll need to run it as root, via sudo or some other mechanism.  The first time it is run, it will create a file called: installer.cache.  Subsequent runs it will use these values as default.  So to keep your settings when upgrading Penguin Greetings, simply copy this file to the new distribution and it will automatically retain the same defaults. Unfortunately, Install.PL has been updated yet again for version 0.9.0, so installer.cache files made by earlier versions will not work.  Install.PL will detect old installer.cache files and give the user the option to either delete the file and start over or halt the installation to save the file.   A sample install session is shown below:

canebas.org [838]% sudo ./Install.PL
    Penguin Greetings installer - version: 0.9.5

Should installer fetch Perl modules directly from CPAN now? ([Y]es/No): y
Launching CPAN installer

CPAN: Storable loaded ok
Going to read /home/users/elagache/.cpan/Metadata
  Database was generated on Sat, 16 Aug 2003 15:44:33 GMT
CPAN: LWP::UserAgent loaded ok
Fetching with LWP:
  ftp://cpan.nas.nasa.gov/pub/perl/CPAN/authors/01mailrc.txt.gz
Going to read /home/users/elagache/.cpan/sources/authors/01mailrc.txt.gz
CPAN: Compress::Zlib loaded ok
Fetching with LWP:
  ftp://cpan.nas.nasa.gov/pub/perl/CPAN/modules/02packages.details.txt.gz
Going to read /home/users/elagache/.cpan/sources/modules/02packages.details.txt.gz
  Database was generated on Mon, 18 Aug 2003 16:45:03 GMT
Fetching with LWP:
  ftp://cpan.nas.nasa.gov/pub/perl/CPAN/modules/03modlist.data.gz
Going to read /home/users/elagache/.cpan/sources/modules/03modlist.data.gz
Going to write /home/users/elagache/.cpan/Metadata
Apache::Htpasswd is up to date.
CGI is up to date.
CGI::Carp is up to date.
CGI::SpeedyCGI is up to date.
Config::General is up to date.
Date::Pcalc is up to date.
Digest::MD5 is up to date.
Embperl is up to date.
MIME::Lite is up to date.
String::Checker is up to date.


Resuming Installation of Penguin Greetings . . .
 Checking for required modules
- Found: Config::General
- Found: CGI
- Found: CGI::Carp
- Found: MIME::Lite
- Found: Apache::Htpasswd
- Found: Date:Pcalc
- Found: Embperl
- Found: String::Checker
- Found: Digest::MD5
- Found: I18N::AcceptLanguage
- Found: Pgreet
Do you wish to install the Greeting card image directory([Y]es/No)?
Do you wish to install the Penguin Greetings Speedy CGI script([Y]es/No)?

Please enter the location of the following files and directories
 Greeting card image directory [none]: /home/httpd/htdocs/pgreet
 Penguin Greetings CGI script [/home/httpd/cgi-bin]:
 Penguin Greetings Template test tool [/usr/local/bin]:
 Penguin Greetings card configuration file [none]: /home/agent-workspace/pgreet/conf
 Penguin Greetings main configuration file [none]: /home/agent-workspace/pgreet/conf
 Penguin Greetings system daemon [/usr/local/sbin]:
 PgTemplateTest configuration file [none]: /home/agent-workspace/pgreet/conf
 Penguin Greetings Speedy CGI script [/home/httpd/cgi-bin]:
 Penguin Greetings database init tool [/usr/local/bin]:
 Penguin Greetings HTML template files [none]: /home/httpd/htdocs/pgreet

Please provide the following information for your installation:

 full hostname of your server (e.g. www.your-host-name.net)
 []: www.canebas.org
 Name of your SMTP server
 [localhost]: smtp.comcast.net
 The group ID number (not name) of the pgreet group on your system
 []: 230
 Path on your server to HTML data (images and templates) for Penguin Greetings
 [/home/httpd/htdocs/pgreet]:
 The user ID number (not name) of the pgreet user on your system
 []: 523
 Path on your server to Pgreet data and configuration directories
 [/home/agent-workspace/pgreet]:
 Complete path to Penguin Greetings Configuration file (including filename)
 []: /home/agent-workspace/pgreet/conf/pgreet.conf

Generating/Localizing files ...
 Generating/Localizing file: pgreet.pl.scgi
 Generating/Localizing file: pgreet.pl.cgi
 Generating/Localizing file: PgTemplateTest.pl
 Generating/Localizing file: pgreet.conf
 Generating/Localizing file: PgreetDBinit.pl
 Generating/Localizing file: pgreetd.pl

Installing files ...
 Installing Greeting card image directory
 Installing Penguin Greetings CGI script
 Installing Penguin Greetings Template test tool
 Installing Penguin Greetings card configuration file
 Installing Penguin Greetings main configuration file
 Installing Penguin Greetings system daemon
 Installing PgTemplateTest configuration file
 Installing Penguin Greetings Speedy CGI script
 Installing Penguin Greetings database init tool
 Installing Penguin Greetings HTML template files
canebas.org [358]%

Install.PL has four command line options explained below:

-c
 Do a clean install, erase installer.cache and start over.
-d
 Do a dry-run install, ask questions and generate cache, but do not actually install any files.
-f
 Force install, skip asking for locations but use locations in installer.cache.
-h
 Give a usage/help summary.
-i
 Ignore "optional" files in installation.  The optional files right now are the graphical images (for development and those who just wish to install the software components.)
-o
 Overwrite all files no matter how the the installer is configured (option provided mostly for development.)  See section on backing up existing configuration files below.


In general, Install.PL takes no prisoners (i.e. doesn't save any old version of files that it installs :-).)  This could be disastrous for any customized configuration files.  So as of version 0.8.0, Install.PL includes support for the backup options available in the standard BSD install program.  As shipped with Penguin Greetings, only the conf directory is thus protected.  Any file found already existing will be backed up with a suffix ~1~ and so on.  Since the configuration files are evolving on Penguin Greetings, it isn't always possible to reuse an existing configuration file.  If you are upgrading, see the upgrade notes to see how to convert your existing configuration files.

Version 0.8.2 added support for SpeedyCGI.  If desired,The SpeedyCGI version of pgreet.pl.cgi is automatically generated by the installer and is called pgreet.pl.scgi. 

If you are running a LINUX or other System-V UNIX systems, you can use the following files to provide an easier startup capability.  These files are not automatically installed for you by Install.PL.

For UNIX system-V startup scripts and log rotation (note changed filenames)
Files
 Copy To:
 Directory
pgreetd.sys5.sh =>
 /etc/rc.d/init.d/pgreetd
pgreetd.logrotate =>
 /etc/logrotate.d/pgreetd

The owner and permissions on the file will depend to some extend on your local setup.  The Install.PL script has reasonable defaults for LINUX and Apache.  All of the data files should be owned by pgreet with chmod permissions of 644.  The Perl CGI script permissions will depend on your server.  On Apache for example, the correct owner is the apache user.  The pgreetd daemon and associated System-V initialization files should be owned by root.

As always, adjust to local UNIX tastes!

The installer now modifies the configuration files so that Penguin Greetings should start up without any further tinkering with those files.  However, it is prudent to check the contents of the configuration files to make sure all is correct.  At the very least, run the Configuration file testing tool PgreetConfTest on your pgreet.conf file.  The PgreetConfTest program runs the same sanity checks that the Penguin Greetings daemon pgreetd runs.  Fixing any errors found by PgreetConfTest will spare you chasing down some unexpected terminations of pgreetd.  For more information on the configuration files and PgreetConfTest, see the Penguin Greetings Administrators' Guide.

  [Table of Contents]

Creating Databases and starting Penguin Greetings

At this point you can start testing your applications to see if they work correctly.  Try connecting to pgreet.pl.cgi to see if this works correctly.  The URL should be something like http://www.your-server.org/cgi-bin/pgreet.pl.cgi.  If it fails, look at your server's error log for the cause.  The pgreet.pl.cgi has extensive error reporting so that you should get a precise message (unless it is a just plain bug! ) 

New to version 0.8.8 is a separate utility to initialize the databases used by Penguin Greetings.  Before actually attempting to send a card you must create the databases with the following command:

sudo PgreetDBinit path_to_your_pgreet_data_directory

The PgreetDBinit utility must be run as root (again via sudo or whatnot) so that it can set the file permissions correctly.  Note the path above must be complete (including the final directory data in the path.)  There are some options of PgreetDBinit that can be used to customize your installation.  See the PgreetDBinit man page for more details.

Once you get to this point that you can connect to it, you can go ahead and actually send a ecard.  However, nothing will happen until after the daemon is started.  Instead all the state files will wait to be processed.  You can manually start pgreetd for a first trial, but you'll probably want to place an entry in your rc.local file or equivalent if you intend to keep using the program.  The System-V startup script is very convenient for debugging Penguin Greetings, but not necessary unless you want the security advantage of a quick start and stop tool.  If you want to use the System-V script, don't forget to add it to your system using chkconfig:

chkconfig pgreetd add
chkconfig pgreetd on

As usual, you may need to adjust the setting for the System-V initialization script to work correctly with chkconfig on your system.

If you have problems keeping pgreetd running, check your syslog messages file and/or pgreet.log file.

When both pgreetd and pgreet.pl.cgi are running, send yourself a Penguin Greeting and see if it makes it to your email box!

  [Table of Contents]
Installing secondary ecard sites

As of version 0.9.9, Penguin Greetings includes the templates of six secondary ecard sites which are located in the card_sites directory of the source code distribution.:

  1. PgCamel - The Penguin Greetings Camel Collection
  2. PgSaint - The Penguin Greetings Holy cards Collection
  3. PgXmas - The Penguin Greetings Christmas card Collection
  4. PgPoppy - The Penguin Greetings California Poppy Collection
  5. Pg4Seasons - The Penguin Greetings Four Seasons Collection.
  6. PgSeattle - Savoring the sights of Seattle Collection (Implemented using HTML::Mason)
All these sites but the first include a French translation.

These sites are intended more as examples of possible sites than for use as is.  All the content (in English) of four of the six sites is already included in the primary ecard site, so users will not gain any card content by installing secondary sites (except for the French translations.)  The two remaining sites (Four Seasons and Seattle) contain material unique to those secondary sites.  However, any can be used either as a secondary ecard site or as an alternative primary site.  In either case, the configuration files must be edited to fit your local conditions.  To use a secondary site as a replacement for the primary ecard site, you'll need to replace the cards.conf file with the file from the secondary ecard site and reconcile the default site configuration file pgreet.conf with the secondary ecard site configuration file (PgCamel.conf, PgSaint.conf, PgXmas.conf, PgPoppy.conf, or Pg4Seasons.conf).  This usually means just changing the location of the directories of configuration files, data files, and HTML related materials to the right locations on your system.  At this time, multiple language support is only available for secondary ecard site.  If you want to only run a single multilingual site, simply ignore the primary site or perhaps put a status page only in the place of the primary site.

To use a secondary site as is, one can simply uncomment out the secondary secondary ecard site entry in the primary configuration file pgreet.conf, change the configuration files (PgCamel.conf, PgSaint.conf, PgXmas.conf, PgPoppy.conf, Pg4Seasons.conf, or PgSeattle.conf) to point to your local directories, and then use the bash script install_site.sh to copy the actual content to the locations on your file system.  The install_site.sh script is simply a series of install commands, and just is a work saver for the required copying.  It can be used as follows:

sudo ./install_site.sh SiteName Owner Group .../Path_to_data_config_directory .../Path_to_web_data_directory

A sample call is given below.  This script must be run as root - sudo being one possible means to this end.

sudo ./install_site.sh PgCamel pgcamel pgreet /home/agent-workspace/PgCamel  \
/home/httpd/htdocs/pgreet/PgCamel

See the Penguin Greetings Administrators' Guide for more information on setting up secondary ecard sites and the Penguin Greetings Content Developers' Guide on creating and manipulating secondary ecard sites.

If you wish to install all the components of any of the five object-oriented secondary ecard sites (all sites but the Camel collection) you can use the install_site_obj.sh installer that comes with version 0.9.8 of Penguin Greetings.  This installer is like it's simpler ancestor and uses install_site.sh for installing the two languages included with each object-oriented site.  Like than ancestor, it doesn't update the configuration files, it simply copies files to the right location on your disk in a simple-minded way.  The arguments are essentially the same as for install_site.sh:

sudo ./install_site_obj.sh SiteName Owner Group .../Path_to_data_config_directory .../Path_to_web_data_directory

Note that because this script installs the two languages automatically, the paths on your server won't quite be the same.  This is illustrated by a sample call on the development <canebas.org> server shown below.  The install_site_obj.sh script will create the  required Pg4Seasons directories and associated en-us and fr-fr subdirectories, unlike the example creation of the PgCamel directory above with install_site.sh.

sudo ./install_site_obj.sh Pg4Seasons pg4seasons pgreet \
                            /home/agent-workspace /home/httpd/htdocs/pgreet



  [Table of Contents]
Troubleshooting the installation.

Penguin Greetings has been running now for years on my personal web server and has been extremely reliable and trouble-free.  However just in case, here are a few issues and trouble-shooting hints.
  [Table of Contents]