Installing ShopSite on Linux/FreeBSD Servers

ShopSite is easy to install on your Linux or FreeBSD Web server; the only tools required are a Web browser and FTP or shell (SSH) access to your Web server.

Note:

Most ShopSite hosting partners will install ShopSite on your server for you. You should contact your ShopSite partner if you have questions about your ShopSite installation.

These instructions are for installing new ShopSite stores on Linux/FreeBSD servers.1 See the Upgrade Help for instructions to upgrade an existing ShopSite installation.

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

The process of installing ShopSite includes the following phases:

Preparing to Install
Obtain Installation Files
Upload Installation Files
Run Installation Program
Access Logging for PCI Compliance
Troubleshooting

In order to keep the instructions as clear as possible, examples that follow assume you are installing a single2 ShopSite store on the main domain name of your Web server, and that your Web server files are located within the /www directory on your server. If you are installing your ShopSite store in a different location, you will need to use the appropriate paths for your Web server.

Preparing to Install

If you are running a properly configured, compatible Web server, ShopSite usually does not require any special Web server configuration. Before you get started, however, you should be aware of the following:

ShopSite runs on a variety of Operating Systems and Web servers. See the System Requirements Help to make sure you have a compatible Web server.
In order to comply with PCI Security Requirements, you Must have SSL (secure connections) configured and working on your Web server, and you must configure ShopSite to use SSL. Additionally, PCI compliance requires that the OS and web-server support and implement an active access log. For information on enabling and configuring access logging in Apache Web Server, see Apache's documentation.

Prior to beginning the installation, you should plan out where you will install the different ShopSite directories2. You do not need to create any of these directories at this time, but you should decide where they will be and make sure they will have the required access. ShopSite will let you put the directories wherever you want, and you can name them however you wish, as long as the directories have the appropriate access rights for the Web server3. You will be prompted to specify the locations for these directories as part of the installation process.

CGI Directories
ShopSite uses numerous CGI programs, which must be allowed to run from a Web browser. Your Web server may already have a cgi-bin directory where you can put your ShopSite CGI directories, or you can configure your Web server to allow CGIs to run in the directories where the ShopSite CGIs will be. In order to run CGI programs, the Web server must also have read and write permissions for these directories and all their contents, and execute permission for the directories and any CGI programs in them3. ShopSite uses the following CGI directories:
- Install Directory - This is the directory where you will upload and run the installation files. This directory is only required while you are installing or upgrading ShopSite. Once you have ShopSite running properly, it is a good idea to restrict Web access to or remove the install directory.
  Example FTP/Shell Path: /www/cgi-bin/shopsite-install
  Example URL4: http://www.mystore.com/cgi-bin/shopsite-install
- Shopping Cart Directory - This is where the shopping cart CGI files will be stored.
  Example FTP/Shell Path: /www/cgi-bin/sc
  Example URL4: http://www.mystore.com/cgi-bin/sc
- ShopSite Directory - This is where the merchant back office CGI files will be stored.
  Example FTP/Shell Path: /www/cgi-bin/ss
  Example URL4: http://www.mystore.com/cgi-bin/ss
HTML Directories
In order to access the static HTML elements of your store, the Web server must have read and write access to these directories and their contents. The directory itself also needs to have execute permissions for the Web server3. ShopSite stores static HTML content in the following directories:
- Store Pages Directory - this is the directory where ShopSite will put the store pages it generates. It may also be referred to as your HTML Output Directory. Most merchants will want this to be the same directory as their domain name's root URL. The URL of this directory is included in the store auth file and can not be changed without obtaining a new auth file.
  Example FTP/Shell Path: /www/htdocs
  Example URL4: http://www.mystore.com
- Store Media Directory - this is the directory which contains the images your store uses. It is a non-configurable sub-directory of the Store Pages directory. While you can not configure this directory, you should consider it when planning the location of your Store Pages directory. You can upload images to this directory in the back office, but you may also want to have FTP access to this directory if you will be uploading a large number of images.
  Example FTP/Shell Path: /www/htdocs/media
  Example URL4: http://www.mystore.com/media
- ShopSite Images Directory - this is the location where ShopSite stores images used by the back office and by some of the built-in themes.
  Example FTP/Shell Path: /www/htdocs/shopsite-images
  Example URL4: http://www.mystore.com/shopsite-images
