
TallyMan Installation Overview
Second Draft, for development version
15 September 1999
revised 27 September 1999
Jason E. Holt <jason@akopia.com>

*************** NOTE ******************

This file is somewhat out of date, owing to the automatic install
script, which should do all of this, plus install sample data and set
up the global configuration options.  This file is included as a peek
at what goes on under the hood of the installer.  See www.tallyman.com
for up to date install instructions.

*************** NOTE ******************

------------
Contents
------------

   * Introduction
   * Installing the TallyMan distribution
   * Checking for the necessary libraries
   * Setting up the database
   * Setting up the CGI scripts
   * Setting TallyMan configuration options
   * Accessing the back office
   * Troubleshooting


------------
Introduction
------------

There are two major configurations in which TallyMan can be used.  The
first involves less system-level configuration and can be installed
and run without root access, but takes a large hit in performance.
The second involves setting up mod_perl and embperl with an Apache web
server, and provides the substantial performance increase associated
with mod_perl.

-------------------------------------
Installing the TallyMan distribution
-------------------------------------

gunzip/untar the installation tarball into an appropriate directory,
where "appropriate directory" is *not* one under the document root of
the web server.

------------------------------------
Checking for the necessary libraries
------------------------------------

Verify that you have the following Perl modules installed on your system.
For a user-space install (ie, one not requiring root access), these libraries
may be installed in a user-owned directory.

    HTML::Embperl
    DBI
    The appropriate DBD for your database:
	DBD::Pg for PostgreSQL
	DBD::Oracle for Oracle
    CGI 
    
Note to RedHat Linux users: 
If you installed PostgreSQL from the RedHat RPMs, specify "/usr" as
the directory for includes and libraries when compiling DBD::Postgres.


-----------------------
Setting up the database
-----------------------

TallyMan needs a database to store its data.  In PostgresSQL, this can be
as simple as connecting to the database as the administrator via `psql`, and
doing something like the following:

If you are using RedHat postgres installation. First you will need to
initalize the database. this is done by:

###############################################

# su postgres
$ initdb --pglib=/usr/lib/pgsql --pgdata=/var/lib/pgsql
$ exit
# /etc/rc.d/init.d/postgres start
# su postgres
$ createdb 
$ psql -u
Username: postgres
Password: <- hit return ->

Welcome to the POSTGRESQL interactive sql monitor:
  Please read the file COPYRIGHT for copyright terms of POSTGRESQL

   type \? for help on slash commands
   type \q to quit
   type \g or terminate with semicolon to execute query
 You are currently connected to the database: postgres

postgres=> alter user postgres with password <- new password ->;
postgres=> \q
$ chmod 600 pg_pwd
$ 

###############################################

Now you will want to change the followling lines in pg_hba.conf from:

local        all                                         trust
host         all         127.0.0.1     255.255.255.255   trust

to:

local        all                                         crypt
host         all         127.0.0.1     255.255.255.255   crypt

$ exit

###############################################

That should set up redhat to be right.

###############################################

$ psql -u
Username: postgres
Password:

Welcome to the POSTGRESQL interactive sql monitor:
[...]

postgres=> CREATE USER tallyman WITH PASSWORD xyzzy;
postgres=> CREATE DATABASE tallyman;
postgres=> \q
###############################################

The SQL code to create all the tables required to use TallyMan is
stored in a database-neutral format, and the make_sql script needs to
be run in order to create the correct sql code for your database.
Change directory to tallyman/make and do something like this:

###############################################
$ cd milton/make
$ ./make_sql.pl oracle       # for Oracle users
$ ./make_sql.pl postgresql   # for PostgreSQL users
###############################################

Next, the SQL installation scripts generated by make_sql need to be
run with your database.  First change directory to the directory
containing the sql scripts.  This should be milton/make/oracle/ or
milton/make/postgresql/, depending on the database you'll be using.
Next connect to the database created for TallyMan as the appropriate
user (*not* as the administrator).  Then instruct the sql monitor to
run the scripts created by make_sql.  Running make_all.sql will
automatically run all the other necessary scripts.  If you can't find
any .sql files in the make directory, the make_sql script probably
didn't execute successfully.  *Don't* try to run any of the .in files
(in the milton/make/generic/ directory) with the sql monitor.  For a
PostgreSQL system, you'll do something like this:

