View source for X-Cart:Installing X-Cart Using the Installation Wizard

== Video tutorial ==

{{XC 4.4}}
<youtube>fAxZDV8QJeA</youtube>

== Step-by-step guide ==

=== Download and unpack ===

Obtain a distribution package for the X-Cart version you need by downloading it from the File Area section of your {{QA}}. Look for a file named like <u>x-cart-x.y.z''edition''.tgz</u> (or <u>x-cart-x.y.z''edition''.zip</u>), where <u>x</u>, <u>y</u> and <u>z</u> are X-Cart version numbers and the ''edition'' portion of the filename is '''gold''' for the GOLD edition, '''goldplus''' for the GOLD PLUS edition or '''platinum''' for PLATINUM. For example, if you need X-Cart v4.7.10. GOLD edition, choose the file x-cart-4.7.10gold.tgz or x-cart-4.7.10gold.zip.

=== Copy the distribution package to a web-accessible directory ===

Copy the distribution package to a web-accessible directory of your server or your hosting account.

* If you are using a Windows-based server, or a UNIX-based server without terminal access:
:# Decompress the archive to a directory on your local computer using your favourite compression program like WinZIP or any other similar tool with support for TAR files.
:# Use an FTP client (for instance, [https://wiki.filezilla-project.org/Using FileZilla]) to upload the files and folders from the archive to the web-accessible directory on your server or your hosting account. Make sure the file and directory structure of the package is retained.

{{Note|Before uploading X-Cart files to the server, please make sure you set binary FTP transfer mode in your FTP client. Some of the uploaded files may be damaged if transferred in the ASCII mode.}}

* If you are using a UNIX-based server with terminal access:
:# Use an FTP client (for instance, [https://wiki.filezilla-project.org/Using FileZilla]) to upload the archive to the web-accessible directory on your server or your hosting account.
:# Decompress the archive using one of the following commands:

::<pre>gunzip < x-cart-x.y.zedition.tgz | tar -xvf -</pre>

::or

::<pre>tar -xzvf x-cart-x.y.zedition.tgz</pre>

:: (Be sure to replace ''x-cart-x.y.zedition.tgz'' with the actual name of your X-Cart distribution package)<br />
: As a result of extracting the files from the archive, you should now have a directory (<u>/xcart</u>) containing the files and folders of your X-Cart. The directory <u>/xcart</u> is created automatically; if necessary, you can rename the directory or move its content to a different location, e.g., your web root. Further in this manual we will refer to the directory with the X-Cart files and folders as the X-Cart root directory, X-Cart installation directory or /xcart directory.

=== Run install.php ===

Use your favorite web browser to run the installation script <u>install.php</u>: in the address bar of your browser, type the URL of the X-Cart installation directory followed by the script's filename. For example, if your domain name is www.example.com, and the X-Cart files are in the directory /xcart in your web root, the URL should be http://www.example.com/xcart/install.php .

This will start the Installation Wizard that will guide you through the installation process and help you install X-Cart. The Wizard includes several steps, and at every step the Wizard solves some specific tasks like checking server environment, gathering necessary details, etc. The picture below shows you a sample step of the Wizard. Beneath the header, the page is divided into two section. The section on the left shows you the progress of the installation process: the name of current step appears in dark blue, the steps that have been completed successfully are marked in green, the forthcoming steps are shown in grey. The section on the right contains different details about the current step of the installation process.

It is important to complete all the steps of the Wizard. At the final step the Wizard will display a screen saying that the installation is complete.

: [[Image:installation_01.gif|640px]]

5. Follow the instruction on the screen to complete all the steps of the Installation Wizard.
The steps of the Wizard are described below in the order how they appear. To move between the steps, use the buttons Back and Next.

====License agreement====

At the first step of the Installation Wizard, you are supposed to accept the X-Cart Software License Agreement. Read the Agreement thoughtfully, and select the check box below the text of the Agreement.

{{Note1|Important: By selecting the check box you confirm that you agree with all the terms and conditions expressed in the X-Cart Software License Agreement. If you do not agree with any part of the Agreement,  do not install the software and quit the Installation Wizard by closing the respective page of the web browser.}}

: [[Image:installation_02.gif|640px]]

