Installing FishCart.. 
Documentrelease: 9   1 december 2004   (Dec 1th 2004)

B. van Ouwerkerk    bvo at dont.spam.me.atz.nl

This is a guide into installing FishCart and debugging a basic
install. This is a work in progress and you will find the latest
version of this doc at fishcartdocs.bvanouwerkerk.nl

Please remove the dont.spam.me. from the domain name to get the
real address.

FWIW, I don't want to get email with offers for whatever great product
you might want to sell. If I need something I will find it.

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

Table of contents:
     
   1 Introduction

   2 Links 

   3 Known issues with MySQL 4

   .. security
      .. some general things
      .. PHP security
      .. backup your files
      .. backup your database
   
   .. other FischCart related resources

   .. How to install a Linux server for testing your cart

   .. FAQ

   .. I want to help developing FishCart
   

Whenever I explain something I might leave things out. It means
I don't think it's important for you to know.

Although you will find information about installing/compiling PHP,
MySQL and Apache on a Linux server, it's not ment as a complete
manual into these packages.


This document contains:
- instructions how to install FishCart
- where to gather more information about MySQL and PHP
- example
- some security information
- how to ask questions on the list

DISCLAIMER:
Although I tested the instructions and believe the information and instructions
below are accurate I don't take any responsibility if things go wrong.


This document is written with root access in mind. I added some notes
about what you can do if you host with an ISP.


Credits:
Some parts of this document originate from the INSTALL.MYSQL doc.

Commands you need to type are put between "" if two commands are between
separate "" they need be entered separately.

More information about MySQL and PHP can be fount at www.mysql.com and
www.php.net.  Both provide a manual which can be downloaded.

There are some hints on how to solve problems below the instructions and
example.

You will need a working install with at least MySQL, PHP and Apache.
Information about how you can install these yourself is provided in one
of the other chapters.

<old information, not needed for current versions>

Check the include path in php.ini to make sure it has './' defined. If
you're running on PHP3 it's called php3.ini
 
   Locate the php.ini file. You do have a few options to do so:
   - use locate, the syntax is
     locate php.ini
   - use find, the syntax is
     find php.ini /
       

   If you don't like to log in via SSH or telnet you could reach the same
   result by creating a .php file and call it whatever you like.. 
   (example: testit.php) and add only one line 
     <?phpinfo();?>
   Upload it to your document root and open it in your browser like this
   http://www.yourdomainname.extention/testit.php
   One of the lines reads Configuration file.
   Another lines reads include_path..
   Using the last method will give you all the information you need. You 
   can also use it to check these settings when you're not allowed to 
   use telnet or if you're chrooted to your homedir.
   
   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 - >

include_path    =  "./"   
              < - end snip - >


If you're not using your own webserver you need to contact your ISP to request
this setting to be changed.

</old information, not needed for current versions>


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

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

In case you use Apache
In httpd.conf there is a DirectoryIndex which says (at least) index.html make
sure index.php and index.php3 are also put into this directive.
To let Apache parse PHP using PHP you will also need the following (for PHP4)
AddType application/x-httpd-php  .php

If you install/run an old version of FishCart you may have a version with
PHP3 files (.php3) in which case you also need to add:
AddType application/x-httpd-php  .php3

Adding the line with .php3 will parse .php3 files through PHP instead of showing
them as text.

Remember to stop and start Apache after making changes to the httpd.conf

Once again.. You might need to contact your ISP to changes these settings.

If you're hosting at an ISP who is unwilling to add these to his httpd.conf
you can try to add these to a .htaccess file. 
Sometimes it might be a better idea to move over to an ISP that will.

Let's do some work:
Unpack Fishcart tar wherever you want. /usr/local is a good place
cd to the directory created while running tar (for V2 this would be fcsqlv2).

      Type "tar xvfz name_of_the.tgz"  If you've got a more recent version
                                        check the filename and change the
                                        command to match this new filename 
      Type "cd fcsqlv2"

      Type "./install.pl -d mysql"

Next, copy the db.cust file that we created by running the command above 

      Type "cd ../fishcartsql.db"
           "cp 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.
In this document I will refer to this newly created file as db.your 


Now we are going to edit the installation template. You know, the file you
created a few seconds ago. Do NOT change the db.cust file but use the copy
of the file instead.


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

   I.   There are those who believe that you don't need to specify $custID 
        I would recommend to do it anyway. 

   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  If you want your shop to be accessed by www.domainname.tld then you
        should leave $fcroot empty.

   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 (in most cases localhost will do just fine for a
           locally MySQL server).  

        b. Edit the databasename entry to indicate the name of the database
           you created. You ISP might have choosen a name for you in which
           case you need to write it in your db.cust

        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. Once again these might
           be appointed by your ISP. If you want to find out where you are
           just use telnet or SSH and type the command "pwd" this will give
           you a complete path to your current location. 

        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. If you host with an
           ISP they will have it setup correctly.. 

        f. Don't forget to enter a password for public and admin.

        g. Although the comments in the db.your might say something else
           you really should enter a username and password for SQL spilt
           credit card delivery. Not doing so will cause more trouble
           then you might expect.

