X-Cart:Backup and Restore

Overview

Backup generally refers to making a copy of a store, which can then be restored fast and easily, if need be. Backups can be perfromed either manually as described in this article below or by using backup automation tools such as X-CloudBackup. Regular data backup will help you prevent serious data loss and corruption that can follow a disaster or mishandling of your store. The rule here is to create a full backup copy of the store at regular intervals and before carrying out any tasks that may interfere with the software code and behavior, including software and hardware upgrades, custom programming, adjusting the store design, etc. At that, you should not rely on your hosting provider only, who is likely to include regular data backup into their hosting plan: In case of emergency, data cannot always be restored immediately while any possible delay can seriously affect your business. Another typical example of when you may need to back up your store is moving/copying the store to another host or directory. In such a situation, if a backup is available, you will be able to deploy a fully functioning copy of the store in a new location quickly.

When you create a backup copy of a store you need to carry out a number of typical steps and procedures, which include making a database dump and creating an archive with the X-Cart code, templates and related files (images, static pages, the HTML catalog, files in the folder file/, etc.). In fact, X-Cart does not impose any restrictions on what tools you use to create a backup copy of your store - you can use any convenient facility, including SSH, FTP, phpMyAdmin, Remote Desktop, utilities that go with your hosting control panel and other available facilities. The exact set may vary depending on the operating system you use.

When you restore the store from a backup copy, it is supposed that you use the same tools and facilities to carry out inverse operations: restoring the store files from the archive and restoring the database content from the MySQL dump. In case you are restoring the store to a different location, in addition to this you will need to adjust some configuration settings.

For detailed instructions on how to handle store backups and carry out specific tasks, please refer to the following sections later in this chapter:

• Backing up the Store
• Restoring the Store from a Backup
• Safety Tips
• Troubleshooting

Remember that making a backup copy of a store and restoring the store from the backup are rather complicated tasks, which may become associated with a series of difficulties or even involve unpredictable effects. This document only provides a general description of the backup and restore procedures, and it does not intend to cover all types of situations that can occur while you back up or restore your store.

If you experience any difficulties in handling your store backups and you cannot find the answer in this document, you are welcome to address the alternative sources and services.

Backing up the Store

Prerequisites

Before you start making a back up copy of your store, make sure of the following:

• You have enough free disk space on your server or hosting account where your store is installed.

To estimate the minimal required amount of free disk space correctly, you can use the following formula: 2 kilobytes (kB) per each product in the store database + size of the folder images/ + size of the folder files/ + 50 megabytes (MB).

For example, if your store database consists of 5000 products, the size of the folder images/ is 66.7MB and the size of the folder files/ is 35.77MB, then you need (2 kB * 5000)/1024 + 66.7MB + 35.77MB + 50MB = 9.76MB + 66.7MB + 35.77MB + 50MB = 162.23MB.

Note: If you do not have enough free disk space, try to remove the files that you do not longer use or move them to another location.

• You can access your server or hosting account using one of these options: terminal SSH or Telnet access, FTP, remote desktop (available for Windows-based servers only), your hosting control panel.

Note: If you cannot access your server or hosting account via these or other alternative options, address your hosting team for help.

• The directory to which you are going to save the backup copy has writable permissions.

• The Customer area of your store is temporarily closed for maintenance.

Having the Customer area closed ensures that none of your website visitors will be able to shop through your store and place orders while you are backing up your store, and the backup will include all the info that is available by the moment you start this task.

To close the store for maintenance:

1. Log in to the Admin area.

2. Go to the General settings section.

3. In the General options box, select the Check this to close your shop temporarily check box. If necessary, enter a key for accessing the Customer area into the Key for access to a temporarily closed shop field.

4. Click the Save button.

From here on, all your store visitors will be automatically redirected to a special page saying that the store is temporarily inaccessible and can be visited later. To open the store back, log in to the Admin area and unselect the checkbox.

Backing up Store Database

With X-Cart the store administrator can back up the store database in a few easy steps directly from the Admin area. However, this way of backing up the database may be unsuitable if, for example, X-Cart utilizes third-party add-on modules and custom code: new tables introduced by these modules and code may be excluded from the SQL dump, which is generated automatically.

In such situations you must back up the database manually so that the dump includes all the store data. For this purpose you can use any adequate facility, including different client implementations of the SSH protocol like OpenSSH or PuTTY, Telnet, phpMyAdmin, MySQL console, control panel of your hosting account, Remote Desktop client and other. Later in this section you will find an example of how to create a database dump using terminal access (SSH or Telnet) to the server or hosting account where X-Cart is installed.