If it is not the first time that you have run the installation script <u>install.php</u>, the Wizard will ask you to enter an authorization code for the existing copy of X-Cart. The authorization code (Auth code) is used in X-Cart to prevent unauthorized access to the installation scripts, and you need to enter the Auth code every time you re-install X-Cart, or change the skin, or install an add-on module.

: [[Image:installation_03.gif|375px]]

{{Note1|Note: If you do not remember your Auth code, you can find it on the [[X-Cart:Summary_Page |Summary]] page in X-Cart Admin area or retrieve the value of the $installation_auth_code variable from the file <u>[xcart_dir]/config.php</u> (X-Cart versions 4.4.2 and later) or <u>[xcart_dir]include/install.php</u> (X-Cart versions before 4.4.2).}}

Click the '''Next''' button.

====Checking PHP configuration====

At this step, the installation script checks that the web server meets the minimum system requirements, verifies that the files and folders from the distribution package have not been modified, and checks that the necessary files and folders have correct permissions. The test result is displayed in a special table that contains the list of tested requirements and the status of every tested parameter. A sample test result is shown in the picture below.

: [[Image:installation_04.gif|540px]]

The statuses mean as follows:

* [OK] - Requirement is satisfied completely);
* [FAILED] - Requirement is not satisfied. Installation cannot be continued as this dependency is critical;
* [WARNING] - Requirement is not satisfied. Installation can be continued as this dependency is not critical.

Ideally, all the parameters in the test result should have the [OK] status. It is also recommended that you solve the issues with the [WARNING] status. The issues marked with the [FAILED] status must be fixed without fail. Otherwise you will not be able to continue with the installation and use X-Cart.

To help you find out how to fix a particular issue, for each failed requirement the Wizard provides a short description and a possible solution. This information is presented in special warning messages on the right to the test results. The detected issues are grouped according to the failure type: environment checking errors, failed critical dependencies and failed non-critical dependencies.

: [[Image:installation_16.gif|640px]]

To see the available information about a particular error or failure, click on the [[Image:installation_17.gif|78px]] link. This will expand the warning message and open a description of a possible solution.

If you are not sure you have enough resources to fix the detected issue(s) on your own, you can send a report to the X-Cart Support Team so that they could provide you with a solution. The report would contain a detailed description of the detected issue(s) together with some important information about your web server configuration.

To send the report click the Send report button below the the warning and error messages.

: [[Image:installation_14.gif|540px]]

This will open a new screen with an automatically generated technical report and a text field where you can put your comments.

: [[Image:installation_15.gif|605px]]

If necessary, put your comments to the <u>Additional comment</u> field and click the Send report button to send the report with your comments (if any) to the X-Cart Support Team. You message will posted to the Message board of your {{QA}} as a regular support ticket, and will be processed by our Support Team. To read the answer of the responsible support engineer you will need to log in to your {{QA}}.

Click the '''Next''' button.

====Preparing to install X-Cart database====

Here you must specify the host name of the server on which your are installing the store, the host name of your secure (HTTPS) server and the details of the MySQL database that will keep all your store's data.

: [[Image:installation_05.gif|640px]]

The fields in this form mean as follows:

* <u>Server host name:</u> The host name of the server on which you are installing your copy of X-Cart.
* <u>Secure server host name:</u> The host name of the secure server that will provide access to your X-Cart based store via the HTTPS protocol.

Important: Server host names must not include the protocols ('http://' or 'https://' prefixes). Enter only the domain name, e.g., www.example.com. Also pay attention that the name of the secure HTTPS server can either coincide with the name of the HTTP server or have a different name. If you do not have an HTTPS server now, or if you do not remember its name, instead of the secure server name temporarily enter the name of your HTTP server. You will be able to change it later by editing the variable <u>$xcart_https_host</u> in the configuration file [[X-Cart:Config.php]].

* <u>X-Cart web directory:</u> The web-accessible directory of your server or hosting account where X-Cart files are located.

Note: As a rule, the installation script detects this directory automatically; however, if the detection has not been a success, you need to enter the name of the appropriate web directory 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 to the web root, leave the field empty.

* <u>MySQL host name:</u> The DNS name or the IP-address of your MySQL server.
* <u>MySQL user name:</u> The username for your MySQL user account.
* <u>MySQL database name:</u> The name of the MySQL database that you will use for your X-Cart based store.
* <u>MySQL password:</u> The password for your MySQL user account.

