FishCart: an online catalog management / shopping system
Copyright (C) 1997-2003  FishNet, Inc.
=========================================================================

                 FishCart Installation Instructions

FIRST TIME INSTALLATION

Unpacking the tarball or fetching the CVS tree will install FishCart
into a "./fishcart_v3" directory under the current level; /usr/local
might be a reasonable starting place.  After you've installed the
source, go into the ./fishcart_v3 directory and do the following
steps to set up your running environment.

1. Change directories to the ./fishcart_v3 directory.


2. Run the following command, choosing the appropriate database:

   ./install.pl -d {odbc | mysql | pgsql}

   For the Solid database only, run this instead:

   ./install.pl -d odbc -l solid

   This will create a "./database.pl" file to set a $databaseeng
   variable to the proper value; this will be required later by
   ./install.pl when installing a FishCart to automatically set the
   database to this value.
   
   This will also copy the appropriate public_*.php and admin_*.php
   files to public.php and admin.php; it is these that will be
   installed in each cart and modified as needed.

   This will also set up a directory at peer level with the distribution
   directory called 'fishcartsql.db'.  This directory will be used
   to hold the various db.??? and unique per-installation files;
   this will allow a new FishCart source tree to be installed without
   interfering with customized files for a particular installation.

   The '???' portion of the filename above should be set to a short
   descriptive name for each installation.

   The ~/db/db.cust file will be also copied from the distribution
   into the ../fishcartsql.db directory.  This is a perl array that
   you will copy and modify to create separate FishCart installations.
   Each db.? file describes the installation for a particular FishCart.

   NB: if you are upgrading an existing FishCart, you should check
   to see if there are any new files in the new db.cust file in the 
   distribution.  This can be done on Unix platforms with 'diff'.
   Windows has no good equivalent, so you will need to compare them
   manually.  You will need to manually add the new files into your
   existing db.??? files that you are upgrading to make sure that
   all the required files are copied in place.


3. Check the include path in php.ini to make sure it has './' defined.

   Whether in the central php.ini (for IIS or sitewide Apache) or in
   the Apache VirtualHost for this web site, both magic_quotes_gpc and 
   magic_quotes_runtime must be turned on.

   php.ini:

   magic_quotes_gpc    =   On
   magic_quotes_runtime=   On

   <VirtualHost a.b.c>
   ...
   # valid only for php 4
   php_flag magic_quotes_gpc on
   php_flag magic_quotes_runtime on
   </VirtualHost>


4. The SQL database for split credit card delivery must be now be
   created.  The appropriate 'sql_*_cc.sql' files installed into the
   maintenance directory must be run through the SQL command
   line utility for that database.  The database may need to be
   created first; this will depend on the database engine in use.

   In V2 there is a zone level flag to control whether or not CC
   numbers are delivered by the split number method.

   SOLID:

   When the 'fishcartsql' database has been created, issue
   the following commands to create the tables.  Note that the
   specific values may change for your installation.

   cd /usr/local/solid
   ./bin/solsql 'upipe solid' uname pword /install/path/sql_solid_cc.sql

   NB: Solid uses SQL views for its split credit card holding tables.
   This is quite different than the other database servers.  This is 
   automatically managed in the FishCartSQL scripts.


   MYSQL / PGSQL:

   The split CC holding tables are created by default when each
   individual cart is installed.  That is, a split CC system is installed
   for each different cart installation.  By default access to the split
   CC tables should only permitted to the admin SQL user.



5. If running PHP3 in safe mode, you will need to copy the mvupload
   script into the safe mode executable directory for file uploads to
   work.  The script does assume that the 'mv' command is available
   for execution in the safe mode directory.

   If not running in safe mode, the upload.php script will use the
   PHP4 function move_uploaded_file() to move the file to the
   final destination.  You should not have to make any code changes
   to make upload work if not running safe mode.
   
   A CGI version of PHP is required to be able to run mvupload.
   If you use the mvupload script, you may need to edit line 1 to set
   the path to the CGI version of PHP, typically called 'php'.

   The mvupload script is not strictly necessary, as the 'mv' command
   could be run directly from the upload.php file.  However, running
   from a script allows other things to be done to the file as needed
   without modifications to the upload.php file.



INSTALLATION STEPS FOR EACH FISHCART

1. Copy the ../fishcartsql.db/db.cust file to a new name for your
   installation.  You don't have to stick with the db.??? naming
   convention, but the file must be in the fishcartsql.db directory.
   Then modify the new file to reflect the installation location and
   unique database table name, etc. that will be used for this cart.

