Installing X-Cart

Note: Wizard installation is recommended; manual installation can be performed by advanced users.

Important: Before installing X-Cart, please make sure the minimum system requirements are met. Regardless of the employed installation method, after the installation is completed, follow our Post-install notes (security related).

If you do not wish to install X-Cart by yourself, please feel free to order installation services from X-Cart team. Our technical specialists will be glad to help you.

1.	Obtain an X-Cart distribution package by downloading it from X-Cart File area. The distribution package you need is contained in the archive file x-cart-x.y.tgz, where x and y are X-Cart version numbers.

The result of above described manipulations should be a directory containing all the files of your X-Cart. Further in this manual we will refer to this directory as '/xcart directory', 'X-Cart installation directory', or 'X-Cart root'. If you do not feel like using the name '/xcart' for this directory, please feel free to pick a different name for it; however, in this case, you should remember to use your own X-Cart directory name in the place of '/xcart' wherever it is needed.

Note: Please make sure you keep the directory structure during unpacking and uploading, otherwise some necessary files can be overwritten!

Note: For more information on chmod utility, enter the command man chmod into the command line.

For example, if your domain name is www.example.com and you placed your X-Cart application in the directory /xcart off your web root, you would enter http://www.example.com/xcart/install.php into your web browser address line.

5.	Once the Installation Wizard is launched, follow the Wizard instructions. Make sure you complete all of the Installation Wizard steps. At the final step you will get an Auth code and instructions on how to access your store.

The first time you run the Installation Wizard, it provides X-Cart Software License Agreement for you to accept. Please read X-Cart Software License Agreement. If you agree to all of the terms of this agreement, select the 'I accept the License Agreement' check box and click Next. (By selecting 'I accept the License Agreement', you are consenting to be bound by this agreement). If you do not agree to the terms of the agreement, do not install the software.

Please note that, if it is not the first time you've launched the installation script on this system to install X-Cart or X-Cart skin files in the current directory (the installation script will know this by the presence of a /skin1 directory within X-Cart root; the directory /skin1 is created at Step 6 of X-Cart installation), you will need to specify what you are trying to do (to create a new installation or to re-install skin files) and to provide your Auth code:

Note: An Auth code is generated at the final step of your first X-Cart installation. See Step 10: Installation complete for details.

At this step, the setup program checks the files from which X-Cart will be installed for integrity and ensures that the configuration of the server on which the installation will be performed meets the minimum requirements.

On the left side of the page, you see the results of this test. It is a list of criteria used in the testing - with statuses, [OK] ("test passed successfully") or [FAILED] ("test failed"):

Ideally, all the lines in the test results should be marked [OK]. If this is the case, the page looks as follows:

The green label 'Passed' signifies that the test has been passed successfully, and you can continue with the installation (To continue, click the Next button at the bottom of the page).

If, however, the test results section displays one or more [FAILED] marks, on the right-hand side of the screen, instead of the 'Passed' label, you will see messages similar to these:

At this point, it needs to be said that, for successful installation, only two conditions are essential: 1) The files of the original X-Cart distribution must be unaltered (The line 'Verifying the integrity of essential files' must be marked [OK]); 2) All critical dependencies must be satisfied (All the lines in the 'Checking critical dependencies' subsection must be marked [OK]). If both these conditions are met, you can continue with the installation - even if there is one or more [FAILED] marks in the 'Checking non-critical dependencies' subsection. If, however, any of the two essential conditions is not satisfied, you will not be able to continue with the installation until the issue is resolved.

You can use the links [+] Click here to see details to get more information about the issues that have been detected and to find out how they can be resolved:

If you cannot resolve the issues detected by the test by yourself, you can send a report to X-Cart technical support service. To send a report, click the Send report button:

The text of your report with a detailed description of your problem will be generated automatically (You will be able to see it in the 'Technical problems report' section). If necessary, you will be able to add any additional information in the 'Additional comments' section. To submit the report, click the Send report button at the bottom of the page. The report will be posted to X-Cart's HelpDesk as a regular support ticket. To get a solution for the problem described in this ticket, you will need to log in to your HelpDesk account. Please note that submitting a report will reduce your support points balance.

At this step, the Installation Wizard requires you to specify the host name of the server where you store will be located, the host name of your secure server and MySQL database information.

Important: Please remember that a server name does not include http:// ! Enter just the domain name, like www.example.com. Also be aware that your secure HTTPS server host name may or may not be the same as the HTTP server host name. If, for the moment, you do not have an HTTPS server, or if you do not know its name, temporarily use your HTTP server name for the 'Secure server host name' field. You will be able to change it later by editing the variable $xcart_https_host in the configuration file config.php.

Note: As a rule, the setup program detects this directory automatically; however, if the detection has not been a success, you may want to enter the appropriate web directory name manually. Put a slash before the name of the directory and no slash at the end (for example, /xcart). If you are installing X-Cart in the site root, leave the field empty.

