The Penguin Greetings Installation Guide
Copyright © 2003-2005 (Penguin Greetings 1.0.0
A introduction to installing the Penguin Greetings web-based
Table of Contents:
- Overview of Penguin Greetings
- Penguin Greetings
- Quickie recipe for the
- Setting up environment
- Installing the application
- Creating Databases and starting
- Installing secondary ecard
Overview of 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.
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
is executed on the server.
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
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
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!
Quickie recipe for the
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!
Setting up environment
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
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:
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
runs for the moment as a CGI script, simply installing the
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
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
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
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.
useradd -g pgreet -c
"Penguin Greetings Agent" -s /bin/false -d /home/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
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
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
subdirectory off of your HTML document tree.
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
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
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:
- The path to the directory where you wish to install the
ecard images and templates (such as: /home/httpd/htdocs/pgreet.)
The installer will create a subdirectory called images and templates within this
- The path where you wish to install the CGI (and if
desired SpeedyCGI) applications (such as /home/httpd/cgi-bin.)
- The path where you wish to install the Penguin Greetings utility
programs: PgTemplateTest and PpgreetDBinit
(such as /usr/local/bin.)
- The path where you wish to install the Penguin Greetings
configuration files: pgreet.conf, cards.conf, and
(such as /usr/local/share/pgreet/conf.)
- The path where you wish to install the Penguin Greetings daemon:
pgreetd (such as
- The hostname of your server.
- The SMTP server you wish to use to send ecard email.
- The UID and GID for the pgreet user you created as
the email agent for Penguin Greetings.
|canebas.org % sudo
Penguin Greetings installer - version: 0.9.5
fetch Perl modules directly from CPAN now? ([Y]es/No):
Launching CPAN installer
CPAN: Storable loaded ok
Going to read /home/users/elagache/.cpan/Metadata
Database was generated on Sat, 16 Aug 2003
CPAN: LWP::UserAgent loaded ok
Fetching with LWP:
Going to read
CPAN: Compress::Zlib loaded ok
Fetching with LWP:
Going to read
Database was generated on Mon, 18 Aug 2003
Fetching with LWP:
Going to read
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 . . .
for required modules
- Found: I18N::AcceptLanguage
Do you wish to
install the Greeting card image
Do you wish to
install the Penguin Greetings Speedy CGI
Please enter the
location of the following files and directories
card image directory [none]:
Greetings CGI script [/home/httpd/cgi-bin]:
Greetings Template test tool [/usr/local/bin]:
Greetings card configuration file [none]:
Greetings main configuration file [none]:
Greetings system daemon [/usr/local/sbin]:
configuration file [none]:
Greetings Speedy CGI script
Greetings database init tool [/usr/local/bin]:
Greetings HTML template files [none]:
Please provide the
following information for your installation:
hostname of your server (e.g.
Name of your
The group ID
number (not name) of the pgreet group on your
Path on your
server to HTML data (images and templates) for Penguin
The user ID
number (not name) of the pgreet user on your
Path on your
server to Pgreet data and configuration
path to Penguin Greetings Configuration file (including
Greeting card image directory
Penguin Greetings CGI script
Penguin Greetings Template test tool
Penguin Greetings card configuration file
Penguin Greetings main configuration file
Penguin Greetings system daemon
PgTemplateTest configuration file
Penguin Greetings Speedy CGI script
Penguin Greetings database init tool
Penguin Greetings HTML template files
Install.PL has four command line options explained below:
|Do a clean install,
erase installer.cache and
|Do a dry-run install,
ask questions and generate cache, but do not actually
install any files.
|Force install, skip
asking for locations but use locations in installer.cache.
|Give a usage/help
|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.)
|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
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
system-V startup scripts and log rotation (note changed
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.
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.
program runs the same sanity checks that the Penguin Greetings
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
Creating Databases and starting
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:
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
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
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:
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
are running, send yourself a Penguin Greeting and see if it
makes it to your email box!
Installing secondary ecard
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.:
All these sites but the first include a French translation.
- PgCamel -
The Penguin Greetings Camel
- PgSaint -
The Penguin Greetings Holy
- PgXmas -
The Penguin Greetings
Christmas card Collection
- PgPoppy -
The Penguin Greetings
California Poppy Collection
- The Penguin Greetings
Four Seasons Collection.
- Savoring the sights of
Seattle Collection (Implemented using
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
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:
./install_site.sh SiteName Owner
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
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
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:
./install_site_obj.sh SiteName Owner
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
subdirectories, unlike the example creation of the PgCamel directory above with
./install_site_obj.sh Pg4Seasons pg4seasons pgreet \
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
- Run PgreetConfTest first to make sure your
configuration file is consistent with your system.
- Unless you are really bold (or overworked) leave the
command line option on pgreetd. This turns on
a great deal of additional information about what pgreetd is doing.
Greetings is very simple-minded about how it processes
temporary state files. It uses the filename prefix to
tell it what sort of file it is attempting to process.
The prefixes can be changed but perhaps this is not
wise once the program is running. If you have a system
failure and have trouble restarting, you can diagnose which
files have been left unprocessed by the filename prefix.
- It is possible to "jump-start" pgreetd to process all cards
immediately by restarting the daemon. When debugging,
run the CGI script before starting the daemon. The CGI
script doesn't need the daemon to work and that allows you to
divide the possible sources of error.
- There is a quick script BerkDB2text.pl which will
open a Berkeley DBM file and dump its contents to standard
output that you can use to look if your databases are being
corrupted. There is the converse script text2BerkDB.pl
that can be used to assemble a file that has been dumped to
text. It is possible (as a desperate last-resort) to
disassemble, edit, and reassemble a database file this