Data Directory
The store data directory is where the databases and store configuration files are located. This directory must have read and write permissions for the Web Server3, but it should not be accessible from a Web browser. This means it must not be inside any directory that can be accessed from a Web browser (such as the htdocs or cgi-bin directories). This is an essential requirement for PCI Security Requirements.
Example FTP/Shell Path: /www/data
Not Accessible using a URL

Obtaining Installation Files

Once you are ready to install ShopSite, you need to obtain the installation files. Each ShopSite store requires a unique Auth file in order to run. See the Auth File Help for information about what an Auth file is and how to obtain one. Make sure you save your Auth file in a location where you will be able to find it later. Be sure to use ASCII (text file) format any time you use FTP to transfer your Auth file.

The ShopSite program files must be installed on the Web server.2 ShopSite partners can obtain the program installation files directly from ShopSite by following the instructions below. You will need the partner ftp username and password you were given when you signed the partner agreement. Make sure you have them ready before you start.

FTP to the ShopSite Support FTP server and download the installation files using one of the following methods:

Using an FTP client on your local computer:
1. Open your FTP client program and open the Connect dialog.
2. Enter support.shopsite.com as the Hostname.
3. When you are prompted, enter the username and password you were provided.
4. On the Server, change to the directory that correlates to your Web server operating system.
5. On your local computer, change to the directory where you want to put the installation files. You may want to use the same location where you put your Auth file.
6. Use Binary (BIN) mode to copy the appropriate "zip" installation file to your local computer. For example a Linux server for version 14 of ShopSite would have the following options for Starter/Manager/Pro stores:
  shopsite-14.0-linux-32-bit.zip or shopsite-14.0-linux-64-bit.zip
  and for Enterprise stores:
  enterprise-14.0-linux-64-bit.zip
7. If there is a patch directory in the operating system directory, you will also need to copy any files in that directory to a sub-directory on your local computer using Binary (BIN) transfer mode.
Using a Web browser on your local computer:
1. Open your Web browser and enter the following URL into the location bar. You will need to replace MyUserName and MyPassword with the username and password you were provided:
  ftp://MyUserName:MyPassword@support.shopsite.com/
2. Click on the name of the directory that correlates to your Web server operating system.
3. Click on the appropriate "zip" installation file to your local computer. For example a Linux server for version 14 of ShopSite would have the following options for Starter/Manager/Pro stores:
  shopsite-14.0-linux-32-bit.zip or shopsite-14.0-linux-64-bit.zip
  and for Enterprise stores:
  enterprise-14.0-linux-64-bit.zip
4. When prompted, select a location to save the file on your local computer. You may want to use the same location where you put your Auth file.
5. If there is a patch directory in the operating system directory, you will also need to save any files in that directory to a sub-directory on your local computer.
Using an FTP client on your Web server:
1. Use SSH to connect to your Web server, then FTP to support.shopsite.com.
2. When you are prompted, enter the username and password you were provided.
3. On the ShopSite support server, change to the directory that correlates to your Web server operating system.
4. Change to the directory on your Web server where you want to store the installation file. It is a good idea to use a different directory than the one you will unzip the archive into, so you don't accidentally overwrite anything important.
5. Use Binary (BIN) mode to copy the appropriate "zip" installation file to your local computer. For example a Linux server for version 14 of ShopSite would have the following options for Starter/Manager/Pro stores:
  shopsite-14.0-linux-32-bit.zip or shopsite-14.0-linux-64-bit.zip
  and for Enterprise stores:
  enterprise-14.0-linux-64-bit.zip
6. If there is a patch directory in the operating system directory, you will also need to copy any files in that directory to a sub-directory on your Web server using Binary (BIN) transfer mode.
7. Unless otherwise indicated, you will still need to follow the Upload Installation Files steps below.

Upload Installation Files

Once you have all the files required to install ShopSite, you need to create the install CGI directory on your Web server and copy the install files into that directory.

