Documentation Home

# Welcome to Zen Cart®

Dear Zen Cart® User,

Zen Cart® is made available to you for your use, addition, changes, modification, etc. without charge, under Version 2 of the GNU General Public License.

While we do not charge for this software, donations are greatly appreciated, each time you install a new version, to help cover the expenses of maintenance, upgrades, updates, the free support forum and the continued development of this software for your online E-Commerce store.

Donations can be made on the Zen Cart® Team Page

We appreciate your support.
The Zen Cart® Team

# Zen Cart® Requirements

- For up-to-date requirements, see: Zen Cart® Server Requirements
- Apache must be configured with AllowOverride set to either "All" or at least both "Limit" and "Indexes" parameters, and preferably the "Options" parameter as well.
- PHP must be configured to support CURL with OpenSSL

While Zen Cart® can run on Windows/IIS servers, Linux/Apache servers are recommended for best results.

# Installing for PA-DSS Compliance

For installation instructions related to PA-DSS Compliance, see the Implementation Guide in your /docs/ folder.

# Getting Started

## The Basics

You have downloaded the Zen Cart® software for an online shopping cart.

Since you're reading this file, you have likely already unzipped the Zen Cart® distribution file and its contents into a folder on your personal computer. If for some reason you have not already done so, unzip the files to your PC now, retaining the file structure within the zip file.

This is a basic guide for new installations of Zen Cart®. If you already have Zen Cart® installed and wish to upgrade from a previous version, please see the Upgrade Instructions and the What's New documentation.

## Preinstallation Questions

1. Do you have a domain?

- If No, stop ... see our Compatible Hosting list and find a fast, reliable web hosting provider who can help you register your own personal domain as well as provide for your hosting needs that meet the Zen Cart® software requirements.

2. Do you have reliable FTP software?

- If No, stop ... you need to obtain a reliable FTP software package such as FileZilla (free), FlashFXP or another FTP software program to transfer files back and forth from your computer to your webserver.
- NOTES:
  1. "Webserver" is the computer on the internet where you have your domain hosted (See Item 1)
  2. Many users have had timeout and other problems when using programs like SmartFTP and CuteFTP. We recommend that you do NOT use these problematic programs.
  3. If your web hosting provider provides an FTP program that runs inside your browser, we recommend that you do NOT use that for uploading large amounts of files such as a fresh install of Zen Cart. Those are okay for single-file uploads, but unreliable for several files at once.

3. Do you have a good Text Editor?

- If No, stop ... you will need a good Text Editing software such as UltraEdit, Notepad++ (free), CrimsonEditor (free), BBedit(Mac), Kedit (linux), or some other type of Text Editor for modifying the files in Zen Cart®.
- NOTES:
  1. Do NOT use CPanel for editing files, nor MS Word or other software designed for fancy writing ... you want a nice clean Text Editor.
  2. You can use the Windows Notepad... but this is limited in capabilities and the size of files that it can open and often can cause more harm than good.

4. Do you have access to your webhosting control panel to create a MySQL database and user?

- BEFORE YOU PROCEED, make sure you have access to a MySQL database, and username/password to that database. You may need to create the database using your webhosting control panel. Contact your web hosting provider for assistance.
- NOTES:
  1. Zen Cart® cannot create the database for you.
  2. You need the following permissions on your MySQL user: SELECT, INSERT, UPDATE, DELETE, CREATE, ALTER, INDEX, DROP.
  3. On an hSphere host, this would be "dba" access, or at least read/write.

If you have answered "Yes" to ALL four questions, you are ready to go on.

# Upload the Zen Cart® Fileset

## How do I Upload Files?

Using FTP software, upload the whole Zen Cart® fileset into a directory on your server. Example: /catalog/

We will use "/catalog/" as an example here. You can choose "no" foldername, or something else if you prefer, such as "/zencart", or "/store/" etc

## What Folder do I Upload Into?

Each web hosting provider has their own preference in naming folders running a website.

You can have many files that do not even get shown to the public. The ones that are available for access via a browser are usually in a folder called something like:

/home/YOURNAME/public_html
- or -
/var/www/YOURNAME/httpdocs
- or -
/usr/accounts/a/b/YOURNAME/httpd
- or -
- etc, etc, etc -

Basically, in your FTP software, look for a "www" or "public_html" or "htdocs" or "httpdocs" or "wwwroot" folder. These are the common folder names for what is referred to as the "webroot", which is where all website content is served from.

Your Zen Cart files need to be under that folder. If they are not, then you will get "not found" errors ... because the content is not found!

If it is unclear where the publicly accessible files are to be uploaded, ask your web hosting provider for assistance.

# Creating Configure.php Files