2. MYSQL

   To create a mysql database for your FishCart, issue the following
   commands:
   
   cd /usr/local/var
   mysqladmin create fishcartsql

   You will need to create two users for this new database.  One is
   a limited permission user for the public Web pages; the other is a
   full permission user for the maintenance Web pages.

   *** NOTE IF YOU CANNOT ADD NEW MYSQL USERS: if you must use
   predefined mysql users, perhaps for hosting service requirements,
   you will need to change your db.??? file to make these users the
   installed mysql access users.  By default, FishCart uses two users,
   a public and a private user, with different permission structures.
   It is possible to set these to the same mysql user if it is not
   possible to create more than one.  To change the users, edit your
   db.??? file and search for the array entries 'userid', 'userpw',
   'admid', and 'admpw'; change these to your predefined mysql user(s).
 
   *** NOTE: The '-u XXXX' in the above command MUST -- REPEAT MUST -- 
   have grant permissions, typically the mysql admin user.  This is NOT
   true when a user is created with 'grant all privileges'; mysql does 
   not automatically give GRANT privileges to a new user.  These must be
   specially set.  Thus, the created FishCart admin user cannot normally
   be used to run the above commands.

3. POSTGRESQL

   Like mysql you will need to create a DB.  This must be done by a user
   who can create a DB.  You can use the command "createuser" as the
   postgres account (or other postgres superuser, see man createuser
   for the postgres man page).

   The account you are logged into will own the DB.  This is sticky some
   days.  The main problem is that if you run a script as a user other
   than the webuser, the scripts do allow you to insert into your own
   queries.  Currently the default inserts are in the sql_pgres.sql.
   The fix for this is the sql_pgsql_insert.sql file.  See below.
  
   Why would you want this nonsense?  Well say your user name is bob,
   you are running the install.  The web server will run as user "web."
   "web" is a low security user, so you want to GRANT permission carefully
   to web.  So if you are running as "bob" and GRANT SELECT/INSERT/UPDATE
   to "web" postgres does not automatically grant these perms to "bob."
   So when the script sees an "insert" it runs as "bob" but becuase you
   GRANTED permissions, "bob" has no rights (other than GRANT rights).

   So one easy solution is to "su - web" and run the psql scripts,
   but that is not always an option.  The trickier one is to break down
   the scripts.
    
   There is probably a better way to so this, but I (Zot) have not come
   up with it.

   A nifty trick is to change the permissions for user nobody in postgres
   to allow to create tables, create the table, and chnage the permissions
   back.  The solves alot of GRANT problems.

   Also since psql and perl tend to see you as the account you are
   logged in as, you may need to "su - username" before you install.
   Since root is rarely a legit postgres user, it is a good idea to do
   all of the tasks as the user in question.  This may effect directory
   permissions (or rather, force you to correct them ahead of time).

   Once you have the user and permissions set, as the user do a
   
   createdb databasename

   putting whichever databasename you are using there (default is fishcart
   or fishcartsql)


4. Change directories to the ./fishcart_v3 directory; the install.pl
   script is written to run from within the fishcart_v3 directory 
   to avoid absolute path problems.  Run the ./install.pl script from
   the fishcart_v3 directory to copy and customize the scripts.
   The install.pl script will look in ../fishcartsql.db for the file.

cd fishcart_v3
./install.pl db.??? section_to_install

   The sections to install argument indicate whether to install all
   of the cart or just one section.  Some possible arguments are
   below; to see a full list, simply enter './install.pl'.
   
   all    installs all parts of the cart
   cart   installs the front end cart scripts
   cron   installs only the cron script(s)
   maint  installs only the maintenance scripts
   sql    installs only the SQL database definition file
          into the /usr/local/solid area where your database is
   lang   installs only the language templates

   ** NB: even if the 'all' parameter is given, the language templates
   are only copied the first time the cart is installed.  Once the
   cart is installed, if you want to update an installed cart from
   the master scripts, you must run install.pl with the 'lang' option.
   WARNING: if you have customized your installed language templates,
   as many will want to to, you will overwrite your changes when the
   language templates are reinstalled.  

   The actual cart scripts that interact with the user are installed
   into the directory that you specified in the db.??? file.  The cart
   maintenance scripts are installed into a "~./maint/" directory
   under it; the top level file in ~/maint is "index.php".

   This procedure may be used repeatedly as FishCart is upgraded.
   This will install the upgraded scripts into the client directory.
   WARNING: you will overwrite any customizations to the FishCart
   scripts that you have made if you reinstall from the master source.

   ** NB: you cannot do this blindly.  There may be SQL database
   modifications that must be done concurrently.  The release notes
   will document this.

