Difference between revisions of "X-Cart:Installing X-Cart Manually"

From X-Cart 4 Classic
Jump to: navigation, search
 
(12 intermediate revisions by 6 users not shown)
Line 1: Line 1:
It is assumed that you are installing X-Cart on a UNIX-based server with terminal access and you have adequate skills in using the basic UNIX commands.
+
==Procedure==
  
To install X-Cart manually:
 
  
'''1.''' Download a distribution package from the File Area section of your HelpDesk account at [https://secure.qtmsoft.com/ https://secure.qtmsoft.com/] .
+
It is assumed that you are installing X-Cart on a UNIX-based server with terminal access and have adequate skills in using the basic UNIX commands.
The package you need is contained in the archive file <u>x-cart-x.y.z.tgz,</u> where <u>x</u>, <u>y</u> and <u>x</u> stand for the X-Cart version.
 
  
You can also download an evaluation copy from [http://www.x-cart.com/download.html http://www.x-cart.com/download.html]
+
'''To install X-Cart manually:'''
  
'''2.''' Use an FTP client to upload the archive with the distribution package to a web-accessible directory on your server or your hosting account.
+
1. Download the distribution package from the File Area section of your {{QA}}.
 +
The package is archived in the file <u>x-cart-x.y.z.tgz</u>, where <u>x</u>, <u>y</u> and <u>x</u> indicate the version of X-Cart.
  
{{Note1|Please make sure that before uploading X-Cart files to the server you set <b>'Binary'</b> FTP transfer mode in your FTP client. Some of the uploaded files may be damaged if transferred in the <b>'ASCII'/'Text'</b> mode.}}
+
2. Use an FTP client to upload the distribution package to a web-accessible directory on your server or hosting account.
  
'''3.''' Decompress the package using one of the following commands.
+
{{Note1|Make sure you have set the <b>'Binary'</b> transfer mode in your FTP client before uploading the X-Cart files to the server . Some of the uploaded files may be damaged if transferred in the <b>'ASCII'/'Text'</b> mode.}}
  
<pre>gunzip < x-cart-X.Y.Z.tgz | tar -xvf -
+
3. Decompress the package by typing one of the following commands:
 +
 
 +
<pre>
 +
gunzip < x-cart-X.Y.Z.tgz | tar -xvf -
 
</pre>
 
</pre>
  
 
or
 
or
  
<pre>tar -xzvf x-cart-X.X.Z.tgz
+
<pre>
 +
tar -xzvf x-cart-X.X.Z.tgz
 
</pre>
 
</pre>
  
As a result of extracting files from the archive, you should get the directory <u>/xcart</u> that would contain all X-Cart files and folders. 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.
+
That should create the directory <u>/xcart</u> that would contain all the X-Cart files and folders. The <u>/xcart</u> directory is created automatically. If necessary, you can rename it or move its content to a different location; e.g., your document root. In this manual, we are going to refer to the directory with the X-Cart files and folders as ''X-Cart root directory'', ''X-Cart installation directory'' or ''/xcart directory''.
  
'''4.''' Change active directory to the X-Cart root directory.
+
4. Change the active directory to the X-Cart root directory.
  
<pre>> cd xcart
+
<pre>
 +
> cd xcart
 
</pre>
 
</pre>
  
'''5.''' Set up a MySQL database which you are going to use with X-Cart.
+
5. Set up a MySQL database, which you are going to use with your X-Cart.
  
 
The shell commands listed below use the following abbreviations:
 
The shell commands listed below use the following abbreviations:
<pre><username> : the username for your MySQL user account;
+
<pre>
<password> : the password for your MySQL user account;
+
<username> : your MySQL account username
<db_host> : the DNS name or the IP-address of your MySQL server;
+
<password> : your MySQL account password
<db_name> : the name of your MySQL database.
+
<db_host> : your MySQL server host name or IP-address
 +
<db_name> : your MySQL database name
 
</pre>
 
</pre>
  
:'''a.''' Clear all the data which the database might contain, create the required tables and populate them with data.
+
:a. Clear all the data that could exist in the database, then create the required tables and populate them with the new data. You can do that by typing the following shell commands.
: You can use the following shell commands.
 
  
 
<pre>
 
<pre>
Line 51: Line 55:
 
</pre>
 
</pre>
  
:'''b.''' If you want to test the installed store and import a sample product catalog and other demo data, which is similar to the one you could try with the online demo available at the product website [http://www.x-cart.com | www.x-cart.com] , run the following shell command.
+
:b. If you want to test-drive the newly created online store and import a sample product catalog with the demo data, similar to what you could have tried with the online demo available at the product website [https://www.x-cart.com www.x-cart.com], run the following shell command:
  
 
<pre>
 
<pre>
Line 57: Line 61:
 
</pre>
 
</pre>
  
: Later on you will be able to remove the demo data using the <u>Remove data</u> tool available in the <u>Summary/Tools</u> section of the Admin area.
+
: Later on, you will be able to remove the demo data using the <u>Remove data</u> tool (See the section [[X-Cart:Advanced_Tools |Advanced Tools]] for more info).
  
:'''c.''' 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.
+
:c. If your company is based in a country with states or, if you are planning to sell internationally, and your customers are going to be from the countries that have states, you may want to import the names of the states for each of those countries. Later on, you will be able use the imported state names for setting up destination zones, your company address and customer addresses.
  
:To import the names of the states, run the following shell command
+
:To import state names, run the following shell command:
  
 
<pre>
 
<pre>
Line 109: Line 113:
 
</div>
 
</div>
  
: 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 | States]] section.
+
: If a particular country is not on the list, you can later add that country and its states to the list manually. The instructions doing so are available in the [[X-Cart:States | States]] section.
  
:'''d.''' For some countries X-Cart enables you to define 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.
+
:d. For some countries, X-Cart allows defining pre-configured store settings, including 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.
  
By default, the store is installed with pre-configured settings for the United States. If your store is based in a country other than the United States, you may find it useful to import some pre-configured settings and thus speed up the process of configuring your store.
+
By default, the store installs with the pre-configured settings for the United States. If your store is based in a country other than the United States, you may find it useful to import some pre-configured settings and thus speed up the process of configuring your store.
  
Currently the settings are available for the following countries: Australia, Canada and the United Kingdom (Great Britain). To import the settings for any of these countries, run the following shell command
+
Currently, such settings are available for: Australia, Canada and the United Kingdom (Great Britain). To import the settings for any of these countries, run the following shell command:
  
 
<pre>
 
<pre>
Line 136: Line 140:
 
</div>
 
</div>
  
'''6.''' Create the required directories and set proper permissions.
+
6. Create the required directories and set proper permissions.
  
: '''a.''' Set up permissions 777 for directories <u>/files</u>, <u>/catalog</u> and <u>/var</u>.
+
: a. Set the 777 permissions for the directories <u>/files</u>, <u>/catalog</u> and <u>/var</u>:
  
 
<pre>
 
<pre>
Line 144: Line 148:
 
</pre>
 
</pre>
  
: '''b.''' If you are planning to use the PGP encryption method, create the directory .<u>pgp</u> and set its permissions to 755<u>.</u>
+
: b. If you are planning to use PGP encryption, create the directory .<u>pgp</u> and set its permissions to 755:
  
 
<pre>
 
<pre>
Line 152: Line 156:
 
</pre>
 
</pre>
  
: '''c.''' Set permissions to 755 for the script <u>admin/newsletter.sh</u> (The this script is used by the <u>News Management</u> module for sending newsletters).
+
: c. Set the 755 permissions for the script <u>admin/newsletter.sh</u> (the this script is used by the <u>News Management</u> module for sending newsletters):
  
 
<pre>
 
<pre>
Line 158: Line 162:
 
</pre>
 
</pre>
  
: '''d.''' Set permissions to 755 for all the payment modules (files with the *.pl extension inside the <u>payment/</u> directory).
+
: d. Set the 755 permissions for all the payment modules (files with the *.pl extension inside the <u>payment/</u> directory):
  
 
<pre>
 
<pre>
Line 164: Line 168:
 
</pre>
 
</pre>
  
'''7.''' Set up the skin.
+
{{Note1|<b>IMPORTANT!</b> If you upload the X-Cart files to your server via FTP, the ftp user becomes the owner of all the uploaded files and folders. Consequently, the PHP parser on your server is installed as an Apache module, those files and folders appear to be non-writeable for the web user. In this case, you should set writeable file permissions manually, as shown in the example below.}}
 
 
: '''a''' Copy the contents of the directory <u>/skin1_original</u> to the directory <u>/skin1.</u>
 
 
 
<pre>
 
> cp -Rp skin1_original/* skin1
 
</pre>
 
 
 
: This will set up the default interface including the default skin <u>Light & Lucid (2 columns)</u> for the Customer area.
 
 
 
: '''b.''' If you want to replace the default skin <u>Light & Lucid (2 columns) </u>with one of the alternative skins that come with the X-Cart distribution package, copy the directory with the skin to the directory <u>/skin1. </u>Use the command:
 
 
 
<pre>
 
> cp -Rpf schemes/templates/<Skin_name>/* skin1
 
</pre>
 
 
 
:replacing the <Skin_name> part with one of the following values:
 
 
 
<div>
 
{| cellspacing="0" cellpadding="5" border="0"
 
| artistictunes_business
 
| for Artistic Tunes Business
 
|-
 
| artistictunes_car_tires
 
| for Artistic Tunes Car Tires
 
|-
 
| artistictunes_fragrances_and_makeup
 
| for Artistic Tunes Fragrances and Makeup
 
|-
 
| artistictunes_water_colour
 
| for Artistic Tunes Water Colour
 
|-
 
| fashion_mosaic_blue
 
| for Fashion Mosaic Blue
 
|-
 
| fashion_mosaic_green
 
| for Fashion Mosaic Green
 
|-
 
| fashion_mosaic_grey
 
| for Fashion Mosaic Grey
 
|-
 
| fashion_mosaic_pink
 
| for Fashion Mosaic Pink
 
|-
 
| light_and_lucid
 
| Light & Lucid (3 columns)
 
|-
 
| neon_lights_flowers
 
| for Neon Lights Flowers
 
|-
 
| neon_lights_household
 
| for Neon Lights Household
 
|-
 
| neon_lights_music
 
| for Neon Lights Music
 
|-
 
| neon_lights_sport
 
| for Neon Lights Sports
 
|-
 
| vivid_dreams_aquamarine
 
| for Vivid Dreams Aquamarine
 
|-
 
| vivid_dreams_chromo
 
| for Vivid Dreams Chromo
 
|-
 
| vivid_dreams_lotus
 
| for Vivid Dreams Lotus
 
|-
 
| vivid_dreams_violet
 
| for Vivid Dreams Violet
 
|}
 
</div>
 
 
 
: '''c.''' After you have copied the skin files to the directory <u>/skin1</u>, set the permissions of every subdirectory and file inside the directory <u>/skin1 </u>to 777<u>.</u>
 
 
 
<pre>
 
> chmod -R 777 skin1
 
</pre>
 
  
: '''d.''' To see the changes, clear the directory <u>var/templates_c</u> which contains compiled templates.
+
Example of setting write permissions to files and folders:
  
 
<pre>
 
<pre>
> rm -rf var/templates_c
+
cd <xcart_dir>
 +
find ./skin -type d -exec chmod 777 {} \;
 +
find ./skin -type f -exec chmod 666 {} \;
 
</pre>
 
</pre>
  
'''8.''' Open X-Cart's main configuration file <u>config.php</u> for editing and set the true values for the following variables:
+
8. Open X-Cart's main configuration file <u>config.php</u> for editing and set the true values for the following variables:
  
 
<pre>
 
<pre>
Line 271: Line 200:
 
</pre>
 
</pre>
  
 +
9. Set up the skin.
 +
 +
'''To select a skin for your store:'''
 +
 +
: 1. Login to your Admin area using the default user name and password.
 +
 +
{{Note|The default login and password for X-Cart GOLD and GOLD PLUS editions are, respectively, ''demo-master@x-cart.com'' / ''master'', for X-Cart PLATINUM and PRO editions - ''demo-admin@x-cart.com'' / ''admin''.}}
 +
 +
: 2. Select <u>Settings</u> -> <u>General settings</u> on the menu and then click on the <u>Appearance</u> link on the Core options pane at the right.
 +
 +
: 3. On the ''Appearance'' page, select the skin to be used on the corresponding select box and then click the '''Apply changes''' button.
 +
 +
{{Note1|<b>IMPORTANT!</b> To improve the security of your store, make sure to replace the default user name and password with something more secure!}}
  
 
== Blowfish key ==
 
== Blowfish key ==
Line 278: Line 220:
 
X-Cart keeps the Blowfish in the main configuration file <u>config.php in </u>the variable $blowfish_key. Before the store is installed, the $blowfish_key variable contains a default value. When you install X-Cart using the Installation Wizard, the installation script <u>install.php</u> generates a new Blowfish key and writes it to the $blowfish_key variable in the <u>config.php </u>file. With manual installation, a new Blowfish key is never generated. And when the installation is complete, the $blowfish_key variable still contains the default value. Using the default Blowfish key is not secure, because its value is known to many people. And you need to generate a new value for the Blowfish key.
 
X-Cart keeps the Blowfish in the main configuration file <u>config.php in </u>the variable $blowfish_key. Before the store is installed, the $blowfish_key variable contains a default value. When you install X-Cart using the Installation Wizard, the installation script <u>install.php</u> generates a new Blowfish key and writes it to the $blowfish_key variable in the <u>config.php </u>file. With manual installation, a new Blowfish key is never generated. And when the installation is complete, the $blowfish_key variable still contains the default value. Using the default Blowfish key is not secure, because its value is known to many people. And you need to generate a new value for the Blowfish key.
  
To generate a new Blowfish key you should go to the <u>Summary/Tools</u> section of the Admin area and use the <u>Re-generate the Blowfish encryption key</u> tool. For details on how to carry out this task see section [[X-Cart:Advanced Tools]].
+
To generate a new Blowfish key, use the <u>Re-generate the Blowfish encryption key</u> tool. For details on how to carry out this task see section [[X-Cart:Advanced Tools]].
  
 
If the newly installed store is supposed to use a database that was previously used use by another X-Cart installation, the data in such database is already encrypted by the Blowfish key generated by that store. It means that neither your nor any of your customers will be able even to log in to their accounts, because the value of the variable $blowfish_key is different to the value of the key which was used to encrypt the store database. To resolve this issue, you need to open the main configuration file <u>config.php</u> for editing and change the value of the variable $blowfish_key to the value of the Blowfish key that was used by the previous X-Cart installation.
 
If the newly installed store is supposed to use a database that was previously used use by another X-Cart installation, the data in such database is already encrypted by the Blowfish key generated by that store. It means that neither your nor any of your customers will be able even to log in to their accounts, because the value of the variable $blowfish_key is different to the value of the key which was used to encrypt the store database. To resolve this issue, you need to open the main configuration file <u>config.php</u> for editing and change the value of the variable $blowfish_key to the value of the Blowfish key that was used by the previous X-Cart installation.
  
 +
==See also==
 +
 +
* [[X-Cart:Installation]]
 +
 +
[[Category:X-Cart user manual]]
 
[[Category:X-Cart user manual]]
 
[[Category:X-Cart user manual]]

Latest revision as of 17:49, 22 July 2020

Procedure

It is assumed that you are installing X-Cart on a UNIX-based server with terminal access and have adequate skills in using the basic UNIX commands.

To install X-Cart manually:

1. Download the distribution package from the File Area section of your X-Cart Account. The package is archived in the file x-cart-x.y.z.tgz, where x, y and x indicate the version of X-Cart.

2. Use an FTP client to upload the distribution package to a web-accessible directory on your server or hosting account.

Make sure you have set the 'Binary' transfer mode in your FTP client before uploading the X-Cart files to the server . Some of the uploaded files may be damaged if transferred in the 'ASCII'/'Text' mode.

3. Decompress the package by typing one of the following commands:

gunzip < x-cart-X.Y.Z.tgz | tar -xvf -

or

tar -xzvf x-cart-X.X.Z.tgz

That should create the directory /xcart that would contain all the X-Cart files and folders. The /xcart directory is created automatically. If necessary, you can rename it or move its content to a different location; e.g., your document root. In this manual, we are going to refer to the directory with the X-Cart files and folders as X-Cart root directory, X-Cart installation directory or /xcart directory.

4. Change the active directory to the X-Cart root directory.

> cd xcart

5. Set up a MySQL database, which you are going to use with your X-Cart.

The shell commands listed below use the following abbreviations:

<username> : your MySQL account username
<password> : your MySQL account password
<db_host>  : your MySQL server host name or IP-address
<db_name>  : your MySQL database name
a. Clear all the data that could exist in the database, then create the required tables and populate them with the new data. You can do that by typing the following shell commands.
> mysql -u<username> -p<password> -h<db_host> <db_name> < sql/dbclear.sql

> mysql -u<username> -p<password> -h<db_host> <db_name> < sql/xcart_tables.sql

> mysql -u<username> -p<password> -h<db_host> <db_name> < sql/xcart_data.sql

> mysql -u<username> -p<password> -h<db_host> <db_name> < sql/xcart_language_US.sql
b. If you want to test-drive the newly created online store and import a sample product catalog with the demo data, similar to what you could have tried with the online demo available at the product website www.x-cart.com, run the following shell command:
> mysql -u<username> -p<password> -h<db_host> <db_name> < sql/xcart_demo.sql
Later on, you will be able to remove the demo data using the Remove data tool (See the section Advanced Tools for more info).
c. If your company is based in a country with states or, if you are planning to sell internationally, and your customers are going to be from the countries that have states, you may want to import the names of the states for each of those countries. Later on, you will be able use the imported state names for setting up destination zones, your company address and customer addresses.
To import state names, run the following shell command:
> mysql -u<username> -p<password> -h<db_host> <db_name> < sql/states_<country>.sql
replacing the <country> part with one of the following values:
AT for Austria
AU for Australia
BE for Belgium
CA for Canada
DE for Germany
ES for Spain
FR for France
IT for Italy
LU for Luxemburg
NL for the Netherlands
UK for the United Kingdom
US for the United States.
If a particular country is not on the list, you can later add that country and its states to the list manually. The instructions doing so are available in the States section.
d. For some countries, X-Cart allows defining pre-configured store settings, including 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.

By default, the store installs with the pre-configured settings for the United States. If your store is based in a country other than the United States, you may find it useful to import some pre-configured settings and thus speed up the process of configuring your store.

Currently, such settings are available for: Australia, Canada and the United Kingdom (Great Britain). To import the settings for any of these countries, run the following shell command:

> mysql -u<username> -p<password> -h<db_host> <db_name> < sql/xcart_conf_<country>.sql

replacing the <country> part with one of the following values:

AU for Australia
CA for Canada
UK for United Kingdom.

6. Create the required directories and set proper permissions.

a. Set the 777 permissions for the directories /files, /catalog and /var:
> chmod 777 files catalog var
b. If you are planning to use PGP encryption, create the directory .pgp and set its permissions to 755:
> mkdir .pgp

> chmod 755 .pgp
c. Set the 755 permissions for the script admin/newsletter.sh (the this script is used by the News Management module for sending newsletters):
> chmod 755 admin/newsletter.sh
d. Set the 755 permissions for all the payment modules (files with the *.pl extension inside the payment/ directory):
> chmod 755 payment/*.pl
IMPORTANT! If you upload the X-Cart files to your server via FTP, the ftp user becomes the owner of all the uploaded files and folders. Consequently, the PHP parser on your server is installed as an Apache module, those files and folders appear to be non-writeable for the web user. In this case, you should set writeable file permissions manually, as shown in the example below.

Example of setting write permissions to files and folders:

cd <xcart_dir>
find ./skin -type d -exec chmod 777 {} \;
find ./skin -type f -exec chmod 666 {} \;

8. Open X-Cart's main configuration file config.php for editing and set the true values for the following variables:

$sql_host =’%SQL_HOST%’;

$sql_user =’%SQL_USER%’;

$sql_db =’%SQL_DB%’;

$sql_password =’%SQL_PASSWORD%’;

and

$xcart_http_host =”$HTTP_HOST”;

$xcart_https_host =”$HTTP_HOST”;

$xcart_web_dir =”/xcart”;

9. Set up the skin.

To select a skin for your store:

1. Login to your Admin area using the default user name and password.
Note: The default login and password for X-Cart GOLD and GOLD PLUS editions are, respectively, demo-master@x-cart.com / master, for X-Cart PLATINUM and PRO editions - demo-admin@x-cart.com / admin.
2. Select Settings -> General settings on the menu and then click on the Appearance link on the Core options pane at the right.
3. On the Appearance page, select the skin to be used on the corresponding select box and then click the Apply changes button.
IMPORTANT! To improve the security of your store, make sure to replace the default user name and password with something more secure!

Blowfish key

To ensure the safety of sensitive data in the database (user info, order details, etc.), X-Cart uses the Blowfish encryption algorithm. Encryption is performed using a special key code. In X-Cart, this code is referred to as Blowfish key. The same code is used to decrypt the data when you or your authorized personnel is trying to access the encrypted data (e.g. when viewing an order in the Admin area).

X-Cart keeps the Blowfish in the main configuration file config.php in the variable $blowfish_key. Before the store is installed, the $blowfish_key variable contains a default value. When you install X-Cart using the Installation Wizard, the installation script install.php generates a new Blowfish key and writes it to the $blowfish_key variable in the config.php file. With manual installation, a new Blowfish key is never generated. And when the installation is complete, the $blowfish_key variable still contains the default value. Using the default Blowfish key is not secure, because its value is known to many people. And you need to generate a new value for the Blowfish key.

To generate a new Blowfish key, use the Re-generate the Blowfish encryption key tool. For details on how to carry out this task see section X-Cart:Advanced Tools.

If the newly installed store is supposed to use a database that was previously used use by another X-Cart installation, the data in such database is already encrypted by the Blowfish key generated by that store. It means that neither your nor any of your customers will be able even to log in to their accounts, because the value of the variable $blowfish_key is different to the value of the key which was used to encrypt the store database. To resolve this issue, you need to open the main configuration file config.php for editing and change the value of the variable $blowfish_key to the value of the Blowfish key that was used by the previous X-Cart installation.

See also