# MiniVend V1.03
# 
# Copyright 1996 by Michael J. Heins <mikeh@iac.net>
#
# Largely based on Vend 0.2
# Copyright 1995 by Andrew M. Wilcox <awilcox@world.std.com>
#
# Portions from Vend 0.3
# Copyright 1995 by Andrew M. Wilcox <awilcox@world.std.com>
#
# This program is free software; you can redistribute it and/or modify
# it under the terms of the GNU General Public License as published by
# the Free Software Foundation; either version 2 of the License, or
# (at your option) any later version.
#
# This program is distributed in the hope that it will be useful,
# but WITHOUT ANY WARRANTY; without even the implied warranty of
# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
# GNU General Public License for more details.
#
# You should have received a copy of the GNU General Public License
# along with this program; if not, write to the Free Software
# Foundation, Inc., 675 Mass Ave, Cambridge, MA 02139, USA.

Welcome to MiniVend, based on Vend, Andrew Wilcox's fine shopping cart
program.  This program is completely unsupported, without warranty of
any kind -- but that doesn't mean I am not interested in problems,
suggestions, or comments.  Please feel free to send them to me, Mike
Heins, <mikeh@iac.net>.

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

                        M I N I V E N D
                                       
   MiniVend is a full-featured electronic catalog system (commonly known
   as a shopping cart) with online ordering capability. It is designed to
   provide an interface complete with SSL security and full database
   support.
   
   MiniVend is freely-redistributable under the GNU General Public
   License -- you can download it via FTP.

  IMPORTANT NOTE:  MiniVend works best with Perl 5.002 -- if you are
  having problems, get it. I understand it does work with 5.001m, but
  it is no longer tested with it.
   
     Features

     * Users maintain a "shopping cart" for ordered items
     * SSL support means secure and practical credit card ordering
     * Catalogs can be of almost unlimited size with excellent
       performance
     * Powerful search capability including a complete Glimpse
       interface, one-click search profile capability, and independent
       field search selection
     * Multi-server mode for very high capacity on systems with
       sufficient memory
     * Forked searches for consistent response time in
       single-server mode
     * Cookie support allows browsers to leave catalog and come
       back without losing session state
     * Full frames support
     * Catalog pages automatically selected -- either built "on the fly"
       from the database or pre-made for popular items
     * Works well with all browsers
     * Complete addressable database support with virtually unlimited
       rows and columns
     * Fully-configurable quantity pricing
     * Easy back end order entry
     * Full client-side imagemap support, including frame targets and
       form submits
     * Automatic installation and configuration
     * Remote administration via the web using MAT
     * Runs under Perl 5 and almost any UNIX
     * Designed to be secure, runs with taint checking enabled
     * Built-in online help capability
     * Central control of buttonbars
     * Sales tax calculation, with fully independent non-taxable
       item and taxed shipping
     * Shipping calculation (quantity and/or weight)
     * Blank field checking
     * Fully configurable order reports
     * Much more
       
   Andrew Wilcox wrote Vend, the copylefted shopping cart software.
   MiniVend is based on Vend V0.2, but enhanced considerably, adding
   support for frames, search capability, remote administration,
   superfast server mode, client-side imagemaps, user-customizable help
   and displays, and more. 


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

                         D E M O

There are two modest demos supplied. The 'sample' demo demonstrates
frames on MiniVend, along with the result of automatic page generation.
It is possible to generate a link to each individual item with an
automatic page builder. The pages in the demo were untouched by human
hands, other than generating a template.  It is possible to build inline
images, clickable sounds, and other doo-dads into these pages, and then
automatically generate Vend references to them.