Next, we are going to create a database. This is done via mysqladmin:
Type "mysqladmin -u xxxx -p create databasename"
        you may use fishcart as databasename of any other name.
xxxx is the name of the mysql superuser. In most installs I encountered this
was root.

Perhaps your provider already created a database for you, in that case you should
use that one. No need to create a new database. You might contact your ISP before
you request a MySQL database from them. Live is mucht easier if you can create
your .sql files and let them run those :) Not to mention the fact that you need 
sufficient rights to run those scripts.. 

   Type "cd ../fcsqlv2" and copy the mvupload script (found in fcsqlv2/maint)
   to the appropriate location to enable uploads to cart
    
   If running PHP(3) 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, copy the mvupload script into a
   path in your executable path.
   
   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(3) file.  However, running
   from a script allows other things to be done to the file as needed
   without modifications to the upload.php(3) 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 we are going to install the files to the userdirectory. Make sure
your current directory is /fcsqlv2



 Type "./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
            ./maint area where your cart is.
     lang   installs only the language scripts

An example: Let's assume we have created a file called atztest, and we want to
install everything. The command would be: "./install.pl atztest all"

Now all .php files are copied into the right location. Next we are going to
setup the MySQL database and users.

Next run the following commands:
  mysql -u xxxx -p databasename </location/of/your/directory/maint/sql_mysql.sql
  mysql -u xxxx -p databasename </location/of/your/directory/maint/sql_mysql_users.sql
After each command the MySQL server will ask for your password.

Normally an ISP will grant you enough rights to create tables so the sql_mysql.sql
shouldn't give you much problems. The sql_mysql_users.sql might become a problem
since you need specific rights to create users. You might want to ask your ISP
to run the sql_mysql_users.sql 
Since some ISP's give you two users (1 webuser with minimal rights and 1 admin 
with insert/update and many other rights) you could try to use these instead of
the users you would have entered into db.your. You will still need to enter
loginnames and passwords for those users into your db.your because those will
be set into several .php files.


Now you're about ready to launch your webbrowser you MUST password protect
your maint directory. Not doing so is insecure and could lead to all sorts of
unwanted activity. In addition to password protection you could think about
moving the .sql files out of the documentroot. If the .htaccess fails your
.sql files aren't shown to those who know what to look for. You know.. 
if someone just types 
http://www.your_domain.extention/maint/sql_mysql_users.sql
he/she will know your login and passwords for your database. 


Start your browser and you can start putting products into the database.


Getting a bit confused?? afraid you won't make it?? I've been kind and added
an example:


I'm going to show you the steps I took from scratch in a life example.
I will call my installation template "atztest" my sql database is going to be
called "atzbees". The name of my Fishcart admin is going to be "admid" with
"pass" as password and the name for the public user is going to be "web" with
"open" as password.  The document root where my files will be is
"/opt/usr/atz/www/htdocs" My cgi-bin is "/opt/usr/atz/www/cgi-bin"
I don't run PHP in safe mode.

Root is my MySQL superuser, it is on every server :)
The MySQL user has a different password.

One remark: the names and passwords above has been tested on a server.
After completing this example the names and databases are removed.
I suggest you use other names and passwords.  It's best to pick one not
to be guessed easy, normal rules apply to this.

Here goes:

I copied the file to my personal account on the webserver. 

Logged into the server on my own account and entered su to log in as
root.

Went to my own directory and typed cp name_of_the_file.tgz /usr/local
You need to be root otherwise you shouldn't have enough rights to
write to this directory. If you get an error saying you don't have rights
to write there you need to type su to login as root.

Then I issued the command "tar xvfz name_of_the_file.tgz"

Next things:

"cd fcsqlv2"
"./install.pl -d mysql"
"cd ../fishcartsql.db"
"cp db.cust atztest"
"pico atztest"
in which file I made the settings as outlined above.
"mysqladmin -u root -p create atzbees"
mysqladmin asks for the password
"cd ../fcsqlv2"
"cp ./maint/mvupload /opt/usr/atz/www/cgi-bin"
"./install.pl atztest all"
"cd /opt/usr/atz/www/htdocs/maint"

"mysql -u root -p atzbees </opt/usr/atz/www/htdocs/maint/sql_mysql.sql"
"mysql -u root -p atzbees </opt/usr/atz/www/htdocs/maint/sql_mysql_users.sql"

DONE.


