Upgrading ShopSite on Linux/FreeBSD Servers

New versions of ShopSite are released periodically to provide merchants with new features or improvements on existing features. ShopSite Starter or Manager merchants may also want to upgrade service levels to get access to additional features. Upgrading ShopSite on Linux or FreeBSD server is easy; the only tools required are a Web browser and FTP or shell (SSH) access to your Web server.

Note:

Many ShopSite resellers and Web hosting providers will automatically upgrade your ShopSite store for you when a new version becomes available. You should contact the reseller or hosting provider if you have questions about upgrading your ShopSite store.

These instructions are for upgrading ShopSite stores on Linux/FreeBSD servers1. See the Installing ShopSite Help for instructions to install a new ShopSite store. There are different instructions for Installing or Upgrading ShopSite on Microsoft Windows Servers.

Warning:

Whenever connecting to your server for administrative purposes (such as installing or upgrading ShopSite), you should use a secure connection. Telnet and standard FTP are both unencrypted connections, and could be intercepted. Always use a secure connection, such as SSH for shell connections, and FTP over SSH or SFTP for file transfers.

Overview

ShopSite can be upgraded to newer versions or to higher service levels. A version upgrade installs a more recent release of ShopSite with new or improved features. Version upgrades can either be full versions (ShopSite 12.x to ShopSite 14.x) or point releases (ShopSite 14.0 to ShopSite 14.0 r3). A service level upgrade installs a greater feature set (ShopSite Manager to ShopSite Pro) within the same version.2

Upgrading to a Newer Version of ShopSite
Upgrading to a Higher Service Level (Starter, Manager Pro)
Upgrading to the Enterprise Service Level

Upgrading to a Newer Version of ShopSite

New versions of ShopSite are released periodically to provide additional features or improvements on existing features. When a new version includes significant improvements over the previous one, the major version number is incremented (e.g. 12.x to 14.x). This is called a full version upgrade. Between full releases, less substantial improvements are released as a point release upgrade, and the minor version number is incremented (e.g. 14.0 to 14.0 r3).

The process of upgrading to a new version of ShopSite is the same, regardless of whether it is a full or point release upgrade. To upgrade to a newer version of ShopSite, do the following:

Note:

If you are upgrading from a version of ShopSite prior to 8.1, you must remove orders placed prior to the upgrade in order to comply with PCI security guidelines.

Backup your existing store. You should always be sure any important information has been backed up before making any changes to your store. All store-specific information, including your auth file, is kept in your store's data directory. It is a good idea to store a backup copy of your data directory in a compressed archive on your local computer.

Note:

If you are upgrading ShopSite Enterprise you should also backup the Database Server before proceeding.

Obtain the ShopSite program installation files. You do not need a new auth file to upgrade your store, but you will need the program files for the version of ShopSite you are upgrading to. See Obtaining Installation Files in the install help for detailed instructions on obtaining the new ShopSite installation files.
Upload the installation files to your server. This is the same procedure outlined in Upload Installation Files in the install help. Your may need to copy the storeid.auth file from your data directory and save it as store.auth in your install CGI directory.3
Run wwwinstall.cgi in your Web browser. This is the same program used to install new stores, and is located in your store's Install Directory.
- Example Install URL: http://www.mystore.com/cgi-bin/shopsite-install/wwwinstall.cgi
Select the radio button to update4 your store and click Continue.
Confirm the paths ShopSite should be using for the upgrade, then select whether or not ShopSite should create a backup copy of your store's data directory before performing the upgrade. Click START UPDATE to continue.
If you chose not to have ShopSite backup your store content, you will get a warning message. If you have not already created a backup, you should check the box to have ShopSite create a backup. Click CHECK PERMISSIONS to continue.
ShopSite will check file permissions for the content that will be upgraded.5 If any locations do not pass the check, you will need to change the permissions on that directory before continuing. Your Web server needs to have read, write, and execute permissions to all ShopSite content in order to upgrade successfully. For more information, see Linux and FreeBSD File Permissions Explained. After fixing any permissions problems, click CHECK PERMISSIONS to have ShopSite test file permissions again.
Once all your directories pass the permissions check, click CONTINUE UPDATING to complete the upgrade. ShopSite will then install the upgraded content and program files. After the installation completes, you should log in to your ShopSite back office and confirm that the upgrade completed without errors.
After running the upgrade, you may have patch files to install. Follow the steps to install patches outlined in the installation help.

If you encounter any problems during the upgrade process, see the Troubleshooting section of the installation help.

Upgrading to a Higher Service Level

ShopSite is available in different service levels, with lower levels offering fewer features for a reduced cost. For example, ShopSite Pro offers several features to help you draw customers to your store that are not available in a less expensive ShopSite Manager store. See the Feature Checklist to compare features available in different service levels of the current version of ShopSite.

If you originally purchased a lower service level version of ShopSite but want to start using the additional features available in a higher service level, you can upgrade your current store without any hassles. All you have to do is install a new auth file to allow your store to run at the new service level:

Backup your current auth file. If something is wrong with your new auth file, you may need to restore the old one until you can get your new auth file replaced. Your auth file is located in your store's data directory, and is named storeid.auth (where storeid is the username you use to sign in to your ShopSite back office). You can make a copy of the file with a different name (storeid.auth.old, for example) in the same directory, or on your local PC.
Obtain a new auth file from your ShopSite reseller or hosting provider. The reseller who provided you with your original auth file can provide you with a new one for your new service level.
Save the new auth file as storeid.auth (where storeid is the username you use to sign in to your ShopSite back office) in your store's data directory. Make sure the file name matches the storeid of your store, or ShopSite will not run.
Log in to your ShopSite back office and check that the new auth file is installed correctly. The store version and service level are indicated at the bottom of the main back office screen, followed by your storeid. If you have any problems, see the troubleshooting section of the Auth File information page.