Note: Typically you can obtain your MySQL access details from your hosting provider.

* <u>Your e-mail address: </u>The email address that you would like to use as a default company email address. This address will be assigned to the default Administrator and (X-Cart PLATINUM/PRO) Provider accounts that are created automatically during the installation. If necessary, you will be able to change the default email address after the installation is complete. An email notification about the successful installation of X-Cart software will also be sent to that address.

Click the '''Next''' button to continue. This will reload the page and you will see a new screen that will display the information that you have entered at the previous screen and a few more fields.

: [[Image:installation_06.gif|640px]]

The fields in this form mean as follows:

* <u>Languages</u>: The languages that you wish to use in your store. By default X-Cart is delivered with the English language pack only, and English is selected as an only language to be installed. Later on you will be able modify the default set of languages in the <u>Languages</u> section of the Admin area. The instructions on how to manage languages are available at [X-Cart:Managing Languages] page.
* <u>States table</u>: If your company is based in a country that has states, or if you are planning to sell internationally and your customers are going to be from countries that have states, you may want to import the names of the states for each of these countries. Later on you will be able use the imported state names for setting up destination zones, your company address and user addresses.

In the selectbox you can choose as many countries as you wish. To select a country, simply click on its name and highlight the item. 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.

If a particular country is missing from the list, you will be able to manually add the country and its states later. The instructions on how to carry out this task are available in the [[X-Cart:States]] section of this manual.