A few hints to solve problems (in addition to the ones found on fishcart.org):
- try if normal html files are being served
- if you get connect errors check if you left any password entries open
  in the custom file
- if you get connect errors use telnet (secure shell if possible) and
  connect to the mysql database via the Linux mysql client you can do this
  by typing:

  "mysql -u uname -p"
  "use databasename"

  uname is the username giving you a hard time, databasename is the name of
  your database. The -p makes MySQL ask for your password.
- connect errors usually mean you didn't enter all needed usernames and 
  passwords in the cust.db. 



3 Known issue with MySQL 4

  There have been some changes to how MySQL works with lock_tables. For the
  lock tables in FishCart to work correctly you need to run a few queries
  which grant lock tables to a few users.

  In general MySQL 3 is used therefore it's not reasonable to assume that 
  support for MySQL 3 will be dropped soon.

  For the time being a special .sql file has been added for MySQL V4. Anyone
  who needs to install FishCart with the Perl installer should replace the
  sql_mysql_users.sql with the MySQL 4 version.

  Problems with locking tables will be noticed with most versions of FishCart.
  You can run the needed queries manually or as part of the installation 
  process. To be able to run them manually you will need a shell or a tool 
  like phpMyAdmin.
  




.. Security

   .. . .. Some general things about security
100% secure is an illusion. But you can do several things to keep your
FishCart install as secure as possible.

Copy files using secure FTP or pscp 
Using pscp the command is:
pscp -v filename username@server:/dir/to/place/files
you can also download files this way:
pscp -v username@server:/file_name_to_copy location_to_copy_to
This will prevent others from electronic eavesdropping which is possible
running normal FTP.
You should not really be alarmed if your ISP allows FTP, I just want you
to know about other ways..

Never use the same login/password for a shell account and a MySQL account.
If you've got a shell account it really should be a SSH instead of normal
telnet. From the sysadmin point of view telnet (insecure) is really 
asking for trouble. If your ISP allows normal telnet it's about time they
should install SSH. Same functionality for the user, but more secure.
If they still run telnet instead of SSH you might want to consider to
move over to another ISP.


   .. htaccess
Several carts don't have any kind of protection. Though not the most 
secure way htaccess does provide at least some protection.

A .htaccess file could look like this:

AuthUserFile /path/to/.htpasswd
AuthGroupFile /dev/null
AuthName 'Members only'
AuthType Basic
<Limit GET>
require valid-user
</Limit>

The . in .htaccess and in .htpasswd are very important. A dotted file is
hidden.

Next you create a password for a user, you will need to do this in a shell:
htpasswd -cb .htpasswd user_name password
for every next user you create:
htpasswd -b .htpasswd user_name password

If you con't enter the d flag you will be prompted for a password.

You will find more information on .htaccess at http://www.apache.org
and if you enter htpasswd on the prompt.



  .. , .. PHP security
It's better to place files with loginname and password outside your
HTML_root. This will prevent reveiling these combinations to the outside
world. This wil occure if a sysadmin makes a mistake in the server
configuration.

Safe mode does help to keep PHP more secure. 
If safemode is enabled PHP checks wether the owner of the script which 
calls a file is the same as the owner of the file being called.
You can verify if your ISP has safe mode on by opening a file with one
line:
<?phpinfo();?>
But you could also use a little script like this:
<?php
$line_array=file("/etc/passwd");
echo $line_array[0];
print ("<br>");
echo $line_array[1];
print ("<br>");
echo $line_array[2];
print ("<br>");
echo $line_array[3];
?>