Create the directory from which you will run the Install CGIs. This is the Install Directory you planned out during the preparation stage. Make sure the Web server has the correct permissions and ownership for the directory3, and that the directory is in a location where you can run CGIs from a Web browser.
Copy the store Auth file to the Install Directory on your Web server. Be sure to use ASCII (text file) format any time you use FTP to transfer your Auth file. If your Auth file has a different name, change the file name to store.auth. You must have your Auth file in the install directory before you can install or use ShopSite.
If you do not have SSH access on your server, you will need to unzip the install file before uploading it to your server.
Copy the install file (or all the files you extracted from the install file) to the Install Directory on your Web server. If you are using FTP, make sure to use Binary (BIN) transfer mode.
If you have not already unzipped the install file, unzip it into the Install Directory on your Web server.
Check to make sure all your files have correct permissions and ownership3.
If you need to conserve disk space, you may remove the install file (the .zip file only) at this time.

If you have any patch files, you will apply them after you have completed installing ShopSite.

Note:

If you are installing ShopSite Enterprise you must now Setup the Database Server before proceeding.

Run Installation Program

Once all the required files are in your Install Directory and have appropriate permissions and ownership3, you can run the Installation Program from your Web browser. To start, enter the Install Directory URL followed by /wwwinstall.cgi into the location bar of your Web browser, then press Enter.

Example Install URL: http://www.mystore.com/cgi-bin/shopsite-install/wwwinstall.cgi

When the Install Program loads in your Web browser, you should see ShopSite Install Menu displayed at the top of the screen. See Troubleshooting if you do not see this screen.

Select the radio button to Create a new ShopSite installation (with first store) and click Continue.

The next screen is where you will enter the settings, including directory locations and URLs, for the store. The Install Help button at the top of the screen will open this help page in a new browser window. You will be required to enter the following settings:

ShopSite CGI Directory and URLs

ShopSite directory

This is the FTP/Shell path of the ShopSite Directory.

URL of ShopSite CGI's

This is the URL of the ShopSite Directory.

Secure URL of ShopSite CGI's (Optional)

This is the secure URL of the ShopSite Directory for use when you have a security certificate.

ShopSite CART CGI Directory and URLs

Shopping Cart directory

This is the FTP/Shell path of the Shopping Cart Directory.

URL of Shopping Cart CGI's

This is the URL of the Shopping Cart Directory.

Secure URL of Shopping Cart CGI's (Optional)

This is the secure URL of the Shopping Cart Directory for use when you have a security certificate.

ShopSite Images Directory and URLs

ShopSite Images directory

This is the FTP/Shell path of the ShopSite Images Directory.

URL of ShopSite Images

This is the URL of the ShopSite Images Directory.

Secure URL of ShopSite Images

This is the secure URL of the ShopSite Images Directory for use when you have a security certificate.

General Settings

Location of sendmail executable

This is the FTP/Shell path for sendmail on your server.

Location of tar executable

This is the FTP/Shell path for the tar utility on your server.

Store Settings

Store directory (associated with Store URL defined in AUTH file)

This is the FTP/Shell path of the Store Pages Directory.

Store URL

This field displays the URL for the Store as defined in the AUTH file.

Secure Store URL

This is the secure URL for your Store, to be used if you have a security certificate.

Data directory

This is the FTP/Shell path of the Data Directory.

Password for StoreID

Enter the password that will be initially used to access the ShopSite back office. The merchant can change the password by going to Utilities > Change Password after logging in.

Note:

In order to meet PCI Security guidelines, you must use a secure password.

Merchant email address

Enter the contact e-mail address for the merchant. The merchant can change this later by going to Preferences > Hosting Service after logging in.

Locale

Select the locale for ShopSite to use. The merchant can change this later by going to Preferences > Locale after logging in.

Currency

Select the primary currency for ShopSite to use. The merchant can change this later by going to Preferences > Locale after logging in.

To use the secure URLs listed above, check the box for Enable use of any secure URLs specified above? If you have the certifications and correct secure URLs, they should be available upon installation completion.

If you have not already created the directories ShopSite will use, check the box for Do you want Install to create any directories that do not already exist? If you set up your permissions properly, ShopSite should be able to create these directories.

Click OK to install ShopSite using the settings you specified. The Installation Progress screen will display information about the installation, with any warnings or errors displayed in red. If the installation completes successfully, you will see The update has been completed in large text near the end of the screen. ShopSite will rename the store.auth file to store.bak when the install completes to prevent anyone from running the Install Program again.

Once the installation is complete, you will need to install any patches that you have. Patches are usually a newer version of a CGI file included in the original installation. To install a patch file do the following for each patch file:

