Installing Exponent

From ExponentCMS Docs

Installing Exponent

This page contains a guide to Installing Exponent CMS.

User Guides & Tutorials

This guide assumes some knowledge of Exponent CMS and the server side requirements used to configure it. If you are new to Exponent, then you may want to view the Tutorials category for step-by-step guides. If you have a specific issue you need help with see the Frequently Asked Questions page.

System Requirements

Exponent CMS is designed to work on Windows, Macintosh, Unix and Linux computers.

Requirements for Exponent

Before you can run Exponent CMS, there are four components you must have installed on your computer or web hosting environment:

1. Web Server — web hosting environments will have this installed and this can be added to most personal computers.
   • Apache — recommended. If you are setting up your own web hosting computer, visit the Apache Download page.
     • Must have mod-rewrite installed with the AllowOverrides directive set properly to enable search engine friendly URLs.
   • Lighttpd - known to work, but requires access to the server configuration to enable search engine friendly URLs.
   • IIS — may work, but will require third-party server add-ons to enable search engine friendly URLs.
2. PHP — this is the programming language in which Exponent CMS is written. PHP support should be included with most web hosting packages. For information about installing PHP, visit the PHP Download page.
   • For versions prior to 0.97
     • PHP 4.0.6 - minimum version required.
     • PHP 5+ - strongly recommended version.
   • For version 0.97 and later
     • PHP 5.2.1 - minimum required version.
     • PHP 5.2.6 - recommended for security.
3. Database — this is used to store and manage the the text and data content for your website. This is included with most advanced web hosting packages.
   • MySQL 4.1+ - minimum, MySQL 5.0+ recommended for performance and security. For information about installing MySQL visit the MySQL Download page.
   • PostGresSQL 7.0+ - minimum, PostGresSQL 8.0+ recommended for performance. — also supported but not as well tested. For information visit Postgres. CURRENTLY NOT SUPPORTED BY 0.97 ALPHA/BETA RELEASES
4. Exponent CMS — this is the Content Management Software.
   • Version 0.97.0 — the current development version can be installed, but should not be used in a live environment.
   • Version 0.96.6 — the current stable release is recommended for live environments.
   • Version 0.96.5 — the previous stable release is also in use, but should be upgraded.

For more info see: Wikipedia Web Server, Wikipedia PHP, Wikipedia Database, Wikipedia MySQL, Wikipedia PostgreSQL.

Additional Requirements for Exponent

These are software extensions and system settings for your hosting environment which Exponent needs for specific tasks. You do not need to have these to run Exponent, but will loose functionality and may experience some problems without them:

1. GD Graphics Library — this is used for imaging functions such as creating automatic thumbnails and Captcha tests. For more info see GD Graphics Library website.
   • Version 2.0.x+ — recommended for sharper and crisper thumbnails.
   • Version 1.0.x_+ — minimum required.
2. Zlib Support — this is used for uncompressing Tar and Zip archives when using the automatic Themes and Modules installers.
3. XML (Expat) Library Support — this gives you access to web services extensions which some Exponent modules use.
4. Safe Mode Disabled — Exponent works best when Safe Mode is Disabled. Having Safe Mode Enabled is a security measure present in some Shared Hosting Environments which limits PHP scripts from including or modifying files that are not owned by that script's owner. If you decide to run with Safe Mode Enabled, make sure that ALL files included in the Exponent package are owned by the same system user.
5. Open BaseDir Disabled — Exponent works best when Open BaseDir is Disabled and it may cause severe problems if this is not the case. Having Open BaseDir Enabled is a security measure present in some Shared Hosting Environments which limits PHP scripts from dealing with files outside of a given directory. This may cause problems with some Exponent file operations, including the Multi-Site manager.
6. File Uploads Enabled — some web servers will have PHP uploads disabled or have problems processing uploaded files. Without this ability you will be unable to upload new code, patches, images or resources.
7. Temporary File Creation — Exponent needs to create temporary files to accomplish many tasks. This is possible with most web hosting packages. This error may be caused by having incorrect File Permissions on the /tmp/ folder.

For more info see: Wikipedia GD Graphics Library, Wikipedia Zlib, Wikipedia Expat XML, Wikipedia Safe Mode.

Downloading the Exponent Software