###############################################
$ cd milton/make/postgresql
$ psql -u
Username: tallyman
Password:

Welcome to the POSTGRESQL interactive sql monitor:
[...]

postgres=> \i make_all.sql
[... lots and lots of text will follow here as the scripts execute ...] 
[... ignore things like ...]
[... NOTICE:  EndTransactionBlock and not inprogress/abort state ...]


postgres=> \dt

 +------------------+----------------------------------+----------+
 |  Owner           |             Relation             |   Type   |
 +------------------+----------------------------------+----------+
 | tallyman         | address                          | table    |
 | tallyman         | affiliate                        | table    |
 | tallyman         | cat_order                        | table    |
 | tallyman         | cat_order_stat                   | table    |
 | tallyman         | cell                             | table    |
[... about 40 more tables should follow ...]
 +------------------+----------------------------------+----------+
postgres=> \q

###############################################


--------------------------
Setting up the CGI scripts
--------------------------

Two directories in the TallyMan distribution contain scripts which
need to be run via the web server.  If you're doing a mod_perl
installation, set up Apache to automatically execute .epl files with
EmbPerl, similar to the setup shown in the apache_include.conf

If you're doing a user-space install, however, the scripts will need
to be run as CGI scripts.  If you already have access to a directory
from which CGI scripts can be executed, you can copy the milton/office
and milton/admin directories there (copy them recursively with 'cp -R'
so the images/ directory gets copied as well).

If you don't already have a CGI directory set up, something like this
in your Apache config files should work:

###############################################
In access.conf:

<Directory /home/jason/tallyman-cgi/>
AllowOverride AuthConfig
Options ExecCGI FollowSymLinks
</Directory>

In srm.conf:
ScriptAlias /tallyman-cgi/ /home/jason/tallyman-cgi/
###############################################

The "FollowSymLinks" option in the above example will let you simply
place links to the milton/admin/ and milton/office/ directories in the
CGI directory.  If you prefer, you can omit that option and copy the
admin/ and office/ direcories to the CGI directory.

Remember that the web server will need to be restarted before changes
to the config files will take effect.

If FollowSymLinks is turned on for your CGI directory, link the
milton/admin/ and milton/office/ directories with something like the
following:

###############################################
$ cd milton
$ ln -s /home/jason/milton/admin/ /home/jason/tallyman-cgi/admin
$ ln -s /home/jason/milton/office/ /home/jason/tallyman-cgi/office
###############################################

If you'll be copying the files there directly, something like this
should work:

###############################################
$ cd milton
$ cp -R admin/ /home/jason/tallyman-cgi/
$ cp -R office/ /home/jason/tallyman-cgi/
###############################################

tallyman/office contains all the scripts which need to be available to
the general public; they comprise the shopping cart.

tallyman/admin contains the back-office scripts which provide the web-based 
administrator interface to TallyMan.  

All the scripts in milton/office/ and milton/admin/ need Embperl to
run, and a modification of the embpexec.pl script which comes with
Embperl is used as a wrapper to execute them.  For the sake of the URL
used to reach the scripts, this file is called simply "epl".  One copy
exists in the admin/ directory, and another in the office/ directory.
Edit each, filling in the information needed for the scripts to find
the TallyMan libraries and the configuration file for your store.

tallyman/admin needs to be protected by a .htaccess file to keep the
general public from, say, deleting all your files.  Something like
this should work as your admin/.htaccess file:

###############################################
AuthType Basic 
AuthUserFile /home/jason/milton/milton_passwd
AuthName "Milton Admin"
require valid-user 
###############################################

Once you've done that, set up your .htaccess file with a command like
this. *NOTE*: this command will delete the mentioned file if it
exists, and create a fresh password file in its place.  To add another
user to an existing, omit the "-c" option.

###############################################
$ htpasswd -c /home/jason/milton/milton_passwd jason
###############################################

The "epl" script will try to verify that a username was entered, and
will complain if it can't.  Nonetheless, make sure your browser asks
you for a username and password the first time you access the back
office.  See the "Troubleshooting" section if you have a problem with
this.


--------------------------------------
Setting TallyMan configuration options
--------------------------------------