Using FTP or SSH, locate the existing CGI with the same name of the patch file.
Back up the existing CGI file by renaming it or copying it to a new location (for example, you could change order.cgi to order.cgi.old).
Copy the patch file to the directory where the existing CGI was. If you are using FTP, make sure to use Binary (BIN) transfer mode.
Make sure the patch file has the correct ownership and permissions3 for the Web server.

Once you have confirmed that ShopSite is installed and working, you may remove the Install Directory and its contents in order to free up disk space. If you do not delete the directory, you should at least change permissions3 for the Install Directory so it is no longer accessible from the Web, in order to prevent anyone from accessing the Installation Program without permission.

Access Logging for PCI Compliance

In addition to the information provided above, you should also be aware that PCI compliance requires access logging by the webserver (in this case, Apache) and also by the OS. Access logging is enabled by default for both. Disabling access logging will invalidate PCI compliance. Please see this article for information on Apache Webserver access logging and this article for more information on access logging for Ubuntu and CentOS.

Troubleshooting

If you encountered any problems installing ShopSite, look at what errors you got, and where you got them, then check this list of troubleshooting tips to see if your problems were caused by any of these common mistakes:

Are all your file permissions correct? Incorrect Permissions3 are the most frequent cause of problems installing ShopSite. In order to install ShopSite, you must grant your Web server the permission to view, modify, and run the files used in the installation. The File Permissions Explained page provides a more detailed explanation of file ownership and permissions.
Did you use ASCII format to transfer your Auth file? - Any time you use FTP to transfer your Auth file, you should use the ASCII (text file) format. If you transferred the file using BIN format, the end-of-line characters in the file may not match the ones used by your operating system, causing the file to appear corrupted to the Web server. Always use ASCII format to transfer your auth file via FTP.
Does your Web server allow CGIs to run? The ShopSite install directory needs to be in a location where you can run CGI programs from a Web browser, such as the cgi-bin directory. You may need to change the location of your install directory, or make configuration changes to your Web server to allow you to run CGI programs in your ShopSite CGI directories. Contact your hosting provider for more information about configuring your Web server.
Did you use binary transfer mode to upload the install files? The install zip file and the files within it are binary (encoded) files. If you upload or download a binary file using ascii (plain text) transfer mode, the files will be corrupted. Make sure you use binary transfer mode when you download the files from ShopSite and when you upload them to your Web server.
Are you using the correct Store URL and ID? When your store.auth file was generated, you specified a Store URL and a store ID to use for your store. The URL and ID are used to help uniquely identify your store, and are encoded in your store.auth file. If you want to use a different URL or store ID, you will need to obtain a new auth file. See ShopSite Auth File Information for details on obtaining and replacing an auth file.
Is your Store.auth file in the install directory? The ShopSite install program requires your store.auth file to be in the same directory as the install files. If your auth file is in a different location, or is not named store.auth, you will need to correct that before the install program will run. After completing the installation, your auth file is renamed store.bak in order to prevent the install program from being run without your authorization.

Footnotes:

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

2. If you are installing multiple ShopSite stores on a single server, you can save space by having all the stores use the same CGI and ShopSite Images directories. Each store must have its own HTML, Media, and Data directories, as well as a unique license (auth file). For more information on installing multiple stores on a single server, see the Creating a ShopSite Mall instructions.

3. Linux and FreeBSD use file permissions to control what level of access a program (or the person using a program) has to a file or directory on the server. In order to install or run ShopSite, you must ensure the Web server has the correct ownership and permissions to run the install CGI and access the other install files. The ShopSite install files and the directory that contains them should belong to the user and group the Web server requires (usually, this is the user and group the Web server runs as). You will also need to grant the user and group read and write permission for the directory and files, and execute permission for the directory and the install CGI. See file permissions explained for more detailed information.

4. Sticklers for proper formatting of URLs will have noticed that when indicating a URL for a directory (rather than a specific file), the examples do not include a trailing slash at the end of the URL. The reason for this is because ShopSite uses the URLs from the configuration to create URLs to specific files, and will attach a slash before the path to the file. If you include a trailing slash in the URLs when you configure ShopSite, your URLs will get an extraneous slash in them such as http://www.mystore.com/cgi-bin/sc//order.cgi. While this normally will not cause any problems using ShopSite, it is not the proper way to format URLs either.