1. Go to the Exponent Downloads page and use the downloads link, or go directly to the Exponent Sourceforge Downloads page.
2. Go to the File Releases section and locate the Exponent version you want to install:
   • Most users should install the latest stable release 0.96.6 Stable (Bossanova).
   • Developers may wish to install 0.97.0 (Milkshake). This is a development version which is likely to be unstable. It should not be deployed on a live site.
3. Download the Exponent archive which suits your hosting environment:
   • Microsoft Exchange and Windows users should download the .zip archive exponent-0.96.6-GA20071003.zip.
   • Unix, Linux and Apple Macintosh users should download the tar.gz archive exponent-0.96.6-GA20071003.tar.gz.
4. Download any additional Add-on Modules and Patches you want to add to your Exponent installation. Make sure that the Release for any add-ons you download matches the version of Exponent you have installed, i.e 0.96.6 or 0.97. Modules not marked as compatible with your version may work but have not been tested for compatibility. For more info visit the Exponent Modules page or the Exponent Subsystems page.

Uploading and Extracting the Exponent Software

You now need to upload the Exponent Software to your webserver:

Uploading and Extracting Exponent using a Control Panel

If your web hosting Control Panel supports extracting archives then this is the simplest way to upload Exponent to your web server:

1. Upload the Exponent Software archive 0.96.6 Stable (Bossanova) to your web server.
2. Use your Control Panel to extract the archive in the desired location.
3. Move the files and folders to your HTML folder or to a sub-folder you want to run Exponent from.

Uploading and Extracting Exponent using FTP

1. Extract the Exponent Software archive 0.96.6 Stable (Bossanova) on your local computer.
2. FTP the folders and files to the desired location on your web server.
3. Be certain to upload the .htaccess file or SEF URLs will not work.
4. Change File Permissions as detailed below.

Uploading and Extracting Exponent using Unix Command Line

1. Upload the Exponent Software archive 0.96.6 Stable (Bossanova).tar.gz to your web server
2. Extract the archive using the command: tar -xzvpf exponent-VERSION.tar.gz
   • Note — the -p option will preserve file permissions, and is very important as Exponent requires certain files and directories to be writable by the web server, and the standard tar-based distributions have this permission information preset.
3. If you have root access to your webserver, you should also change ownership of the Exponent files to whatever user your webserver is running as. For example: chown -R apache:apache exponent-VERSION
   • Note — if you are unable to do this, you will have to adjust your file permissions in order to allow your webserver to write to certain directories.

Set Exponent File Permissions

If you have uploaded and extracted Exponent using your Control Panel then the file permissions should be set correctly. If you used FTP to manually upload the files and folders then you will likely need to change permissions as follows:

File Permissions for Exponent version 0.96.5

For Exponent 0.96.5 the following files and folders should have their permissions set to 755:

/conf/                    (folder)
/conf/config.php          (file)
/conf/profiles/           (folder)
/extensionuploads/        (folder)
/files/                   (folder, including sub-folders)
/install/                 (folder)
/modules/                 (folder)
/overrides.php            (file)
/tmp/                     (folder)
/views_c/                 (folder)

File Permissions for Exponent versions 0.96.6 and later

For Exponent 0.96.6 and later the following files and folders should have their permissions set to 775:

/conf/                    (folder)
/conf/config.php          (file, auto generated during install)
/conf/profiles/           (folder)
/extensionuploads/        (folder)
/files/                   (folder including sub-folders)
/install/                 (folder)
/modules/                 (folder)
/overrides.php            (file)
/tmp/                     (folder)
/tmp/views_c              (folder)

Permissions Note: On some web servers permissions may need to be set to 777 to run Exponent. This is a potential security risk and should be done only if absolutely necessary.

Creating the Exponent Database

The way you manage your site will depend on your web hosting environment, but you will usually be able to use your Control Panel, PhpMyAdmin or MySQL Administrator to create a database.

Using a Control Panel to create the MySQL Database

1. Login to your web hosting Control Panel.
2. Load the MySQL Databases Manager section.
3. Create a new Database called Exponent or some other descriptive name.
4. Create a new User and assign a Username and Password. Remember that the stronger the password the more secure your site will be!
5. Add the User to the Database enabling them with All Privileges.

For more info see the documentation for your Control Panel cPanel Documentation, DirectAdmin Site-Helper, Ensim Pro, H-Sphere Documentation, Plesk Documentation, or contact your Web Hosting provider.

