FishCart Installation Instructions

This INSTALL file has two sets of instructions (BRIEF and DETAILED).  Read
the instructions you feel best fit your level of expertise.  I would
recomend you be conservative in your judgement ;-)


*********************** BRIEF INSTRUCTIONS *******************************

FIRST TIME INSTALLATION USING MySQL AS YOUR DATABASE

The "I hate README files" or "POWERUSER INSTRUCTIONS" (don't be afraid to
read the detailed ones)

1.  Ensure Apache, PHP, and MySQL talk to each other
2.  Unpack latest Fishcart tar wherever you want
3.  Change to directory ./fishcart_v3
4.  Run ./install.pl -d mysql
5.  Check the include path in php.ini to make sure it has './' defined.
6.  Make mvupload available :
	a. If running in safe mode then copy the mvupload script into safe 
	   mode executable directory for uploads to work.
	b. If NOT running in safe mode you should not have to make any
       changes.  The upload.php script uses the move_uploaded_file()
       function to move the file to its final destination.
           
	ONCE YOU ARE FINISHED WITH THESE STEPS, YOU NOW MUST FOLLOW THE
	FOLLOWING STEPS FOR **EACH** FISHCART YOU WISH TO INSTALL

A. Copy the ../fishcartsql.db/db.cust file to new file
B. Create MySQL database for your first cart (use the scripts located in 
   the scripts directory if you need them)
C. Create two users for this db (one superuser and one limited)
D. Modify new db config file to suit your needs (from A above)
E. Change back to fishcart_v3 directory and run:
	./install.pl <new file> section_to_install
    Where section to install can be:

   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




Yep, they were brief but you know all there is to know about computers so
why did you need details?  If you overestimated your abilities, then read
on!


********************* DETAILED INSTRUCTIONS ******************************

FIRST TIME INSTALLATION USING MySQL AS YOUR DATABASE

           ***************** STEP 1 ************************* 
Make sure that PHP and mysql work on your system.  !!!EXTREMELY IMPORTANT!!!
           **************************************************

   To ensure that php works, copy the file phptest.php into your web directory 
   on your host.  The file fishtest.php is locate in the XXX directory.  Point 
   your browser to this file (for example:  http://localhost/phptest.php) and 
   see what output it produces. If it produces an error then go to 
   http://www.php.net and read how to configure php with your web server and 
   mysql.  For those of you who would like to use a script to get apache, php, 
   and mysql to work together - guaranteed! - then go to: 

   http://mapis.sourceforge.net/ 

   where you can download MAPis (Mysql Apache Php install script) a shell script 
   to help you install these programs.

   An alternative is:

   http://members.xoom.com/xeer/software/install-webserver-0.1.tar.gz  

   that installs the tarballs via a perl script.

   Both scripts work without any problems.

   Once you get these parts working together then you can carry on to the next 
   step.  It is strongly advised that you do not skip this step.  There are more 
   questions on the listserv regarding configuration problems than I care to 
   recall so be sure that you get this right before continuing with the 
   installation.


           ***************** STEP 2 ************************* 
Download the latest file from http://www.fishcart.org/download.html
           **************************************************
           
   If you can't do this then hire someone to follow the remaining steps!


           ***************** STEP 3 ************************* 
Save the file to your directory of choice (/usr/local is a good place to start). 
           **************************************************

	cp fishcart-X.XX.tgz /usr/local


           ***************** STEP 4 ************************* 
Unpack the files from the gzipped tar archive (the file you downloaded)  
           **************************************************

	tar zxvf fishcart-X.XX.tgz


           ***************** STEP 5 ************************* 
You will now have a directory called "fishcart_v3" so change to that directory. 
           **************************************************

	cd ./fishcart_v3

   REMEMBER - You are reading the INSTALL.MYSQL file!  These instructions are 
   for those who are using MySQL as their database.  If this still applies to 
   you then please follow the instructions below to complete the installation of 
   fishcart.

   For example:  

	cd /usr/local/fishcart_v3


           ***************** STEP 6 ************************* 
Run the install script and specify mysql as your database of choice (a wise one!)
           **************************************************

        ./install.pl -d mysql

           
   This command does four things (read these points if you want to know the 
   details of what is going on with this step):

   i.  Creates a "./database.pl" file that sets a variable ($databaseeng) to
   the proper value.  This variable will be required later on in the
   when you run the ./install.pl script again.it will be used by the install perl
   script "./install.pl" to set the database to mysql).

   ii.  Copies the appropriate public_*.php and admin_*.inc files to
   public.php and admin.inc; it is these that will be installed in each cart
   and modified as needed.

   iii.  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.

   iv.  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.


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


   Locate the php.ini file.  The darn file has changed names several times so 
   it might be php.ini instead of php.ini.  Do a search with your favorite 
   search tool (mine is locate) and find it.

	locate php.ini
   or 
	locate php.ini

   Once you locate it, edit it and make sure that the line that looks like (see 
   the "include_path" statement below):

              < - snip from php.ini file - >