5. If this is the first time this cart has been installed, the SQL
   database must be created.

   To begin, change your working directory to the ./maint directory
   of the cart you just installed.
   
   The appropriate 'sql_*' files installed into the maintenance
   directory must be run through the SQL command line utility for
   that database.  The database may need to be created first;
   this will depend on the database engine in use.


   SOLID: When the 'fishcartsql' database has been created, issue
   the following commands to create the tables.  Note that the
   specific values may change for your installation.

   cd /usr/local/solid
   ./bin/solsql 'upipe solid' uname pword /install/path/sql_solid.sql



   MYSQL: to create the fishcart database tables, issue the
   following commands:
 
   mysql fishcartsql < /install/path/sql_mysql.sql
     OR
   mysql -u uname -p pword fishcartsql < sql_mysql.sql



   POSTGRES:
   as the user
   psql databasename < /install/path/sql_pgsql.sql
   OR 
   psql -u databasename -f /install/path/sql_pgsql.sql

   If using the second example above you probably need
   psql -u databasename -f /install/path/sql_pgsql_insert.sql



   NOTE FOR MULTIPLE CATALOGS AND/OR LANGUAGES: 
   Increase the maximum number of catalogs and/or languages as required
   by changing the 'MAXZONE' and/or 'MAXLANG' columns in the master
   table.  These are deliberately not maintained in the maintenance files
   and must be increased by hand.  They are initially set to 1.

   Sample SQL:  update your_master_table_name set maxlang=2,maxzone=2;


6. Any cart files that need to be customized for a particular FishCart
   can be placed in a unique directory ../fishcartsql.db/client/.
   The db.client_name file can be customized to include these files
   from that directory.  These files can then be modified independently
   of future updates.  The db.cust array file has examples of the path
   to these unique files.

   It is also possible to remove cart files entirely from the db.???
   file.  These files will not be overwritten in future installations.
   This will preserve unique modifications, at the price of having
   to manually modify the scripts to be compatible with future 
   FishCart releases.

   There are two example layouts in ./cust1 and ./cust2.  These two
   file sets output fixed length flat files in two different formats.
   To actually use these, you will want to copy them to a unique
   entry in the ../fishcartsql.db tree to remove them from CVS updates.

   THE FLAT FILES IN WHICH THE ORDERS ARE ACCUMULATED MUST NOT UNDER
   ANY CIRCUMSTANCES BE UNDER THE WEB TREE.  IF THERE SIMPLY IS NO
   ALTERNATIVE UNDER YOUR HOSTING PROVISIONS, THEY MUST NOT BE
   READABLE BY THE WEB SERVER.

7. This release requires that your Web browser be configured to 
   PHP3 parse the .php filenames.  See your Web server and/or
   PHP3 documentation for more information.