Using PhpMyAdmin to create the MySQL Database

1. Login to PhpMyAdmin.
2. Type your database name Exponent or some other name into the Create new database box.
3. Set the database type to ASCI [NOTE: UNSURE OF THIS].
4. Click Create to initialise the database.

For more info see PhpMyAdmin Documentation.

Using MySQL Administrator to create the MySQL Database

1. Launch MySQL Administrator.
2. Connect (login) to your MySQL databases using your Username and Password.
3. Click on the Catalogs tab to load a list of your existing tables.
4. Click on the + (plus) button to add a new schema.
5. Give the schema a name such as Exponent.

For more info see MySQL Administrator.

Using the Exponent Install Wizard

The web-based Exponent Intstall Wizard should now be used to complete the installation.

1. Use your web browser to navigate to the Exponent Install folder of your website:
   • www.yoursite.com/install/index.php
   • www.yoursite.com/exponent/install/index.php
2. Use the drop-down menu to select your Language then click Set Language.
3. Click on the New Installation link.
   • If you see an Unable to write message on the top left of the page then you need to check your File Permissions before moving on.
   • If you are upgrading Exponent see the Exponent Upgrade guide.
4. Review the Sanity Checks to ensure that everything is passed as ok
   • Ensure that your File and Directory Permissions are set correctly
   • Ensure that the Other Tests indicate your web hosting environment is compatible with Exponent.
5. Click on the Configure Database Settings link once all the Sanity Checks have been passed.
6. Input the Database Settings:
   • Backend — should usually be set to MySQL Database Backend but if necessary you can use a PostGreSQL Database Backend instead.
   • Address — the default setting localhost should work for most users, but if your Hosting Provider runs their database software on a different server, then you should enter this address here. It should be either an an IP address http://192.256.3.4 or a domain name http://mysql.example.com/userABC/.
   • Port — the default port 3306 should work for most users but if your database is on another computer you may need to use a different port number.
   • Database Name — input the Name of the database you created for Exponent, usually Exponent.
   • Database User — input the Username you created to access this database.
   • Database Password — input the Password for the User.
   • Table Prefix — the default prefix exponent should work for most users, but if you are using a shared database for multiple Exponent installations you may need to differentiate it. Note that the Install Wizard will add an underscore (_) to the table prefix do don't add this yourself.
   • Example Content — most users should leave this box ticked to include a set of commonly used Exponent modules and sample content with their installation.
7. Once you've verified your settings are correct, click the Test Settings button.
   • If you get a Connecting: Failed... message then something in your Database Configuration was incorrect. Click on the Edit Your Database Settings link and repeat the steps above to fix the problem.
8. Click on the Create an Administrator link to create the Super Administrator for your website.
   • Username — set the Username you will use this to login to your website. To ensure the security of your website, DO NOT leave this as the default admin! Note: Once you've set the username of the Super Administrator, it can't be changed so make sure to use something memorable but secure.
   • Password — set a Password for this account. Remember that the stronger your password the more secure your website will be. DO NOT leave this as the default admin!
   • Personal Details — set your personal details and valid email address which the system can use to contact you.
9. Click the Continue button.
10. You should now see an Installation Complete message. Review any notices displayed here and take all necessary action recommended to secure your site.
11. Now visit your website. Note if you did not install the Sample Content and need to login to your Exponent website use the url:
    • www.yoursite.com/login.php
    • www.yoursite.com/exponent/login.php

Troubleshooting

Installing Exponent in a Subdirectory

If you installed Exponent in a sub-folder of your website then in some hosting environments this can cause a problem which will lead to a Content Not Found error. This is due to the Exponent index.php script reverting to the root html directory of your website.

If you encountered this problem then you need to add the Path to your exponent installation:

1. Open the file /yourexponentfolder/overrides.php in a code or text editor:
2. Locate the Path statement:

   define('PATH_RELATIVE','/');

3. Change to:

   define('PATH_RELATIVE','/yourexponentfolder/');

4. Save your changes then visit your website.

Getting Started Resources

• www.exponentcms.org
• About Exponent
• Exponent Download
• Exponent Download SourceForge
• Download Themes
• Download Modules
• Download Language Packs
• Installation Tutorial
• Upgrade Tutorial