;;;;;;;;;;;;;;;;;;;;;;;;;
; Paths and Directories ;
;;;;;;;;;;;;;;;;;;;;;;;;;
include_path	=                	; UNIX: "/path1:/path2"  Windows: "\
doc_root		=		; the root of the php pages, used on
user_dir		=		; the directory under which php open
;upload_tmp_dir	=	                ; temporary directory for HTTP uploa
upload_max_filesize = 2097152       	; 2 Meg default limit on file upload
extension_dir	=	./		; directory in which the loadable ex

                   < - end snip - >

the line should now read:

include_path	=   ./                ; UNIX: "/path1:/path2"  Windows: "\pa


   

           ***************** STEP 8 ************************* 
Copy the mvupload script to the appropriate location to enable uploads to cart
           **************************************************
   
   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.  In this case, the
   possibility exists to keep only the file content between the
   <body>...</body> tags.  This is presently not used but will be
   useful in the future when templates are running.


***********************************************************************************
NOW THAT YOU HAVE COMPLETED THESE STEPS, YOU ARE NOW READY TO INSTALL A SHOPPING
CART FOR EACH STOREFRONT YOU DESIRE.  THE HARD PART IS DONE!
***********************************************************************************


                  INSTALLATION STEPS FOR EACH FISHCART


           ***************** STEP A ************************* 
Copy the db.cust file that we created in STEP 6 (above) to a new file
           **************************************************

	cp ../fishcartsql.db/db.cust yourname

   Note that yourname could be any name you desire and does not need 	the db 
   prefix (i.e., does not need to be db.yourname).  Certain things are 
   important.  First, the file must be in the same directory (fishcartsql.db) as 
   the original db.cust file.  Second, when you edit the file (next step) make 
   sure you edit your new file and not the db.cust file.


           ***************** STEP B ************************* 
Create the MySQL database for fishcart - since this is your fist time installing.
           **************************************************

   To create a mysql database for your FishCart, issue the following    
   commands:

	mysqladmin create YYYY
	
   where YYYY is your database name of choice (e.g., widgetco)

   If you get an error when issuing this command then you will need to specify 
   the proper user:

	mysqladmin -u XXXX -p create YYYY

   where XXXX is your admin username.  MySQL will prompt you for the admin 
   password so supply it upon command.

   NOTE:  If you are on a hosting service system, your system administrator will 
   provide you with a database.  If this is the case, be sure to ask him/her 
   about the next step.


           ***************** STEP C ************************* 
Setup database priveleges for the database you just created in the previous step
           **************************************************

   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.

   Edit the script sql_mysql_users.sql to reflect the usernames you would like 
   to use for admin but leave the other user alone!

   You will see the lines:

       GRANT ALL PRIVILEGES ON YYYY TO XXXX@localhost
       IDENTIFIED BY 'ZZZZ' WITH GRANT OPTION;

	   GRANT USAGE ON YYYY TO QQQQ@localhost
	   IDENTIFIED BY 'PPPP';


   Simply replace the YYYY with your database name, XXXX with your admin 
   username and ZZZZ with the password you would like to use for the admin.  In 
   addition, change the QQQQ to the public username and PPPP to the public 
   username's password.

   Run the scripts provided in the scripts directory by issuing the command:
   
	mysql -u XXXX -p mysql < /usr/local/fishcart/sql_mysql_users.sql

   Again, XXXX is the admin username.  It will prompt you for the password just 
   like the previous step.

   *** 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.

	
           ***************** STEP D ************************* 