Backing up the database through X-Cart Admin area

To back up the database through the X-Cart Admin area:

1. Log in to the Admin area.

2. Go to the Database Backup/Restore section (In X-Cart versions 4.4.0 and later, this section can be found at Tools menu -> DB backup/restore; in earlier X-Cart versions, this section can be found at Administration menu -> DB backup/restore).

You will see the Database Backup/Restore box.

3. In the Backup database section of the box, click the Generate SQL file button. If necessary, additionally select the Write SQL dump to file '<file_name>' check box;

By selecting the check box you tell X-Cart to save the SQL dump to the default file and location on the server file system (file xcartdump.sql in the directory <xcart_dir>/var/tmp/). It is good to save the SQL dump to the server if it is going to be rather large and you want to ftp it to your local computer or another location on the server later. If you leave the check box unselected, the SQL dump will be saved onto your local computer.

Important: If you do not have access to your server/hosting account through FTP, SSH or other suitable facility, do not select the check box and save the SQL file directly to your local computer.

Backing up the database using terminal access

To back up the database using terminal access to the server:

1. Log in to your server or hosting account.

2. Go to the X-Cart root directory.

3. Run the following shell command.

> mysqldump -h<db_host> -u<username> -p<password> -r<backup_filename> <db_name>

The abbreviations in the command mean:

db_host	:: The DNS name or the IP-address of your MySQL server.
username	:: The username for your MySQL user account.
password	:: The password for your MySQL user account.
backup_filename	:: The name and the path to the newly created SQL file with the database dump.
db_name	:: The name of the MySQL database that you use for X-Cart.

After you have run the command, the system will generate an SQL file and save it to the directory that you have specified in the <backup_filename> part of the command. If you have specified the name of the file for the backup only without mentioning the path, the file will be saved be saved to the X-Cart root directory, the directory where you are currently located.

If necessary, you can use a different path, but it is yet recommended that it be a location within the X-Cart root directory.

Backing up Store Files

Creating a backup copy of the store files presumes that you pack all the files in the X-Cart root directory into an archive and then copy or move the archive to a new location on the remote server or your local computer.

Note: If you have previously saved the database dump into the predefined file in the X-Cart root directory (folder <xcart_dir>/var/tmp/), the file will also be included into the archive.

To create an archive you need to use a file archive manager. The exact choice of the archive manager will depend on the operating system you use. On a UNIX-based server, the most popular archive manager, which is currently installed on the majority of servers, is TAR. Later in this section you will find an example of how to archive the X-Cart files with the TAR archive manager. On a Windows-based server, you can create the archive with one of the available file archive managers for Windows, including WinRAR, WinZIP, PKZip and 7Zip. You need to pack the whole X-Cart root directory to an archive and then save the archive to the directory that is parent to the X-Cart root directory.

Alternatively, if it is not possible to pack the X-Cart files into an archive directly on your server, you can copy the X-Cart root directory to your local computer or another remote server using FTP or other suitable facility. Before that, make sure the new location, to which you are planning to copy the X-Cart root directory, has enough free disk space. Besides, the control panel of your hosting provider may offer its own facilities for backing up your account data.

Backing up store files with the TAR archive manager (UNIX-based servers only)

In UNIX-based systems, TAR is known to be one of the most reliable and trustworthy utilities for creating and manipulating file archives. It is now commonly used in tandem with external compression utilities like GZIP, BZIP2 or LZMA, which enables you not only to create an archive, but also compress the data in the archive. As a result, with TAR you can create a lightweight archive of your store and then restore it using the same utility. To find out whether TAR is installed on your server, run the following shell command.

> tar --version

If TAR is installed on your server, the system will display a message with the version of the utility; otherwise you will see an error message. In case of the latter, please contact your hosting team for help.

To back up files with the TAR archive manager:

1. Log in to your server or your hosting account.

2. Go to the X-Cart root directory.

3. In the X-Cart root directory run the following shell command.

> tar -czvf ../store_backup.tgz *

After you have run the command, TAR will pack all the files in the X-Cart root directory to the file store_backup.tgz and compress it with the ZIP data compression algorithm. The file will be saved to the directory that is parent to the X-Cart root directory. For example, if the X-Cart root directory is u/user/public_html/xcart, the file store_backup.tgz will be saved to directory u/user/public_html.

Restoring the Store from a Backup