For more information about your auth file, see the ShopSite Auth File Information page.

Upgrading to the Enterprise Service Level

Unlike upgrading from Starter to Manager or Pro, Enterprise uses a different code base as well as needs an MySQL or MariaDB database server to be configured.

Backup your existing store. You should always be sure any important information has been backed up before making any changes to your store. All store-specific information, including your auth file, is kept in your store's data directory. It is a good idea to store a backup copy of your data directory in a compressed archive on your local computer.
Backup your current auth file. If something is wrong with your new auth file, you may need to restore the old one until you can get your new auth file replaced. Your auth file is located in your store's data directory, and is named storeid.auth (where storeid is the username you use to sign in to your ShopSite back office). You can make a copy of the file with a different name (storeid.auth.old, for example) in the same directory, or on your local PC.
Obtain a new auth file from your ShopSite reseller or hosting provider. The reseller who provided you with your original auth file can provide you with a new one for your new service level. Note that the storeid and serial number stored in the Enterprise auth file need to match what is stored in your current auth file.
If you are updating from ShopSite 12 sp3 or later:
- In your data dir replace your [storeid].auth file with your new Enterprise [storeid].auth file. Log in to your store and check that the initial ShopSite merchant interface (backoffice) comes up as normal. Check that you can view your existing orders and any payment info that you would normally have access to. If you cannot log in or you cannot view order payment info then the enterprise auth file serial number and/or storeid may be different than your previous auth file and this needs to be resolved before proceeding. In the upper left of the main backoffice screen and in the footer you should see that you are running ShopSite Enterprise. If this is not the case then the old auth file has not been correctly replace.
If you are updating from ShopSite 12 sp2 or earlier:
- do not replace your existing auth file at this time. Older versions of ShopSite will not recognize it. Instead, you will replace the auth file after the wwwinstall has been run to install the Enterprise software.
Log in to your ShopSite back office and check that the new auth file is installed correctly. The store version and service level are indicated at the bottom of the main back office screen, followed by your storeid. If you have any problems, see the troubleshooting section of the Auth File information page.
Obtain the ShopSite program installation files. See Obtaining Installation Files in the install help for detailed instructions on obtaining the new ShopSite installation files.
Upload the installation files to your server. This is the same procedure outlined in Upload Installation Files in the install help.
Run wwwinstall.cgi in your Web browser. This is the same program used to install new stores, and is located in your store's Install Directory.
- Example Install URL: http://www.mystore.com/cgi-bin/shopsite-install/wwwinstall.cgi
Select the radio button to update4 your store and click Continue.You should see a warning similar to the following:
Note: You are upgrading using ShopSite Enterprise, however, MySQL or MariaDB has not yet been configured. Once upgrade has been completed you will need to configure the database server by going to Utilities > Database or using the command-line options documented in the help.
Confirm the paths ShopSite should be using for the upgrade, then select whether or not ShopSite should create a backup copy of your store's data directory before performing the upgrade. Click START UPDATE to continue.
If you chose not to have ShopSite backup your store content, you will get a warning message. If you have not already created a backup, you should check the box to have ShopSite create a backup. Click CHECK PERMISSIONS to continue.
ShopSite will check file permissions for the content that will be upgraded.5 If any locations do not pass the check, you will need to change the permissions on that directory before continuing. Your Web server needs to have read, write, and execute permissions to all ShopSite content in order to upgrade successfully. For more information, see Linux and FreeBSD File Permissions Explained. After fixing any permissions problems, click CHECK PERMISSIONS to have ShopSite test file permissions again.
Once all your directories pass the permissions check, click CONTINUE UPDATING to complete the upgrade. ShopSite will then install the upgraded content and program files. If you will see this warning after wwwinstall completes:
Note: You are upgrading using ShopSite Enterprise, however, MySQL or MariaDB has not yet been configured. Once upgrade has been completed you will need to configure the database server by going to Utilities > Database or using the command-line options documented in the help.
Follow the the Database Server Configuration instructions for setting up your database server and for migrating the Standard ShopSite databases into the database server.
After running the upgrade, you may have patch files to install. Follow the steps to install patches outlined in the installation help.

If you encounter any problems during the upgrade process, see the Troubleshooting section of the installation help.

Footnotes:

1. If you are a ShopSite reseller using the scripted installation utility, see the Upgrading instructions in the Scripted Install help.

2. To avoid unnecessary complications, you should not attempt to upgrade version numbers and service levels at the same time. If you want to do both, start by upgrading versions, then upgrade your service level. This will make it easier to troubleshoot upgrade problems, and cost you less.

3. If you did not delete your install CGI directory, your auth file is already there with the name store.bak, and you can simply rename it store.auth to upgrade your store.

4. The option to install a new store will wipe out an existing store using the same auth file. If you want to keep settings and content from an existing store, make sure to use the option to upgrade your store.

5. If you are upgrading a mall with more than one store in it, you will get an additional screen before the file permissions check which mentions some information you should be aware of. You will need to click CONTINUE to proceed to the file permissions check.