1. Two files need to be created on the server. These are the configure.php files that identify the settings of your particular server and the location of the files that you just loaded. After they have been created, you will then need to change the permissions on these files.
   1. Changing permissions can be done via your FTP program with the chmod feature.
   2. Usually right clicking on a directory or filename will open a menu with this option (perhaps under "Properties")
2. On the server locate the file: /catalog/includes/dist-configure.php
   - Rename this file to configure.php and change the permissions to 777 (read-write-execute for all)
3. Next, on the server locate the file: /catalog/admin/includes/dist-configure.php
   - Rename this file to configure.php and change the permissions to 777 (read-write-execute for all)

NOTES FOR IIS USERS:
1. If using IIS for Windows hosting, the "chmod 777" idea for permissions settings is likely foreign to you. In IIS, under Windows, you need to right-click on the file (or folders in the next section below), and choose "Properties".
2. Then under the Security tab, ensure that the"Internet Guest Account", identified usually as: MACHINE_NAME\IUSR_MACHINE_NAME ... has at least "read" and "write" privileges ... likely best to give "modify" as well.
3. This should be done on each file/folder indicated.
4. If the IUSR_MACHINE_NAME account is not listed, click "Add" and add that account from the list, and then set the required permissions.
5. "_MACHINE_NAME" above refers to the "machine name" or "computer name" configured by the server administrator to "name" the server.

# Setting Permissions

## Main Folder Permissions

Now, change the permissions on the following directories to 777 (read/write/execute):
- /catalog/cache
- /catalog/images
- /catalog/includes/languages/english/html_includes
- /catalog/logs
- /catalog/media
- /catalog/pub
- /catalog/admin/backups
- /catalog/admin/images/graphs

Open the /catalog/images directory and change ALL of the subdirectories and their subdirectories to 777 as well. For example (this is a partial list):
- /catalog/images/attributes
- /catalog/images/dvd
- /catalog/images/large
- /catalog/images/large/dvd
- /catalog/images/medium
- /catalog/images/upload

- If you miss any of the images directories and subdirectories inside /images and try to use them later, you will get an error message that you cannot write to these directories.

## Other Folder and File Permissions

Depending on your webserver configuration, other folders and files can be set to:
- Folders: CHMOD 755
  - "CHMOD" is a linux/unix term for setting/changing permission levels
- Files: CHMOD 644
  - These are typically the defaults that your FTP program will use when uploading, so usually do not need to be set manually.

^^ Back to Top ^^

# Before Running the Installer

The installer is fairly intelligent and should be able to automatically supply answers to the questions listed below.

You will, however, need to confirm that the auto-detected answers are, in fact, correct as on some servers they may differ.

You will need the following information for the installation:

- The physical path to your new Zen Cart® directory
  Example: /home2/zencart/public_html/catalog
- The Virtual HTTP Path (the URL to your domain and directory for your shop)
  Example: http://www.mydomain.com/catalog

# SSL Considerations

A Secure Sockets Layer (SSL) is the standard security technology for establishing an encrypted link between a web server and a browser.

If you are installing onto a live webserver where you intend to process real transactions, you should plan on securing your customers' transaction data with SSL.

If you do not already have an SSL certificate, talk to your web hosting provider about your available options. You will need to enter your SSL details as below. In most cases they will be correct, unless you are using a "shared SSL" service. Your web hosting provider can give you the correct details.

- The Virtual HTTPS Server (the secure URL to your domain)
  Example: https://www.mydomain.com
  If you have a shared certificate on a virtual server this may look like:
  - https://mydomain.secureservername.net/
  - - or -
  - https://secure.sharedservername.net/~username
- The Virtual HTTPS Path (the secure URL to your domain and directory for your shop)
  Example: https://www.mydomain.com/catalog
  - or -
  https://secure.sharedservername.net/~username/catalog

If you are installing to a local PC or to a development server where you do not need to protect sensitive data, you can leave the SSL settings at their defaults, and when asked about enabling SSL later in the installation process, just leave it off if you are not on a live production server.

^^ Back to Top ^^

# Running the Installer

## Starting the Installer

- In your browser, enter the URL to your new shop, and the Installer should automatically start.
  - Example: http://www.mydomain.com/catalog
    - or - , to start the installer directly,
    http://www.mydomain.com/catalog/zc_install

You will be presented with a "Welcome to Zen Cart®" page, explaining the features of Zen Cart®.
- If you now see a list of filenames and directories, you should speak to your web hosting provider about how to setup your server to auto-detect PHP filename extensions

Clicking on Continue takes you to the license screen where you are asked to read and confirm acceptance of the GPL licensing agreement.

## System Inspection Step

The Installer examine your server for compliance with technical requirements for running Zen Cart®, presenting you with several items you may need or want to address with your host.