8. Open a Web browser and go to the ~/maint/index.php in your
   newly installed catalog.  A series of steps will be followed to set
   up a minimal catlog to get you started.  Some guidelines for initial
   entries are below.

   VENDOR PROFILE ADDITION

   Online Order Script:           emailorder.php
   Offline Order Script:          offline.php
   Order Confirmation Script:     emailconfirm.php

   LANGUAGE PROFILE ADDITION

   Language Profile Description:  English, Italian, Pig Latin, etc.
   Front Page Template:           blank
   Subcategory Template:          blank
   Product Display Template:      blank
   Error Template:                blank
   Show Cart Script:              showcart.php
   Show Geography Script:         showgeo.php
   Order Entry Script:            orderform.php
   Order Processing Script:       orderproc.php
   Final Order Script:            orderfinal.php

   SHIPPING PROFILE

   Description:                   Mars, Outer Mongolia, etc.
   Select a subzone.
   Select a shipping method.
   Shipping Charge Percent:       0.nnnn format
                                  (if Order Total Percent method)
   First/Subsequent Item Cost:    (if Line Item Cost method)
   Ship Charge Calc Script:       shipthreshper.php
                                  (if Order Price Threshold)
                                  shipthreshweight.php
                                  (if Weight Threshold method)
                                  shippercent.php
                                  (if Order Total Percent method)
                                  shiplineitem.php
                                  (if Line Item Cost method)

   *** NOTE: IF USING Line Item Cost, YOU MUST MODIFY shiplineitem.php
   ACCORDING TO YOUR MODEL.  READ THE shiplineitem.php COMMENTS, THEN
   UNCOMMENT THE APPROPRIATE SECTION OF CODE.

   Aux SQL Data Table 1/2:        blank
   Shipping Threshold Chart:      (if Order Price Threshold)
                                  enter shipping levels, e.g. 
                                  total to 20.00, shipping 3.00
                                  total to 40.00, shipping 5.00

   Weight Threshold Chart:        (if Weight Threshold)
                                  enter weight levels, e.g. 
                                  total to 20.00 kg, shipping 3.00
                                  total to 40.00 kg, shipping 5.00

   WEB PROFILE

   Description                    by now this is obvious
   Home Page URL:                 http://www.somedomain.com/
   Cart Home Page:                http://www.somedomain.com/cart_dir/
   Web Page Title:                <title>....</title> value
   Background Graphic URI:        default background for all pages
   Masthead Logo Graphic URI:     default top of page logo for all pages
   Background, TEXT, LINK, etc.   default values in the <body> tag
   Category Sort Field:           default ORDER BY field

   Header Product SKU:            Top of index.php promo SKU
   Header Product Text:           text for top of index.php promo
   Header Product Banner URI:     strip banner (460x60, etc.) image
    (default to blank for now)

   Footer Product SKU:            Top of index.php promo SKU
   Footer Product Text:           text for top of index.php promo
   Footer Product Banner URI:     strip banner (460x60, etc.) image
    (default to blank for now)

   Category Header Text:          blank
   Duration In Days in New:       30 (or whatever you want)
   New Items Icon Graphic:        greynew.gif
   New Items Masthead Graphic:    greynew.gif
   Special Items Icon:            greyspecial.gif
   Special Items Masthead:        greyspecial.gif
   View Cart Icon Graphic:        greyview.gif
   Zero Price Alternate           valid HTML as alternate to $0.00
   New Product Description Tmpl:  blank
   Add a "Contribution" box:      yes for non-profits that want to 
                                  take extra contributions.
   Automatically track viewer:    reserved
   
   NEW CATEGORY

   Description:                   Widgets, Videos, Moon Rocks, etc.
   Masthead Text:                 text displayed above the products
   Masthead Logo:                 displayed at top of page
   Promo Banner:                  blank
   Background Graphic:            blank, or URI to background graphic
   Category Display Template:     blank
   Category Sort Field:           ORDER BY field for this category
   Zero Price Alternate           valid HTML as alternate to $0.00
   Activate Subcategories         yes for a three layer product
                                  structure (activate in Master
                                  table also):
                                  Category -> Subcat -> Product
                                  (default is Category -> Product)
   Use subcat promo info:         yes if subcat promo info overrides
                                  the category level info
   Background, TEXT, LINK, etc.   values in the <body> tag
                                  FOR THIS CATEGORY ONLY


9. All further maintenance is done from the ~/maint/index.php
   screen.

10. YOU SHOULD NOW PASSWORD PROTECT ACCESS TO THE /maint DIRECTORY IN
    YOUR WEB SERVER TO PREVENT UNAUTHORIZED ACCESS TO YOUR CART.

	You should also activate the ./maint/croncart.php file in your
	newly installed cart to be run after midnight.  This will perform
	ongoing maintenance; you may want to study the file to make sure
	that it is doing what you want.  Part of its function is to 
	clean up unplaced orders that are over two days old to keep the
	order table from filling with useless cruft.
	
	An order summary report for the preceeding day will be created by
	the cron script that will be emailed to the order email address
	in the vendor table.

	Before running the cron script, you may need to modify line 1
	to point to your standalone php interpreter.
	
	For a Unix environment, you will typically set line 1 to 
	#!/usr/bin/php -q

	For a Windows environment, you will typically set line 1 to 
	#!c:/php/bin/php.exe -q

	To run the cron job on a Unix system, typically you will run
	'crontab -e' and add a line like this to run the script at 0215:

	15 2 * * * cd /path/to/.../maint; ./croncart.php

	To run the cron job on a Windows server, you will need to run 
	the scheduled tasks tool.  Set it up to start the job in the
	/maint directory of the installed cart.

	NB: IN PARTICULAR, CREDIT CARD NUMBERS ARE DELETED FROM CUSTOMER
	PROFILES WHERE THE LAST ORDER WAS PLACED OVER 10 DAYS AGO.  THIS
	IS DESIGNED TO LIMIT EXPOSURE IF CREDIT CARD NUMBERS ARE RETAINED
	FOR EACH ORDER.  YOU MAY WISH TO CHANGE THIS TO FIT SPECIAL
	REQUIREMENTS FOR YOUR CART.

11. Modify your Web server configuration for this virtual host to 
    allow index.php as one of the default page options.  For Apache,
	this is done by the DirectoryIndex directive.

	Don't forget to restart the Web server if needed so the changes
	take effect.

11. Congratulations!  Now to see your new cart, go to 
    
	http://www.DOMAIN.COM/DIRECTORY/

	  OR

	http://www.DOMAIN.COM/DIRECTORY/index.php


=====================================================================
FishNet(r), Inc.
850 S. Greenville, Suite 102
Richardson,  TX  75081
voice: 972.669.0041
fax:   972.669.8972