Generally speaking, restoring a store from a backup copy is an inverse procedure to creating the backup copy, which is described in section #Backing up the Store earlier in this manual. When restoring the store, you are expected to use the same tools that you used to create the backup copy. Similar to creating the backup, restoring does not cause any serious difficulties, but it yet requires the standard sequence of operations: restore the store files and then restore the database. One of the major rules to be observed is to restore data from the backup to a newly created directory within the WWW part of your hosting account. You must keep with this rule no matter whether you simply copy/move the store to a new location or replace an existing installation with the backup copy. After you have restored your store from the backup, you may need to adjust some configuration settings, including the values of the variables in the main configuration file config.php, paths to images, file permissions, etc.

Prerequisites

Before you start restoring your store from a backup, make sure of the following:

• You can access your server or hosting account using one of these options: terminal SSH or Telnet access, FTP, remote desktop (available for Windows-based servers only), your hosting control panel.

Note: If you cannot access your server or hosting account via these or other alternative options, address your hosting team for help.

• You have enough free disk space on the server where you are planning to restore your store. It is recommended that you have at least twice as much free disk space as is taken by the backup copy (X-Cart files + SQL dump).
• The directory to which you are planning to restore your store has writable permissions.

Restoring Files from Archive

The instructions below generally describe how to restore X-Cart files from a backup copy. Examples and notes are provided for UNIX- and Windows-based servers. Many of the listed operations can be carried out through your server/hosting control panel (if any).

To restore X-Cart files:

1. Log in to your server or your hosting account.

2. Go to the directory that contains all your Internet projects (usually referred to as the WWW directory), and create a new directory where you will deploy the store from the backup.

• On a UNIX-based server, you can create the new directory using the following shell command.

> mkdir xcart

• On a Windows-based server, you can create the new directory using the graphic user interface (GUI).

As a result, you should get an empty directory that is accessible through the Internet.

3. Go to the directory that you have just created and upload the X-Cart files (or the archive with X-Cart files) onto the directory using FTP, SCP, your control panel or other suitable facility.

4. If you have the X-Cart files in an archive, extract them using the available utilities.

• On a Unix-based server, you can extract files from the archive using the following shell command.

> tar -xfv <archive_name>

or

> tar –xzvf <archive_name> # If the archive has file extension *.tar.gz, *.gz or *.zip

or

> tar –xjvf <archive_name> # If the archive has file extension *.tbz.

• On a Windows-based server, you can extract the archive with one of the available file archive managers for Windows, including WinRAR, WinZIP, PKZip or 7Zip.

5. Check the X-Cart directory. It must contain the standard X-Cart file structure. If it only contains one directory with the X-Cart files, move its content to the current directory.

6. If necessary, edit the main X-Cart configuration file config.php:

a) Locate the file config.php and open it for editing in your favorite plain text editor.

b) Set correct values for the following variables:

$sql_host =’%SQL_HOST%’;                        # The DNS name or the IP-address of your MySQL server
$sql_user =’%SQL_USER%’;                        # The username for your MySQL user account
$sql_db =’%SQL_DB%’;                        # The name of your MySQL database
$sql_password =’%SQL_PASSWORD%’;        # The password for your MySQL user account

and

$xcart_http_host =”$HTTP_HOST”;        # The host name of the server on which X-Cart is installed
$xcart_https_host =”$HTTP_HOST”;        # The host name of the secure server which provides access to X-Cart via the HTTPS protocol
$xcart_web_dir =”/xcart”;                # The web accessible directory of your server/hosting account where X-Cart files are located

For more info on how to edit these variable, refer to the X-Cart:Config.php page.

7. Create a new database for the store using a database management system (DBMS) that you usually use to manage your MySQL databases.

• On a Unix-based server, you can create the new database using the following shell command.

> mysql -h<sql_host> -u<sql_user> -p -e"create database <sql_db>;”

If you connect to the database server through a non-typical port or socket, use the following command.

> mysql -P<sql_port> -h<sql_host> -u<sql_user> -p -e"create database <sql_db>;"

or

> mysql -S<sql_socket> -h<sql_host> -u<sql_user> -p -e"create database <sql_db>;"

The system will ask you to to enter your password for the MySQL account. After the password is accepted, the system will create a new empty database for your store.

Important: The name/address of the MySQL server, the name of the MySQL database, the username and the password for the MySQL account must be the same as the values of the respective variables in the X-Cart configuration file config.php.

Restoring Database from SQL Dump

When you restore a database from an SQL dump, the existing database tables get overwritten. We strongly recommend that you always back up the current store database before restoring data from an SQL dump as it allows you to avoid any possible data loss. Another critical issue here is that you can restore the database only if the SQL dump was created for the same X-Cart version.