* <u>Sample categories/products</u>: The installation script enables you to import a sample product catalog so that you could test the newly installed store. The sample catalog here is very similar to the one you could try with the online demo available at the product website (https://www.x-cart.com/shopping_cart_demo.html) . Later on you will be able to remove the sample catalog using the <u>Remove data</u> tool (See the section [[X-Cart:Advanced_Tools |Advanced Tools]] for more info). To import the sample catalog, select Yes; otherwise, select No.
* <u>Configuration settings</u>: For some countries X-Cart allows you to use pre-configured store settings. These settings include generic tax rules and rates, destination zones, default company and customer addresses and phone numbers, language variables which may differ from one country to another (e.g. postal code instead of zip code), etc.

If you find it helpful to use these pre-configured settings to make the process of configuring your store faster, choose the name of your country from the drop-down box. The installation script will import settings for the selected country then.

<div id="Update_config_php_only"></div>
* <u>Update config.php only</u>: This option allows you to decide if you wish to preserve the data in the MySQL database that you have specified at the previous screen. If you leave the check box unselected, the installation script will drop all the existing X-Cart tables in the database, create new tables and populate them with new data. If you select the check box, the installation script will only update the information in the X-Cart configuration file <u>config.php</u>, but keep the existing database untouched.
* <u>Blowfish key</u>: You should complete this field only if you are installing X-Cart with a database that was used by another X-Cart installation and you want to preserve the data from the database. If you complete the <u>Blowfish key</u> field, make sure the <u>Update config.php only</u> check box is selected.
* <u>Store images in (</u>Database<u> / </u>File system<u>)</u>: This setting allows you to choose where you wish to keep the store images (including product thumbnails and full-size product images, category icons, etc.): on the file system where X-Cart is installed or in the X-Cart database. Storing images in the database makes it easier to backup images, because they will be kept directly in the database dump. Storing images on a file system makes the database more compact and generally increases the performance level of your store.

Click the '''Next''' button.

====Installing X-Cart database====

Now the installation script updates the main configuration file <u>config.php</u> and writes the server and MySQL details that you have specified at the previous step of the Installation Wizard. If you have also forced to perform any of these tasks, the script updates the database, populates the database with demo data, import states, moves images to the file system, etc.

: [[Image:installation_07.gif|540px]]

{{Note1|Important: Depending on the performance level of your server, this process may take several minutes; however, it should not take more than 5-6 minutes.}}

Click the '''Next''' button.

====Layout settings====

At this step of the Installation Wizard, you can choose a skin for the Customer area (storefront) of your store. To choose a skin you need to select the skin name from the drop-down box.

: [[Image:installation_08.gif|640px]]

Click the '''Next''' button.

The installation script will check the existing skin files (if any). If any of the existing skin templates were ever modified, the system will display a message saying that such templates have been found. To see the list of templates, click on the [[Image:installation_19.gif|170px]] link.

: [[Image:installation_18.gif|640px]]

You can choose the keep the modified templates and preserve the modifications, overwrite the modified templates and loose the modifications, or cancel the installation. The latter option is good when you want to backup the modified files before you resume the installation. Use the button Back and Next to either return to the previous screen where you can choose a different skin or move to the next step and continue the installation.

====Setting up templates====

Now the installation script creates the necessary X-Cart folders and copies the files for the chosen skin. After the process is completed, the installation script will display a preview of the Customer area with the chosen skin. If you want to choose a different skin, click the '''Back''' button and move to the previous step of the Installation Wizard. If you are satisfied with the preview and wish to accept the skin, click the '''Next''' button to move to the next step and continue the installation.

: [[Image:installation_09.gif|640px]]

====PayPal payment processing====

At this step the Installation Wizard you can enable the PayPal payment method in your store. To enable PayPal right now, select Yes from the <u>Do you wish to enable PayPal payment processing now?</u> drop-down box. Or select No to skip this step.

: [[Image:installation_10.gif|400px]]

{{Note1|Note: Do not worry about making the final decision right now: you will be able to enable/disable PayPal in the Admin area of your store later.}}

Click the '''Next''' button.

====Enabling PayPal payment processing====

You get to this step only if you chose to enable the PayPal payment method. Here you are supposed to specify the email address that your current PayPal account is registered to or the email address that you wish to use for registering with PayPal (if you do not have an account yet).

: [[Image:installation_11.gif|640px]]

Click the '''Next''' button to move to the next step and continue the installation.

When the installation is complete, the installation script will send a verification message to the email address provided at this step. To enable PayPal payments in your store, follow the link in the massage. If you did not have a PayPal account before you started to install X-Cart, you need not create one right now. When somebody pays for the products in your store using the PayPal payment method for the first time, you will receive an email message from PayPal saying that there is a payment waiting for you at that email address and you need to open an account in order to receive the payment. If you miss opening an account within a limited period of time, PayPal will consider the payment to be unclaimed and send the money back to the person who made the payment.

====Generating a system fingerprint====

Now the installation script generates the system fingerprint.

In X-Cart, a system fingerprint is a list of MD5 checksums of all X-Cart files. The system fingerprint generated during the software installation captures the default/unmodified state of the store and can be used later to control the integrity of the store files. For details, see the [[X-Cart:System Fingerprints]] section further in  this manual.

When the the fingerprint is generated, you will see a message saying that the system fingerprint has been generated successfully.

: [[Image:installation_12.gif|420px]]

{{Note1|Note: System fingerprint generation may take several minutes, please be patient.}}

Click the '''Next''' button.

====Installation complete====

This is the final step of the Installation Wizard. Here the installation script reports that X-Cart has been installed successfully and provides direct links to the Customer, Admin and (X-Cart PLATINUM/PRO) Provider areas of your store. For the Admin and Provider areas the page displays the default login credentials (a username and a password) generated during the installation. Do not forget to change the default passwords after your have logged in to either the Admin area or the Provider area for the first time.

In addition, the message also contains the authorization code (Auth code) for the installed copy of X-Cart. The code is used to prevent unauthorized access to the X-Cart installation scripts, and you will be asked to provide the Auth code if you decide to reinstall X-Cart, change the skin, or install an add-on module. There is no need to remember the Auth code as you will be able to look it up in the <u>Summary</u> section of the Admin area or retrieve it from the variable ''$installation_auth_code'' in the file <u>include/install.php</u> in the X-Cart root directory.

After the installation process has been completed, the installation script <u>install.php</u> is automatically renamed as an additional measure to protect your X-Cart installation. Please take a note of the filename to which this script has been renamed. If you decide to re-install your X-Cart copy, you will need to rename the installation script back to <u>install.php</u> before launching the installation process in your web browser. See the section [[X-Cart:Security_related_tips|X-Cart:Security related tips]] for more information.

: [[Image:installation_13.gif|640px]]

All the information that you see at the final step of the installation process is also sent to the email address that you specified as the company email address (See [[#Preparing to install X-Cart database|Preparing to install X-Cart database]]).

==See also==

* [[X-Cart:First steps after installation]]
* [[X-Cart:Adding CMS/blog to your store]]

[[Category:X-Cart user manual]]
[[Category:X-Cart video tutorials]]