If this says something like you can't open the file cause safe_mode is
in effect you're safe. If you're getting all sorts of usernames it's time
to contact your ISP.
If you can open /etc/passwd someone else might be able to open your
files with passwords like public.php If that someone gets your passwords
he/she might be able to extract your data from the database.



   .. backup your files
   Don't wait until you loose some valuable changes you made, even 
   experienced coders may muck something up pretty badly. So, when
   you're changing code it's always a good idea to copy changed files to
   a safe location. You may even want to copy files to a removable media.
   It's highly recommended to rename files before you start editing them.
   As soon as you made an adjustment and you like it, it's about time to
   copy the file to a new filename and continue your changing and testing
   of the code. 
   This way you can always do one step back to get the latest known good
   code not doing so may result in you doing the same work over and over
   again.
   It's usually a good idea to backup your work daily. If you're spending
   a lot of time coding you may want to backup your work.
   Tar is a great tool to create a backup. If you cd to one directory 
   above the one holding your cart you can do a:
   tar cvfz backup.tgz ./name_of_the_dir

   KEEP YOUR BACKUP OFFSITE! never ever leave it on the server.

   .. backup your database
   Unless you'd rather spend time typing everything again after a systemcrash
   or just someone stupid enough to drop the database (or a few tables) you
   must create backups of your database.
   There are several ways to do this, I will describe several options below.
   Which way you choose will depend on where your database is hosted. 

   KEEP YOUR BACKUP OFFSITE! never leave it on the server.
   
   Use tar, cp or other systemtools
   In order to use these you must make sure no table is opened otherwise your
   backup will be useless. In order to use this you must bring the MySQL server
   down. This is done my typing
   mysqladmin -u root -p shutdown
   next you will have to type the mysql root users password.
   As soon as the MySQL server is down you will be able to create a backup.
   Using tar it looks like this:
   tar cvfz databackup.tgz /path/to/location/of/database 
   you can choose whatever name you see fit instead of databackup.tgz

   If you need to restore you can simply use
   tar xvfz and the database will be untarred.

   If I use tar to create backups I always prefer to CD to the directory
   just above the data. Assuming you installed MySQL in the default location
   (/usr/local/mysql) that would mean I CD to /usr/local/mysql/var where databases
   will normally live. You will see several directorynames holding lots of files.
   Those files hold your data. If you tar from the var directory and the
   name of your database is shop then you will create your database by:
   tar cvfz databackup.tgz ./shop


   Use mysqldump
   Let's assume I want to backup the database shop. The user who is going to
   perform this task is testadmin and the password is stupid.
   mysqldump --add-drop-table --lock-tables -u testadmin -p'stupid' shop >backup.sql
   This line will perform the following tasks:
   - add the DROP TABLE if exists command to the archive to prevent errors if a
     table already exists.
   - lock tables to prevent modifications
   - create a file called backup.sql
 
   .. Troubleshooting
      Read this document again and follow each step. If you're bombed with 
      errormessages you probably didn't follow each step or you changed
      the order. 

   .. How to configure a Linux server for testing
      Although this goes well beyond the scope of this document it may be 
      useful for someone. How long it takes to install the server depends
      highly on the type and speed of the hardware. 
      
      This instruction should not be used to configure a productionserver.
       1. what you need
         - a Linux distro like Slackware, RedHat, Mandrake, Suse, Debian
         - sourcecode tars from www.apache.org, www.mysql.com and www.php.net
           for this server we don't use SSL. If you want to use SSL you
           wil need to download mod_ssl too.
         - an old PI or PII with at least 32Mb memory will do the job nicely
           if you can't use an old computer you could use dual boot 
           Windows/Linux. Lilo (a bootmanager) will allow you to choose
           during startup.
           An old computer will be very slow during the initial install.
           As soon as it's up and running it doesn't matter that much since
           you will not use it as a production server.
       
       2. Follow the instructions of your Linux distro of choice to get it
          up and running.

       3. If your distro installs MySQL, PHP and Apache for you it might be
          possible to use these. If you're only using it to test one website
          it could do the job for you.
          I was far from impressed by the results of default installs so I
          decided to compile from source myself.
          If you need any help with the default installs please contact the
          vendor from who you downloaded or bought the distro.
          Don't ask me to give this one on one support.

       4. A very comprehensive explanation of how to install Apache, MySQL
          and PHP is found at the devshed.com website. You will find a link
          on the links page at fishcartdocs.bvanouwerkerk.nl
          It will even help you to install SSL.          


   .. FAQ    
      

   .. mailinglists
When sending messages to a mailinglist you should remove your username(s)
and password(s) from scripts or fragments of scripts. You should remove
them or preferable replace them with not existing username/pw combinations.

There is an active group of FishCart users, with different levels of
experience. But they are all willing to help you.




.. How to ask questions on the FishCart list:
Nothing special, the things mentioned below are valid on most lists I know.

Don't yell BUG before you're 100% sure you didn't screw things up yourself.

If you do report a bug or an error in the code your message should explain
which script gave the error, which error and how you solved it. Please
include the code snipped and on which line it should be included/changed.

Use a subject that covers the messages. Help or mayday doesn't do the job.
This will also help others to find help if they check the archive for a 
clue.

Explain what you tried, and where it went wrong. If you tried to add some
of your own code you should provide all of it, if it's more then say
30 lines you should put it online (don't call it .php since that will
make your code invisible) and provide the list with a link.

Remember that none of the ppl on the list receives payment for their help
so be polite DON'T YELL and don't demand an answer.

Post plaintext/ASCII and NOT HTML. You may think it looks great to use
your favorite font but you shouldn't use it on this or any other list.
HTML was never ment for using in e-mail. It's using more bandwith then
needed and it's a BIG securityrisk.
Not to mention the fact that some people may not have a mailclient that
supports HTML, the tags are really looking awful in those clients.

Don't use long signatures. And you should only quote the part of the 
messages you're answering. 

Search the archives before asking questions. 

And.. as soon as you're an experienced user too we'd love to keep you 
around to help other newcomers..





That's all for now.. Happy coding.