Note: The database server name is typically localhost, but this is not universal! If you do not have or do not know the name of your database server, your database name, etc. please check with your hosting provider.

Please also provide an email address that will be used as the default address for your company options. The address you provide here will be automatically inserted by X-Cart into all the email address fields in the General settings->Company options section of your store and all the email address fields in the profiles of the default users that will be created at the time of X-Cart installation. An email notification about a successful installation of X-Cart will also be sent to this address.

Click on Next. A page will appear displaying the data you provided regarding your web server and MySQL database and a few more fields:

Make sure the web server and MySQL database details provided by you at the previous stage are correct.

Then provide some additional information as to what your X-Cart installation should be like:

▪

Languages: At the moment, X-Cart is shipped with an only language pack - English, which is selected as the language pack to be installed by default. If, at some point in the future, X-Cart comes to provide other official language packs, you will be able to select any language packs you would like to install from this selectbox.

▪

States table: If your company is located in a country that has states, or if your X-Cart-based store is going to sell and ship products to countries that have states, you may want to import state names for each of these countries. It will be possible to use imported state names for setting up destination zones, your company address and specific user addresses. If you wish to import state names, use the 'States table' selectbox to specify the countries for which you wish to import states. To select a country, simply click on its name with your mouse (The country name will be highlighted). To select more than one country, hold down the CTRL key while clicking the appropriate country names. If you do not wish to import states, select No states. In any case, you will be able to add state names manually after X-Cart is installed.

▪

Sample categories/products: For the purposes of testing of a newly installed X-Cart store, the Installation Wizard allows you to import sample products and categories (the sample categories/products set will be pretty much the same thing you see in X-Cart demo installed at our company site). As soon as you've finished testing, the imported sample categories/products can be removed with just a couple of clicks through the Summary->Tools section. If you wish to import sample categories/products, select Yes (If not, select No).

▪

Configuration settings: For some countries, pre-configured store settings are available (This includes some pre-configured taxes, destination zones, default company and customer addresses and phone numbers, and language variables which may differ from one country to another - like zip code/postal code). If you think using such pre-configured settings can help you make the process of configuring your store faster, see if your country is listed in the 'Configuration settings' drop-down box and, if it is, select this country to import the settings.

▪

Update config.php only: If you are installing X-Cart for the first time, or if you want to completely re-install your X-Cart, leave this check box empty. If you wish only to update the information in config.php, keeping your current database, select this check box.
If you are installing X-Cart over the database, left from another installation, make sure you specify the blowfish key which was emailed to you during the previous installation. If you fail to do that, the key which is included into the new X-Cart will not be able to decrypt the encrypted data from the old database.

At this step, the installation script will use the information you provided at Step 3 to update X-Cart's main configuration file config.php and to set up the store database:

Note: The time required for completing this installation step depends on the performance of your server; however, the process is unlikely to take longer than 5 minutes.

Select a layout, a color scheme and a dingbat set that you wish to use for the front-end of your store.

At present, five X-Cart shop layouts are available: 3-columns (default), 3-columns reverse, 2-columns, 2-columns reverse and small shop (In the main, small shop reproduces the 2-column reverse layout, but includes fewer menus).

After the desired settings are selected, click on Next. The installation will continue.

The setup program will create the necessary X-Cart folders and copy the necessary templates.

After the process is completed, the Installation Wizard will display a preview of the chosen color/layout style:

If you are satisfied with the way a shop site looks in the preview and want to accept the selected color/layout style for your own store, click on Next.

Specify whether you wish to enable PayPal payment processing in your store by selecting Yes or No from the drop-down box.

Tip: Do not worry about making a final decision as to enabling PayPal payment processing at this step: you will be able to enable/disable PayPal at any time later via the administration back-end of your store.

Specify an email address you wish to use for PayPal registration, or (if you already have an account with PayPal) an email address your current PayPal account is registered for.

Click on Next. A verification message will be sent to the email address provided at this step. To enable PayPal payments in your store, confirm your desire to use PayPal by clicking a web link in this message.

At this step, a fingerprint of the newly installed X-Cart system will be generated. Please be patient, the process may take a few minutes.

Note: In X-Cart, a system fingerprint is a list of MD5 checksums of all X-Cart files. The system fingerprint generated during X-Cart installation reflects your store's original (unmodified) state and can be used later to control the integrity of your store's files. For details on using X-Cart's fingerprints, please refer to the chapter System Fingerprints further in this manual.

After the fingerprint generation is completed, the Installation Wizard will display a message 'System fingerprint is successfully generated'. Click on Next.

This is the final step of X-Cart installation. It notifies you that an X-Cart-based store has been successfully installed, displays an Auth code for your X-Cart installation and provides important security-related post-install notes. It also provides links to the URLs at which the newly installed store can be accessed.