The milton/stores/sample/ directory contains the templates and
configuration for a sample store.  Edit stores/sample/configuration
and fill in the requisite information.  The comments in that file
indicate what goes where.


------------------------
Accessing the back office
------------------------

At this point you should be ready to load the back office.  From here
you'll be able to manage most aspects of your store.  In your favorite
web browser, load the admin/index.epl script.  Make sure you're
prompted for a username and password the first time you access a back
office script since you started your browser.  

If you're running with mod_perl, the URL for the main back office
screen will simply be the URL of admin/index.epl.  For example, if
the scripts are kept on "lunkwill.ml.org", and the admin directory is
in a subdirectory of your web server's root directory named "milton",
the URL would be:

http://lunkwill.ml.org/milton/admin/index.epl

If you're using a user-space installation, you'll need to insert
"epl/" between "admin/" and "index.epl" so that the embedded Perl
wrapper is executed.  If your CGI directory's path (from the browser's
perspective) is "/tallyman-cgi", the URL would be:

http://lunkwill.ml.org/tallyman-cgi/admin/epl/index.epl

[XXX Need some sort of conclusion, "where do I go now?" sort of thing here.]

[XXX performance note: init.d/postgres: su -l postgres -c '/usr/bin/postmaster -o -F -S -D/var/lib/pgsql' XXX]


---------------
Troubleshooting
---------------

If you have problems compiling Apache and mod_perl, you may find this
helpful.  This is how I compiled Apache 1.3.9 and mod_per 1.21:

############################################
$ cd mod_perl-1.21/
$ perl Makefile.PL APACHE_SRC=../apache_1.3.9/src \
$ DO_HTTPD=1 USE_APACI=1 PREP_HTTPD=1 EVERYTHING=1
$ make
$ su
# make install
# exit

$ cd ../apache_1.3.9/
$ ./configure --prefix=/usr/local/apache \
$ --activate-module=src/modules/perl/libperl.a \
$ --enable-module=most --enable-shared=max
$ make
$ su
# make install
############################################

---------------

If your browser doesn't prompt you for a username and password the
first time you access your back office each session, or if you get a
message like the following when attempting to access the back office:

"REMOTE_USER environment variable not set.  Check your .htaccess file and
web server config."

then check the following:

1: The milton_password file exists in the place specified by your
admin/.htaccess and has an entry for the username you entered.  There
should be a line similar to the following, where "admin" is the
username you gave the htpasswd command:

admin:t1xbF0Y7b3FYo

2: The admin/.htaccess file exists and has the proper
permissions.  (It should be world readable, but writeable only by
you.)

3: The "AllowOverride AuthConfig" option is enabled in your web
server's "access.conf" file.


---------------

If you can access admin/index.epl via your browser, but get a fatal
error each time you try to go to one of the administration screens:

1: Make sure the database is running, and that the username and
password specified in stores/sample/configuration are both correct.

2: Verify that each of the other configuration options listed in
stores/sample/configuration are correct.

3: Connect to the database using TallyMan's user account ("psql" and
"isql" [XXX is this correct?] will let you do this from the command
line for PostgreSQL and Oracle, respectively), and make sure that the
necessary tables exist.  (There should be at least 40 tables; if you
have at least that many, all of them probably exist.)


---------------

If you get bizarre looking output on the pages as they load up (visible
HTML tags, etc.) (other symptoms include missing form data in fdat and
broken $escmode, $optRawInput, etc. variables):

You probably have mod_perl compiled as a DSO (loadable) module for
Apache.  Make sure you don't have a line like:

PerlModule HTML::Embperl

in your web server config.  You still need to have PerlHandler set for
.epl files, but the PerlModule line above will break Embperl in very
strange ways.  Also, if you have any sort of "startup.pl" or the like-
a script which is run at server startup time, make sure it isn't doing
a "use" on any specific libraries relating to TallyMan.  You'll need 
a line with "use lib /path/to/tallyman/libs", but that's all.

---------------

If your browser displays HTML source instead of properly rendering the
back office pages, your web server may be sending text/plain as the
MIME-type for .epl files.  To correct this, in your Apache configuration
you'll need:

AddType text/html .epl

---------------


---------------------------------------------------------- 
END