To install the demo, simply copy the following pages from the sample
directory into the directory sample/ under your HTML root. Use these
commands:

 cd /usr/minivend                   # wherever your vend directory is
 mkdir pages                        # make if not already there
 cp sample/*.html pages
 mkdir /usr/local/etc/httpd/htdocs/sample # Or where your doc root is
 mkdir /usr/local/etc/httpd/htdocs/sample/images
 cp sample/images/* /usr/local/etc/httpd/htdocs/sample/images
 cp sample/special*.html /usr/local/etc/httpd/htdocs/sample
 cp sample/index.html  /usr/local/etc/httpd/htdocs/sample
 cp sample/intro.html  /usr/local/etc/httpd/htdocs/sample
 cp sample/address.html /usr/local/etc/httpd/htdocs/sample

There is a simple demo that demonstrates the basic features 
of MiniVend.  It is located in the 'simple' directory, and is
the default if you installed in static mode.  To enable it:

 cd /usr/minivend                   # wherever your vend directory is
 mkdir pages                        # make if not already there
 cp simple/*.html pages
 mkdir /usr/local/etc/httpd/htdocs/sample # Or where your doc root is
 mkdir /usr/local/etc/httpd/htdocs/sample/images
 cp sample/images/* /usr/local/etc/httpd/htdocs/sample/images
 cp simple/index.html  /usr/local/etc/httpd/htdocs/sample

The configure script will give you a chance to install either demo
automatically -- this is with no doubt the easiest way to see the
demo.  I suggest you use it.

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

                      A V A I L A B I L I T Y
					          A N D
                     C O M P A T I B I L I T Y

MiniVend has been well-tested on Solaris 2, SunOS, Linux, OSF/Alpha, ,
and FreeBSD. The underlying Vend engine has certainly been tested on
several more OS versions -- and it should work on any UNIX with Perl 5
and GDBM, DB_File, or NDBM support.

GDBM works best -- it is the fastest for import, and most reliable.

Solaris 2 and Irix 5 have certain problems with file locking,
which may have been resolved in MiniVend 1.03 -- we will see.
In any case, with those operating systems you will need the 
File::Lock module, available at the same CPAN archive where you
obtained this program.

To fully use the page checking feature, you will need the HTML::Parse
module, again available at CPAN in the libwww-perl-5b libraries. You
will want those anyway, if you are doing much work with the web.

If you are using GCC on Solaris, you may have to pass -lsocket on
the compile command line.

Please let the author know if you have successfully run MiniVend on
any additional platforms -- patches would be appreciated.

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

                      I N S T A L L A T I O N

Try typing:

	./configure

at the prompt after unpacking the tar file.  If it doesn't work,
then try:

	perl configure.pl /usr/bin/perl

Replace 'perl' and '/usr/bin/perl' with whatever you happen to call Perl
with.  You can try 'whereis perl', which might have info that escaped
the configure script.

If none of that works, you will have to follow the steps below -- you
should check out the documentation, but it will be in POD format, and if
you don't have Perl 5, you are out of luck anyway.  You can try building
it with './makedocs', or just looking at the file doc/minivend.pod.

NOTE:  As the configuration script has gotten better, this procedure
has been neglected.  It may be incorrect -- use the configure program!

The installation is quite complex.  There are 8 basic steps.

1. Read the documentation.
2. Determine your system configuration
3. Edit and compile the dispatch programs
4. Adjust the script files
5. Configure your HTTP server
6. Install the dispatch programs and utilities
7. Set up your database
8. Create your page tree


1. READ THE DOCUMENTATION

All of the information is there, and it should be clear enough to the
very technically-oriented user with some knowledge of UNIX.  EXPECT
PROBLEMS IF YOU DON'T FIT THIS DESCRIPTION. Assistance of an expert may
be vital. Caveat Emptor. TANSTAAFL. To make the docs, you can type at the
prompt:
	
	sh makedocs

That will use pod2html and pod2man to make the POD documentation.

2. DETERMINE YOUR SYSTEM CONFIGURATION

You need to know at the minimum before compiling the dispatch
programs:

	a. The UID your CGI program will run under.  This is
	often 'nobody', but the numeric ID is needed. Copy the
	testcgi script provided to your cgi-bin directory and
	run it -- it should give you the information. Actually,
	with MiniVend 1.01, and its server mode, you can get
	along without it, but MAT will not work.

	b. The location of your Perl 5 binary. Perl 5.002 is
	recommended for best results -- it might run under Perl 5.001,
	but I wouldn't recommend it.

    c. The location that your minivend.pl script will be in.  Creating
	the directory $HOME/minivend is one possibility -- the default
	is /usr/local/lib/minivend.

3. EDIT AND COMPILE THE DISPATCH PROGRAMS

To compile vlink, which is needed to run in server mode, you should read
the documentation under "Setting up VLINK".  Basically, you need to edit
the defines LINK_FILE, LINK_TIMEOUT, PERL, and VEND in src/link.c, and
then:

	cd src
	./configure
	cc -o vlink vlink.c

To make svend, edit the first three lines of svend.c, the dispatch
program for the main Vend program.  Use the information you got in step
2.

#define CGIUSER	65534
#define PERL 	/usr/bin/perl
#define VEND	/usr/local/lib/minivend/minivend.pl

You will need a C compiler -- gcc will work fine, as will most
stock compilers.  Compilation is simple, and is done with the commands:

	cc -o svend svend.c
	cc -o mat mat.c

This will create two binaries, svend and mat.  You will actually
install them in Step 6.

4. ADJUST THE SCRIPT FILES

Edit each of the files to call the proper Perl if desired. This is not
really needed for MAT or minivend.pl -- they are called with the
dispatch programs, and don't need a shbang line except for Perl
directives. A proper shbang is required for vendpage, makedbm, and
the server control scripts (stop,start,restart).

You should use the -w and -T flags, for warnings and tainting.  This is
the default.  See the file src/bug1.pl for a tainting bug exhibited on
some systems, in particular Linux.

The minivend.pl script needs to know the location of its toplevel
directory.  That is set in the variable $Config::VendRoot -- edit the
file if you are not using the default /usr/local/lib/minivend.

You no longer need to mess with the DBM type in MiniVend 1.02, but
you will be out of luck if you only have SDBM -- its record size
of 1024 is probably not large enough for sessions.  You can try.
Just change all instances of NDBM to SDBM and it should work.

The MAT(8) utility has a number of configurable variables
that need to be set. See the comments in the file for information
on how to set them.


5. CONFIGURE YOUR HTTP SERVER

This is quite installation dependent.  For the NCSA server, you will
need to create a script alias for the directory you plan on placing
svend in, and a PASSWORD-PROTECTED script directory for the MAT
program.  See your HTTP server documentation for information on how
to do this. 

6. INSTALL THE DISPATCH PROGRAMS AND UTILITIES

If you want to run in server mode, copy the vlink program to your
cgi-bin directory and make it SUID to a user ID other than root.  DON'T
MAKE IT SUID ROOT!  Use the command:

	chmod u+s vlink

If you don't use vlink, copy the svend program to your cgi-bin directory
and make it SUID to a user ID other than root.  DON'T MAKE IT SUID ROOT!
Use the command:

	chmod u+s svend

If you want to run the program without SUID permissions on the dispatch
programs, you will need to configure the ReadFilePermission and
WriteFilePermission directives as 'world'.  That will create
world-writable session files and error logs.  It is also possible to
make the files owned by the CGI user.  If using vlink, you will also
have to edit the file Vend/Server.pm and change the line that sets the
socket file permissions to 0666 instead of 0600.

The MAT utility requires SUID permissions, since the configuration
files are not (and should not be) world-writable.  If you can't do
SUID, don't use MAT.

7. SET UP THE DATABASE

Create the products.asc file according to the Vend documentation.

8. CREATE YOUR PAGE TREE

Examine the sample page tree supplied, and create some catalog pages
that match your database.

If you have completed steps 1-8 properly, you should have a running 
Vend catalog. More information can be found in the doc/ directory.