On this last step the name of the installation script 'install.php' is changed. This might be impossible if renaming is prohibited. A corresponding error message will be displayed if this is the case.

When the script has been renamed, it cannot be run. To be able to used the installation script again you need to change its name back to 'install.php' on the server, using ftp, ssh or other direct access to the file system (Control Panel and etc.).

If, at Step 3 of the installation process (Preparing to install X-Cart database), you provided an email address in order to receive an email notification about the successful completion of the installation, this notification will be sent. It will provide store access information, post-install notes, your installation Auth code and Blowfish encryption key.

If the installation script has been renamed, the new name will be included into the notification. If the installation script could not be renamed, a note about this is included into the notification as well as a reminder to rename or delete it.

Note: Auth code and Blowfish encryption key are two special key codes generated in the process of X-Cart installation.

Auth code is used to prevent unauthorized access to X-Cart's installation script install.php. If, in the future, you decide to completely re-install X-Cart, change your store's skin set or install some X-Cart add-ons, you will be required to enter this code at the time of installation. Please be aware that, after X-Cart is installed, this code is stored for you in include/install.php. You can also look it up in the 'Summary' section of your store's Admin zone.

Blowfish key is used to encrypt all sensitive data in your store including user passwords, order details, etc. This code is supposed to be stored permanently in config.php (the variable $blowfish_key). Please do not change this key manually.

This section assumes that you are installing your X-Cart on a UNIX server with terminal access. Basic knowledge of UNIX operating system is required.

1.	Obtain an X-Cart distribution package by downloading it from X-Cart File area. The distribution package you need is contained in the archive file x-cart-x.y.z.tgz, where x, y and z are X-Cart version numbers.

The result of decompressing the archive should be a directory containing all the files of your X-Cart. Further in this manual we will refer to this directory as '/xcart directory', 'X-Cart installation directory', or 'X-Cart root'. If you do not feel like using the name '/xcart' for this directory, please feel free to pick a different name for it; however, in this case, you should remember to use your own X-Cart directory name in the place of '/xcart' wherever it is needed.

When X-Cart is being installed using X-Cart Installation Wizard, the Wizard automatically creates all the directories that need to be created within the directory /xcart and sets proper permissions on these directories so X-Cart can use them to create files required for the store operation. In manual installation, you need to create these directories and set their permissions manually. Create directories /files, /catalog and /var under the directory /xcart and set their permissions to 777; copy the directory /skin1_original to a directory /skin1 and set the permissions 777 for every subdirectory and file under the directory /skin1; if you are going to use PGP encryption method, copy the contents of the directory .pgp.def to a directory .pgp; set the permissions 755 on the script admin/newsletter.sh (this script is used for sending newsletter emails in News Management module) and on all the payment scripts of the payment/*.pl type:

5.	Setup a database to be used with X-Cart: clear all the data which might be contained in the database, create the necessary X-Cart database tables and populate them with data. To do so, use the following shell commands:

If, before you start using X-Cart as a basis for a live store, you want to learn how it works, you might want to import some demo data (sample products and categories) into the store database. As soon as you decide you no longer need these products and categories, you will be able to remove them with just a couple of clicks through the Summary->Tools section of X-Cart administration back-end. To import demo data, issue the following command:

If your company is located in a country that has states, or if your X-Cart-based store is going to sell and ship products to countries that have states, you may want to import state names for each of these countries. It will be possible to use the imported state names for setting up destination zones, your company address and specific user addresses. To import states for a country, issue the following command:

By default, your store will be installed with some pre-configured settings typical for the United States. Pre-configured settings affect such areas of X-Cart functionality as taxes, destination zones, default company and customer addresses and phone numbers, and some language variables (for example, a US installation will have a 'zip code' field in all the default addresses instead of the 'postal code' more typical for the UK). If your store is based in a country other than the United States, you may want to import a different set of configuration settings. At present, pre-configured store settings for Canada, Australia and the United Kingdom are available. If you want to import pre-configured settings for any of these countries, issue the following command:

> mysql -u <username> -p<password> <database_name> < sql/xcart_conf_<Country>.sql

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 in to X-Cart.

Before you proceed to using X-Cart, please restore secure permissions on the file config.php and your X-Cart installation directory. Issue the following commands:

Important: We strongly recommend you remove X-Cart distribution package archive from your web directory to prevent unauthorized access to X-Cart source code.

The script install.php you used for installing X-Cart can be used again to change the skin set of your store or to completely re-install X-Cart. If you think you are not going to need this script in the nearest future, we recommend you remove it from the web-accessible directory keeping a copy of the file in a safe place (If, at some time later, you need to run X-Cart installation again, you will need to re-upload the script install.php to X-Cart installation directory). However, if, for the moment, you need to keep the script install.php in its initial location in the web directory, change your Auth code. To do so, edit the value of the $installation_auth_code variable in include/install.php and ensure that only people authorized to perform X-Cart re-installation can access this file.

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.