X-Cart Installation Manual ========================== $Id: INSTALL,v 1.65.2.6 2009/02/05 10:39:21 avg Exp $ Dear Customer, Thank you for choosing X-Cart. We hope this manual will help you install this software on your site in several minutes! If you experience some problems during installation, don't hesitate to contact us at http://www.x-cart.com/, we would be pleased to help you. I. SYSTEM REQUIREMENTS II. INSTALLING X-CART USING INSTALLATION WIZARD III. INSTALLING X-CART MANUALLY IV. I'VE INSTALLED X-CART. WHAT'S NEXT ? V. REPORTING BUGS AND PROBLEMS VI. WHAT IS SMARTY ? VII. UPGRADE NOTES * * * * * I. SYSTEM REQUIREMENTS ====================== Minimal system requirements --------------------------- 1. Web server with support for PHP version 4.0.6 or better (PHP5 is also supported). Make sure the configuration file php.ini meets the following requirements: a. safe_mode must be disabled b. file_uploads must be enabled c. register_long_arrays must be enabled (only for hosts using PHP5; not required for PHP4) (all these values are default) 2. The web server must have support for MySQL databases. X-Cart is compatible with MySQL versions from 3.23. You will need to have access to a MySQL database, so make sure you have the following information: your MySQL server name, your database name, your username and password for MySQL access. 3. The server perfomance, recommended for X-Cart to run on it, depends on how many visitors your store will have. Unpacked distribution of X-Cart requires about 25 megabytes of disk space, but you may need more if you are going to use additional files and own templates for X-Cart. 4. The database size used by X-Cart depends on the number of products, customers and orders stored in it. For example, for small shops it may be 1 megabyte, for medium 10, and for huge stores over 100 megabytes. Advanced requirements and recommended settings ---------------------------------------------- Certain parts of X-Cart's functionality rely on using external files. Accordingly, your web server must be allowed to run external executable files (like Perl) and to make outgoing connections to the Internet (that is required for online payments). The following components may be required: 1. An HTTPS module (like Net::SSLeay perl module, CURL executable, OpenSSL executable or libCURL PHP extension) for some of the online credit card processing modules and for shipping modules. 2. EXPAT extension for PHP for Intershipper, UPS or USPS shipping modules. Make sure the functions "exec", "popen", "pclose" and "ini_set" are not included in the disabled functions list in php.ini: 1. PHP function "exec()" must be allowed for the correct functioning of most of the CC payment processing modules used with X-Cart (CyberCash, CyberPac (LaCaixa), VeriSign PayFlow Pro, PayBox, CyberSource, PaySystems Client, VaultX), HTTPS modules (Net::SSLeay, CURL, OpenSSL, https_cli), GnuPG/PGP, X-Carts Patch/Upgrade functionality. 2. PHP functions "popen()" & "pclose()" must be allowed for the correct functioning of some HTTPS modules (CURL, Net::SSLeay), payment modules (Saferpay, CyberSource, iDeb), shipping modules (DHL/Airborne, Canada Post, UPS Online Tools, Intershipper, AntiFraud module. 3. PHP function "ini_set()" is used for the session mechanism and enhances security. For help on this visit the PHP site at http://www.php.net An SSL certificate is highly recommended to ensure security of online transactions at your store. You can obtain a certificate using our "Security products" section. Note: The above-listed requirements are usually met by all web hosting service providers. If unsure, contact your provider for details. * * * * * II. INSTALLING X-CART USING INSTALLATION WIZARD =============================================== This section explains how to install X-Cart using X-Cart Installation Wizard. It assumes you understand how to unpack TAR archives, what are file access permissions and how to change them. If you have problems with installation, please refer to X-Cart Manual, or contact us and we can do the installation for you. 1. Ensure that your server meets the minimum requirements. 2. Uncompress the module distribution and upload the files into the X-Cart directory on the server. On a Unix-based server with terminal access to it, you can do it using the following command: gunzip < x-cart-X.X.tgz | tar -xvf - or tar -xzvf x-cart-X.X.tgz 3. Go to the X-Cart installation directory and grant writable file access permissions on the following files and directories (you can skip this step if PHP engine installed on your hosting server runs in suEXEC mode - http://en.wikipedia.org/wiki/Suexec): .pgp files catalog images skin1 var var/cache config.php Also the following files should have executable permissions on Unix-based systems: admin/newsletter.sh payment/ccash.pl payment/csrc.pl payment/netssleay.pl On a Unix-based server with terminal access to it you can do it using the following commands: > cd xcart > chmod 777 .pgp > chmod 777 files > chmod 777 catalog > chmod 777 images > chmod 777 skin1 > chmod 777 var > chmod 777 var/cache > chmod 666 config.php > chmod 755 admin/newsletter.sh > chmod 755 payment/*.pl 4. Open in your browser X-Cart Installation Wizard at the following URL: http://www.yoursite.com/xcart_directory/install.php Then follow the instructions provided by the Installation Wizard. 5. Finally you should setup proper permissions to protect files from writing. You can skip this step if PHP engine installed on your hosting server runs in suEXEC mode - http://en.wikipedia.org/wiki/Suexec. On a Unix-based server with terminal access to it you can do it using the following commands: > chmod 755 var > chmod 644 config.php 6. You should also modify install.php by setting $installation_auth_code variable if you will be using it in the future. This will prevent the Installation Wizard from unauthorized access. * * * * * III. INSTALLING X-CART MANUALLY (for advanced users) ==================================================== This section assumes that your server is Unix-based, you have terminal access to it and possess basic Unix knowledge. 1. Ensure that you meet the minimum requirements. 2. Uncompress the X-Cart distribution anywhere inside your web tree. 3. Edit the X-Cart main configuration file, "config.php". X-Cart distribution includes a sample "config.php", which you can modify. You will need to edit the following entries: $sql_host ='%SQL_HOST%'; $sql_user ='%SQL_USER%'; $sql_db ='%SQL_DB%'; $sql_password ='%SQL_PASSWOD%'; $xcart_http_host ="%HTTP_HOST%"; $xcart_https_host ="%HTTPS_HOST%"; $xcart_web_dir ="%WEB_DIR%"; These entries represent MySQL server name, MySQL username, MySQL database name and MySQL password. 4. Setup proper permissions for files and directories. If the PHP engine installed on your hosting server does not run in suEXEC mode: > cd xcart > chmod 777 .pgp > chmod 777 files > chmod 777 catalog > chmod 777 images > chmod 777 var > chmod 777 var/cache > chmod 666 config.php > cp -Rp .pgp.def/* .pgp/ # If you are planning to use PGP encryption > chmod 644 .pgp/.htaccess > chmod 666 .pgp/* > cp -Rp skin1_original skin1 > find skin1 -type d -exec chmod 777 {} \; > find skin1 -type f -exec chmod 666 {} \; > chmod 644 skin1/.htaccess > chmod 755 admin/newsletter.sh > chmod 755 payment/*.pl If the PHP engine runs in suEXEC mode: > cd xcart > chmod 700 .pgp > chmod 700 files > chmod 711 catalog > chmod 711 images > chmod 711 var > chmod 711 var/cache > chmod 644 config.php > cp -Rp .pgp.def/* .pgp/ # If you are planning to use PGP encryption > chmod 644 .pgp/.htaccess > chmod 600 .pgp/* > cp -Rp skin1_original skin1 > find skin1 -type d -exec chmod 711 {} \; > find skin1 -type f -exec chmod 644 {} \; > chmod 755 admin/newsletter.sh > chmod 755 payment/*.pl 5. Setup the X-Cart database. In case the database contains tables with names, which are used by X-Cart, they will be dropped. > cd xcart > mysql -u -p < sql/dbclear.sql > mysql -u -p < sql/xcart_tables.sql > mysql -u -p < sql/xcart_data.sql > mysql -u -p < sql/xcart_language_.sql where is a language code (e.g. US, DE etc) > mysql -u -p < sql/states_.sql where can take these values: AU - for Australian states CA - Canada ES - Spain UK - United Kingdom (Great Britain) US - United States if you need demo store uploaded into database issue this command via shell or command line: > mysql -u -p < sql/xcart_demo.sql 6. Please note that, if manual installation is used to re-install X-Cart on top of a previously installed one, and the database is installed anew, you need to replace the value of the variable $blowfish_key in the file config.php of your installation by the default Blowfish key. The default Blowfish key can be copied from the variable $init_blowfish_key in your install.php. This is essential, because the Blowfish key used in your new database equals the default Blowfish key, not the Blowfish key generated in the process of the previous X-Cart installation that is stored in config.php. Failure to replace the Blowfish key in config.php by the default Blowfish key from install.php will result in the inability of any users to log into X-Cart. 7. Note that, if your X-Cart store was installed manually, the Blowfish key that was used to encrypt the data in your database corresponds to the default value of $init_blowfish_key in install.php. Using this value as a Blowfish key is not secure, so, after installing X-Cart using the manual method, you need to re-generate your Blowfish key by clicking the button Regenerate in the Admin area -> Summary page -> Tools page -> Re-generating the Blowfish encryption key section. * * * * * IV. I'VE INSTALLED X-CART. WHAT'S NEXT ? ======================================== Your web store's customer interface is located at: http://www.yoursite.com/xcart-directory/ There are default user accounts in your copy of X-Cart system. You may easily change/delete them. a. Administrator account (valid in X-Cart Pro version only): Usertype: Administrator Username: admin Password: admin Interface URL: http://www.yoursite.com/xcart-directory/admin/ b. Provider account (valid in X-Cart Pro version only): Usertype: Provider Username: provider Password: provider Interface URL: http://www.yoursite.com/xcart-directory/provider/ c. Administrator account (valid in X-Cart Gold version only): Usertype: Administrator/Provider Username: master Password: master Interface URL: http://www.yoursite.com/xcart-directory/admin/ d. 'Root' provider account (valid in X-Cart Pro version only): Usertype: Provider Username: root Password: root Interface URL: http://www.yoursite.com/xcart-directory/provider/ For more information about operating X-Cart and how to create and manage your own on-line store, please refer to X-Cart Manual. * * * * * V. REPORTING BUGS AND PROBLEMS ============================== Please report bugs and suggestions to the developer using the contact forms at http://www.x-cart.com/ * * * * * VI. WHAT IS SMARTY ? ===================== Smarty is a PHP-based template engine. X-Cart uses it to provide X-Cart store owners with unlimited capabilities of customizing X-Cart's design and layout. You can get more information on Smarty at the following URL: http://smarty.php.net/manual/en/ * * * * * VII. UPGRADE NOTES =================== For detailed information about upgrading X-Cart please refer to the UPGRADE.readme file. * * * * * X-Cart Copyright (c) 2001-2009 Ruslan R. Fazliev All rights reserved. * * * * * Thank you for reading this far. We wish you success in your e-business. Yours, X-Cart Team.