The store administrator can restore the database either through the X-Cart Admin area or manually. If you decide to carry out this task manually, ensure that you have access to the respective tools and facilities, including different client implementations of the SSH protocol like OpenSSH or PuTTY, Telnet, phpMyAdmin, MySQL console, control panel of your hosting account, Remote Desktop client and other. In this case, the exact instructions on how to restore the database from the backup will depend on the utility you use.

The example below describes how you can restore the database using terminal access (SSH or Telnet) to the server or hosting account where X-Cart is installed.

Restoring the database through X-Cart Admin area

To restore the database through the X-Cart Admin area:

1. Log in to the Admin area.

2. Go to the section Database Backup/Restore (In X-Cart versions 4.4.0 and later, this section can be found at Tools menu -> DB backup/restore; in earlier X-Cart versions, this section can be found at Administration menu -> DB backup/restore);

3. Restore the database from the SQL dump using the instructions below.

• (PREFERRED WAY) If the SQL dump is saved in the predefined file located on the server file system (file xcartdump.sql in directory <xcart_dir>/var/tmp/):

a) Click the Restore button.

b) Confirm the action.

c) Wait until the system displays a message saying that the database has been restored successfully.

• If the SQL dump is saved on a local computer:

a) Click the Browse... button to display the dialog box for uploading files.

b) Select the file with the SQL dump.

c) Click the Restore from file button.

Wait until the system displays a message saying that the database has been restored successfully.

Note: If your SQL dump is saved on your local computer, you can restore the database through the Admin area only if the size of the SQL dump does not exceed the value in line "WARNING! The maximum file size that can be uploaded:...". This value is defined by the PHP settings of your server. If you have access to the PHP configuration file php.ini, you can increase/decrease the maximum file size by editing the value of the variable $max_upload_size.
If changing the php.ini settings is not possible, you should rename your SQL dump to xcartdump.sql file, upload it to the directory <xcart_dir>/var/tmp/ (for example using FTP), then use the Restore button to restore the database from that file.

Restoring the database using terminal access

To restore the database using terminal access to the server:

1. Log in to your server or your hosting account.

2. Run the following shell command.

> mysql -h<sql_host> -u<sql_user> -p <sql_db> < <store_backup.sql>

If you connect to the database server through a non-typical port or socket, the command should be

mysql -P<sql_port> -h<sql_host> -u<sql_user> -p <sql_db> < <store_backup.sql>

or

mysql -S<sql_socket> -h<sql_host> -u<sql_user> -p <sql_db> < <store_backup.sql>

The system will ask you to to enter your password for the MySQL account. After the password has been accepted, the system will populate the database with the data from the SQL dump.

Important: The name/address of the MySQL server, the name of the MySQL database, the username and the password for the MySQL account must be the same as the values of the respective variables in the X-Cart configuration file config.php.

Safety Tips

Remove the SQL dump and the archive from the WWW directory of your server or hosting accoun. It is strongly recommended that you do not leave the SQL dump of the store database and the packed archive with X-Cart files anywhere in the WWW directory of your server or hosting account where you keep your Internet projects and which is publicly accessible. Otherwise, your store data can be easily stolen as anybody will be able to access the database dump through the Web.

A good practice here is to keep the backup on a local computer or in a directory on a remote server that cannot be accessed through the Web. For example, if the root directory of your hosting account is /u/user/ and the web directory is /u/user/public_html/, you must move the SQL dump and the store archive from the directory /u/user/public_html/ to somewhere in the directory /u/user/.

If you backed up the database through the X-Cart Admin area, make sure you have not left the dump (file xcartdump.sql) in the directory <xcart_dir>/var/tmp/, which is the pre-defined directory for the SQL dump generated by X-Cart.

Troubleshooting

Problem	Possible cause	Solution
The system says you do not have enough privileges to write to the file	User who has run the PHP script is not allowed to write files to the directory.	Set writable permissions to the directory where you are trying to save the SQL dump to, and repeat the task.
The system says you do not have enough free disk space to complete the operation.	File system does not have enough free disk space.	Since some data has been saved to the file before the error message, first remove the file with the backup. Then either make available more free space and repeat the task, or choose to save the file to another location.
Task was terminated and the system says you will be redirected to the previous page.	The memory that was allocated to the script has exhausted	Increase the amount of memory allocated to the script by increasing the default value of the $memory_limit variable in the php.ini file. If you do not have access to the php.ini file, ask your hosting team to help you. Important: It may be necessary to increase the allocated memory several times, because it is impossible to predict how much memory you really need.

Automatic backups with X-CloudBackup

Instead of creating backup archives manually you may want to consider using X-CloudBackup module to backup your data into a cloud storage automatically on a schedule.