osCommerce Documentation

Template Installation

Technical Requirements

osCommerce Online Merchant can be installed on any PHP enabled web server that can connect to a MySQL database. This includes shared servers, dedicated servers, and local installations running on Linux, Unix, BSD, Mac OS X, and Microsoft Windows operating systems.

Web Server

The web server must support PHP either as a module or allow execution of CGI scripts. For performance reasons FastCGI is recommended over CGI.


The following PHP options are recommended to be set in the php.ini configuration file:

When you've completed the preparations steps you can proceed to the osCommerce installation.

register_globals Off
magic_quotes_gpc Off
file_uploads On
session.auto_start Off
session.use_trans_sid Off

The following PHP extensions are mandatory:


The following PHP extensions are recommended:

GD Image processing module.
cURL Network communication library.
OpenSSL Encryption library.

MySQL Database Server

The minimum MySQL version required is v3.23. It is recommended to use the latest MySQL 4 or MySQL 5 version on the database server. The following MySQL storage engines are supported:

MyISAM Default storage engine.

Pre-Installation Steps

osCommerce Online Merchant is a web based solution that needs its relevant files to exist on the web server. The files can be copied to the web server by extracting the download package on your computer and uploading its contents to the web server via FTP, or by copying the download package to the web server directly and extracting its contents there.

Copying the Files to the Web Server

The contents of the download package need to be copied to the public HTML directory the web server is serving from.

  • /home/shinyredapples/public_html/
  • /srv/www/htdocs/
  • /usr/local/htdocs/
  • /var/www/vhosts/yourwebsite.com/httpdocs/

The contents of the download package once extracted is:

  • catalog (directory)
  • community_docs.pdf
  • documentation.pdf
  • extras (directory)
  • upgrade.html

Using FTP to Copy the Download Package Contents to the Web Server

The download package of osCommerce Online Merchant should be saved and extracted on your computer to reveal its contents. The catalog directory must be copied to the public HTML directory on the web server.

This can be achieved on most FTP clients by dragging the catalog directory from your local file browser panel to the remote panel listing the files on the web server.

Feel free to check out the following tutorial on how to upload files to a server.

All PHP files must be uploaded in ASCII mode (not in Binary mode).

File Permissions

The following files need to be writable by the web server.

Files Web Server Writable

Feel free to check out osCommerce. Uploading files and changing permissions tutorial.

The catalog/includes/configure.php and catalog/admin/includes/configure.php files must have their web server writable permission removed after the installation procedure has completed successfully. This is described in the Post-Installation Steps chapter.

Please consult with your hosting provider for the correct permission flag to allow the web server to write to those files. This is commonly defined with a permission flag of 755.

In some cases a world write permission flag of 777 can be used but may lead to an insecure installation of osCommerce Online Merchant.

Changing the file permissions can be performed by most FTP clients or directly on the web server.

Using FTP/cPanel file manager to Change File Permissions

Most FTP clients are capable of changing file permissions on the web server. This is commonly performed by right-clicking on the file and selecting "Properties" or "Attributes" on the context menu.

The file permissions can be changed by allowing all users to read, write, and execute the file, or by manually entering the world readable and world writable flag of 777.

Feel free to check out the following tutorial on how to manage file/folders permissions using FTP manager or cPanel filemanager.


A MySQL database on the web server or database server is required for the installation procedure to successfully import the database table structure and required data settings.

Feel free to check out the following tutorials on creating a database using cPanel and creating a database with GoDaddy.

Web Server and Database Server Details

The following web server and database server details are required during the installation procedure. Please consult your hosting provider if these details are not known.

Web Server Details

Setting Description Possible Value
Server Address The web address to the online store. http://www.yourwebsite.com/catalog/
Root Directory The directory where the online store is installed on the web server. /home/yourwebsite/public_html/catalog/

Database Server Details

Setting Description Possible Value
Server Address The address of the database server in the form of a hostname or IP address. localhost
Username The username used to connect to the database server. oscommerce_user
Password The password that is used together with the username to connect to the database server. securepassword
Database Name The name of the database to hold the data in. oscommerce

Please review the Pre-Installation Steps chapter before continuing with the installation procedure.

Installation Procedure

The web based installation procedure configures the online store and imports the configuration data into th5e database. This is necessary to create a fully functional online store and to create an administrator that administrates the online store through the Administration Tool.

The configuration values provided by default are safe to use but may need to be changed depending on the environment of the web server.

  1. Installing a New Online Store
  2. Welcome Page
  3. Database Server
  4. Web Server
  5. Online Store Settings
  6. Finished!

Installing a New Online Store

The web based installation procedure is automatically started when accessing the online store through a web browser. This can be achieved by entering the WWW address of osCommerce Online Merchant installation in your browser.

For example:


osCommerce Online Merchant automatically detects if the installation has already been completed and redirects to the installation procedure if it has not yet been performed.

Feel free to check out the tutorial on final steps of installation.

Welcome Page

The first step is the welcome page which displays the current recommended configuration settings for PHP:

Welcome Page

It is recommended to update a PHP configuration value, or to install and activate a PHP extension, if it is marked against the recommended setting.

When making PHP configuration changes or when installing and activating a PHP extension, the web server service needs to be restarted for the changes to take effect. Once restarted, refreshing the welcome installation page and viewing the Server Capabilities listing can confirm if the PHP configuration changes have taken place and if it meets the recommended settings.

Database Server

The second step sets the database connection parameters to successfully connect to the database server, to import the database table structure, and to import required data:

Database Server

The installation procedure verifies the values entered before proceeding to the next step. If there is a problem connecting to the database server, an error message is shown similar to the message shown in the screenshot below:

Database Server

Make sure the correct username, password, and database name are listed.

Web Server

The third step sets the web server parameters to successfully serve the online store to users:

Web Server
Online Store Settings

The fourth step sets the store owner and administrator settings for the online store:

It is important to keep note of the administrator username and password as these are used to login and to access the Administration Tool.

Online Store Settings

Additional administrators can be created in the Administration Tool after the installation procedure has been successfully completed.


The last step in the installation procedure stores the database server and web server parameters to the configuration file on the web server. On successfully saving the configuration file, the installation procedure is finalized and the online store is ready to be used.

It is important to keep note of the administrator username and password as these are used to login and to access the Administration Tool.


Post-Installation Steps

Upon successful installation of osCommerce Online Merchant, the following steps need to be performed to secure the installation of the online store.

Remove Installation Files

The catalog/install directory must be removed from the web server otherwise a user could use the installation procedure and reconfigure the online store to use another database server.

Reset File and Directory Permissions

Configuration Files

The file permissions on catalog/includes/configure.php and catalog/admin/includes/configure.php must be set to deny write access by the web server service. This is commonly performed by setting the permission flag to a read only value of 644 or 444 depending on your server.

Writable Directories

The following directories must be set to allow the web server service to write to for the Administration Tool to function properly. This is commonly performed by setting the permission flags to a world-writable value of 777.

Directories Web Server Writable
catalog/cache (create this folder)

Extra Protection for the Administration Tool

The Administration Tool is secured by its own login routine but is still publicly accessible. It is recommended to further protect the Administration Tool by setting a htaccess password on the catalog/admin directory.

If no extra protection is set for the Administration Tool, it is recommended to move the catalog/admin/backups directory outside the public html directory otherwise public access to the backup files would be possible. The location of the backup directory must be correctly defined in catalog/includes/configure.php.

Feel free to check out the following tutorial on how to secure your osCommerce store.