# MiniVend V1.03 # # Copyright 1996 by Michael J. Heins # # Largely based on Vend 0.2 # Copyright 1995 by Andrew M. Wilcox # # Portions from Vend 0.3 # Copyright 1995 by Andrew M. Wilcox # # 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, . ------------------------------------------------------------- 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.