Anything marked in red or with an "X" must be addressed before the installer can continue. Things marked with an orange or yellow "caution" symbol are simply warnings that may or may not apply to your setup now. The image folders and others as described earlier in this document are also noted.

If you make changes to your server, you can click Re-Check or press F5 in your browser to refresh the display and reflect the changes you've made before proceeding.

If a previous version of Zen Cart® is found on your server, the installer will attempt to determine the database patch level and display that on the screen as well. In this case, an "upgrade" button will display at the bottom of the screen offering you the ability to upgrade if needed.

See the Upgrade Instructions.

Once you are satisfied that the "pre-flight-check" inspection is OK for your needs (ideally, all green check-marks), you may click the "Install" button at the bottom of the screen.
- If you receive any of the following error messages, go through the above steps to make sure you have not left anything out. All error messages have context-sensitive help via a popup window if you click on the "more info..." links supplied.

Warning: Problems Found
- /includes/configure.php does not exist. more info...
- /admin/includes/configure.php does not exist. more info...

## Database Setup Step

On the next screen, you are asked for Database Information about your MySQL database, username and password. These can be obtained from your cPanel or equivalent control screen provided by your host.

If you do not have a clean MySQL database setup with a username and password, you will need to create one.

Contact your web hosting provider if you need assistance in creating a MySQL database table and/or username and password.
- You need to have your database and userID created before the Zen Cart® installer can continue past this screen.

Other information on this screen:
- At this time, MySQL is the primary operational database type.
  Future releases may support other database types.
- We recommend that you store your Database Sessions in your database for security purposes.

## System Setup Step

On the System Setup page you will need to complete the information we described in "Before Running the Installer" earlier in this document.

Indicate if you want to Enable SSL (the secure pages where required, in Login, Checkout, and optionally Admin areas) on your server.

If you do not have an SSL certificate yet, do not enable this feature now. It can be changed at a later date.

See the Enabling SSL Tutorial for detailed instructions.

## Store Setup Step

Now, complete the Store Information about your Shop.

Demo Data

If you would like to install the demo data, select "Yes".

We recommend that you install the demo data to familiarize yourself with many of the examples created that explain and demonstrate the vast number of features available in Zen Cart®.

You may also decide later, to set up a test site with the demo data AND a separate working site for your live data so that you have the ability to refer back to the demo data for help and to see examples of a feature.
- Except for "demo data", all of the information here can be (re)configured later in the Admin area of your shop.

After you click Save Store Settings, there will a brief delay as the database tables are created and the demo data is optionally loaded.

## Admin Setup Step

- Now, complete the Admin Information to set your Login name, Admin email address and password.
  1. Both the login name and password are case sensitive.
  2. Admin passwords must contain letters and numbers and be a minimum of 7 characters.
  3. The admin password you enter here IS ONLY TEMPORARY, and will be expired on first use, for your protection.

^^ Back to Top ^^

# Post Installation

## Configure.php Files

- You will now want to change the permissions on the configure.php files with chmod 644 or 444 depending on your server.
  - Sometimes setting 444 cannot be done via FTP, in which case, use your webhosting control panel or file manager to set the permissions level
- These are located in:
  - /catalog/includes/configure.php
  - /catalog/admin/includes/configure.php
- It would also be a good idea to download a copy of these files to your computer from the server as they have been setup and configured to your server specifications based on the Installation process.
- If you have any errors or problems, most of these can be corrected by minor adjustments to these two files.

## Delete the "zc_install" Directory

You must DELETE the /catalog/zc_install directory so that nobody can misuse the scripts in there to wipe out your store.

## Update Nginx Directives if Required

- The Zen Cart® Installer includes base directives equivalent to ".htaccess" rules to help secure your store.
  - These should be activated and Nignx reloaded before going live with the store

^^ Back to Top ^^

# Next Steps

To set up your online store, see the Zen Cart® Wiki entry outlining a Basic Checklist

Familiarize yourself with the Zen Cart® Developers Toolkit
- Located in your store Admin area, under "Tools".
- This will help you locate almost anything you want to customize in your Zen Cart® store!

Review the Zen Cart® Site Security Recommendations to be sure your site is not vulnerable to hackers
- The most up-to-date version of the security recommendations can be found on the Zen Cart® Wiki

^^ Back to Top ^^

# Help and Support

For additional help and support, visit the Zen Cart® FAQ and the Zen Cart® Support Forum.

Zen Cart® is derived from: Copyright 2003 osCommerce
This program is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY;
without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE
and is redistributable under Version 2 of the GNU General Public License.

This software is OSI Certified Open Source Software.
OSI Certified is a certification mark of the Open Source Initiative.

Copyright 2003 - 2018 Zen Ventures, LLC
Zen Cart®
www.zen-cart.com