Modify the new file to reflect the installation location and database information
           **************************************************

   There are only a few places that MySQL users should take notice in this file 
   while editing.  Here are some guidelines:

   i.   I did not specify $custID in any of my databases and have had no adverse 
        reactions but I only use one catalog for each client.

   ii.  Make sure you get the prefix (e.g., www), domain (e.g., freshmeat), and 
        suffix - $tld in this file (e.g., net, org, etc) correctly set.  No brainer 
        here.

   iii. Make sure that you only change the values on the RIGHT side of the statements 
        following the line:
        
		%inst = (

        a.  You should edit databasehost if your database is located off of the 
            present server (localhost will do just fine for a locally located MySQL 
            server).  

        b.  Edit the databasename entry to indicate the name of the database you 
            created in STEP B.

	c.  Edit the docroot and secroot entries to indicate where you are going 
	    to keep the fishcart and its associated files for both non-secure and 
	    secure access, respectively.

	d.  You can keep the other directories the same unless you have some preference 
	    otherwise.

        e.  Be sure to specify the proper owner (as in UNIX's chown) for both 
            the account and secure account directories.

        f.  Finally, make sure you specify the passwords that you provided above 
            in STEP C.


           ***************** STEP E ************************* 
Change directories to the ./fishcartsql directory and run the install script again. 
           **************************************************

	cd /usr/local/fishcartsql (consistent with this example install)

	./install.pl <dbname> <option>

   Where dbname is the name of the database you chose in STEP A above and option 
   is one of the following:
   
   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

   The actual cart scripts that interact with the user are installed into the 
   directory that you specified in the modified db.cust file in STEP C.  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.

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

           ***************** STEP F ************************* 
Create the tables in the database you created in STEP B
           **************************************************

   If this is the first time this cart has been installed, the SQL
   database must be created.  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.

   To create the fishcart database tables, issue the following commands:

   	mysql yourdbname < /install/path/sql_mysql.sql

   	OR 

   	mysql -u uname -p yourdbname < sql_mysql.sql

   For example, if I named my database in STEP B widgetco and used dude as my 
   admin username, then I would issue the following command:

	mysql -u dude -p widgetco < sql_mysql.sql


   In V2 the split credit card delivery system is installed by default
   as part of the database installation.  There is a zone level flag
   to control whether or not CC numbers are delivered by the split
   number method.
   

   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;


           *** SIDE NOTES REGARDING THESE STEPS UP TO NOW ***

   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 file 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.


           ***************** STEP G ************************* 
Make sure that the web server can parse *.php filenames
           **************************************************

   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.


           ***************** STEP H *************************
Open the mainenance page in your new catalog and setup a minimal catalog
           **************************************************

   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.inc
   Offline Order Script:          offline.inc
   Order Confirmation Script:     emailconfirm.inc

   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:       threshpercalc.php
                                  (if Order Price Threshold)
                                  shipthreshweight.php
                                  (if Weight Threshold)
                                  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


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


           ***************** STEP H *************************
Setup security on the maint directory to keep intruders out!
           **************************************************
           
   Let me repeat this....

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

   You can do this one of several ways.  The quickest, but not most secure would 
   be to use .htaccess (not terribly secure but will do the trick for a quick, 
   temporary security fix).  Other suggestions are numerous and beyond the scope 
   of this INSTALL doc.


           ***************** STEP I *************************
Modify your web server's virtual host settings to allow index.php as default page option.
           **************************************************

   For Apache, this is done by the DirectoryIndex directive.

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


           ************ CONGRATULATIONS! ********************

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

	  OR

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

Where DIRECTORY is the directory you specified in STEP D, part iii. section c. 
and the address should be self-explanatory by now!  Good luck customizing your 
cart.

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