installation.txt for distribution with GeoClassifieds /**************************************************************************\ Copyright (c) 2002 Geodesic Solutions, LLC GeoClassifieds All rights reserved http://www.geodesicsolutions.com This file written by James Park IT Project Manager see license attached to distribution \**************************************************************************/ Thank you for purchasing this GeoClassifieds software. Please follow the steps below to complete this software's installation to your server. **************************** INSTALLATION PROCESS **************************** 1) Uploading files to your site--------------------- Upload the following files that come with this distribution maintaining the directory structure to the location on your website where you want the front page of your classifieds to be displayed: - all php files in the root of your software distribution - admin/(all folders and files) - classes/(all folders and files)(this includes adodb.inc.php and the drivers directory) - images/(all folders and files) - sql/(all files) - setup/(all folders and files) - user_images(folder - contains no images by default) 2) Configuring for Database type------------------------- GeoClassifieds also requires ADODB to work properly. ADODB version 1.90 has been included in this distribution to speed installation. You can go to http://php.weblogs.com/ADODB or probably one of several other places to get the latest version if you wish. Unless you make changes to index.php GeoClassifieds looks for ADODB in the classes subdirectory. Make sure the adodb.inc.php file is in the classes directory as well as the drivers/ subdirectory containing all of the ADODB database drivers (or at least the driver to the database type that you will be using). classes/adodb.inc.php adodb.inc.php will look for the appropriate database wrapper in the classes/drivers directory GeoClassifieds comes set for using a MySQL database. If you need to use a different database type uncomment that wrapper class you need to use in index.php and admin/index.php (and comment out the MySQL wrapper class). At the top of the index.php and admin/index.php you will see a list of database wrapper classes. 3) Setup (Create) your Database---------------------------- Most hosting companies will provide you with a control panel for your domain (website). Within that control panel you should be able to access a MySQL database creation tool (or they will display the name of a preconfigured database for you to use). Simply create a new database (if there is not already one created for you) by giving it a name (i.e. geoclassifieds). Then, you likely need to create a user for that database (sometimes your control panel username will be assigned by default). If not, create a user, assign that user to the database, and then set the permissions for that user to "all". The information you just entered will be needed for the next step. 4) Open up the config.php file on your pc using "notepad" or a similar text editing tool and enter the appropriate Database Connection Information. IMPORTANT - DO NOT LEAVE ANY EXTRA SPACES OR LINES IN THE CONFIG.PHP FILE. SIMPLY REPLACE THE REQUIRED INFORMATION WITHIN THE QUOTES. Then, ftp the updated config.php file to your server, overwriting the old file. $db_host = "server-host-name"; Note: this is usually "localhost", but can also be an ip address, etc. $db_username = "your-username"; $db_password = "your-password"; $database = "your-database"; 5) Populating the Database---------------------------------- YOU HAVE TWO OPTIONS: 1) SETUP SCRIPT (recommended) 2) POPULATE THE SQL TABLES USING PHPMYADMIN %%%%%%%%%%%%%%%%%%%%%%%%% SETUP SCRIPT OPTION %%%%%%%%%%%%%%%%%%%%%%%%% The software distribution you have received contains a folder called "setup" which is located at the root of the installation files. Therefore, once you have completed the steps above, simply type in the URL to the setup folder within your browser window and follow the instructions on your screen. If you choose this option, you DO NOT need to proceed any further with this document, unless something goes wrong during the setup process. If this happens, please proceed with the PHPMYADMIN OPTION below and then continue with Step 6) of the installation. Example URL: http://www.yourclassifiedssite.com/setup/ %%%%%%%%%%%%%%%%%%%%%%%%% PHPMYADMIN OPTION %%%%%%%%%%%%%%%%%%%%%%%%% SQL Instructions The SQL to set up the database structure is in the file sql/initial.sql distributed with this download. We recommend the (at least temporary) installation of phpMyAdmin (or some other equivalent database manipulation program) to set up the database. phpMyAdmin can be downloaded for free at: http://www.phpmyadmin.net Once phpMyAdmin is installed you can upload the sql/initial.sql file into it to be executed or cut and paste the contents of sql/initial.sql into the textbox within phpMyAdmin to execute it. Once executed successfully the database is setup. PhpMyAdmin is very useful and we recommend either keeping it installed permanently (if you do password protect it) or keeping it close at hand where it can be uploaded to your site quickly. It can be very useful as a second way to get database backups or in a server db catastrophe. GeoClassifieds was built using MySQL and has only been tested internally with MySQL. There are no complicated sql statements.....But there is always an exception so some modifications may be required to work with other databases (data types, etc). 6) If you received a file that is named something similar to "upgrade_classified.php" then you will need type the address to this file in a browser. I.E. www.yoursite.com/somefolder/upgrade_classified.php". This file checks your database to verify that it is current with the latest changes. It is ok to refresh this page as the file will not adjust the database unless there are changes that have not been made yet. 7) Configuring GeoClassifieds---------------------------- If you installed GeoClassifieds to your root web directory the link will be: http://www.yoursite.com/admin/index.php The default username and password for the admin are: username: admin password: geodesic If a blank screen is all that appears there is a problem in connecting to the database. Retrace your steps in setting up the database. Make sure the adodb.inc.php and the classes/driver/adodb-%%%%.inc.php wrapper file to the appropriate database type is present. If the blank screen persists check the existence of the database table and data necessary to populate some of the tables are there through the use of PhpMyAdmin. Once logged in change the following settings by clicking the appropriate buttons. These setting are required to be configured for your site so that GeoClassifieds can work properly. On each of the pages where these configurations are necessary are other non-critical configurations to discover. We'll just go through the necessary ones here: SITE CONFIGURATION > GENERAL Change the site url field to the current url location of the index.php file (http://www.yoursite.com/index.php). Also change the administration reply email to your email address. All communication from the site (except possibly registrations which can be set separately there) to the administrator use this email address. REGISTRATION CONFIG This is where you can set the email address where users will send questions with the registration process to. You must also set the url of the register.php file. This is usually in the same directory as your index.php file (http://www.yoursite.com/register.php). You can also set the script to alert you when users attempt registration and successfully complete the registration. You can configure all aspects of the registration process on this page. ADMIN PASSWORD Change your admin username and password and save them. AD CONFIGURATION > IMAGES MANAGEMENT If you are going to allow images to be uploaded onto your site you have 2 options - save as a file on the server or save the image in the database. We recommend saving the images as files within a directory. The file structure system of the server is a little faster at serving up images than spooling the image from a database. If you anticipate at least moderate traffic to your site you have to remember that if images are saved in a database that each display of an image saved within a classified ad is a call to the database that must spool a large bit of data to the browser requesting it thus keeping a connection open while doing it. Saving the images in a file also makes the size of your database considerably less. Database backups become much easier to handle. Make your choice for the "allow images to be uploaded". If "yes" then make your choice for "upload images to database or file directory". If "save images as file"... set the "url path to image directory if allow uploaded to a file" to the directory the images will be saved in relative to the index.php file. If the images will be in a user_images/ sub directory of the same directory the index.php file is in then just enter "user_images/". If either "allow image to be uploaded" is checked "yes" the "image upload type" must be set. This field comes defaulted to "option 1". Most servers have this configuration. Option 1 - This choice is made if your server allows the manipulation of images within the /tmp directory where the server places them once they have been uploaded from a user. Try this option first and move to option 2 if the server tree structure has been set and you are unable to upload images. If you get an error that says you cannot open a file in the /tmp directory due to permissions you may have to use option 2. Option 2 - This choice is made if your server does not allow manipulation of images within the /tmp directory. The images must be moved from the /tmp directory to the directory you set in the "directory path to images directory" field before they can be manipulated. If you save your images as a file or have to use option 2 in the image upload type you must set the "directory path to images directory" to the proper server path from root to the directory where you are storing or manipulating images. This is the root server path not just the site path. You can often see the root path in the directory path of your ftp program when you are uploading or in the error messages displayed when there is a php error on your site. You may have to contact your host to find the root server path as many do not expose the root path while ftp-ed into your site. Once you have set up this folder make sure the directory has the proper permissions to copy images or manipulate images within this directory. You can usually set the permissions to this directory through your ftp program or the CHMOD command while telnet-ed into your site. 8) Email--------------------------------- The program uses the mail() command built into PHP and therefore requires no configuration within GeoClassifieds. Almost every PHP installation has this configured for you so you will not need to worry. Just make sure you have the sendmail_path configured correctly within your php.ini file and it should work properly. We have experienced some email restrictions at Yahoo hosting. Yahoo does not allow you to set the "from:" field at the mail() command level and "bounces" any attempt to do so. They force the use of the "lead" email address of the hosting account as the return email address for all outgoing emails. If you use Yahoo/GeoCities hosting let us know and we can supply you with some specially configured files that do not set the "from:" field. Finished!!!!!!!!!!!!! Have fun ;) Geodesic Staff geoclassifieds@geodesicsolutions.com Please feel free to contact us with any questions or comments you may have.