****** NOTICE ****** You should backup your production phpESP database before upgrading to this release. We are now using ADODB and have made significant changes to the database API which may cause unknown data corruption. Also if you are upgrading mySQL to version 4.1 or above, on an existing phpESP installation you need to read the UPDATING document in this directory, especially the UPDATING DATABASE section. ****** NOTICE ****** ================= INSTALLING PHPESP ================= This document contains instructions for installing phpESP on your system. OBTAINING PHPESP ---------------- phpESP can be obtained from the phpESP web site, at http://phpesp.sourceforge.net/ The most current release version and the most current development version are listed on the main page. Older releases are available from the "Files" section of the Source Forge project page. All distribution files can be unpacked using tar+gunzip (see INSTALLING PHPESP, below). Bleeding-edge development versions of phpESP are available via CVS; see the file docs/HACKING for information on accessing the phpESP CVS repository. PREREQUISITES ------------- The following prerequisites are REQUIRED for phpESP to function properly. 1. A web server that supports PHP. phpESP is developed under the Apache web server, which we recommend. Apache is available from http://httpd.apache.org/ phpESP may work under Microsoft IIS, but is known to have certain problems. 2. PHP 4.2.1 or above. PHP is the interpreted language in which phpESP is written. You can obtain PHP at http://www.php.net/ Follow the instructions in the PHP package to build PHP for your system. If you use Apache, be sure to build PHP as a library with the --with-apache or --with-apxs options to ./configure. The following PHP options are REQUIRED by phpESP (listed with their own prerequisites and configure options). In many cases, the required libraries and tools can be obtained as packages from your operating system vendor. a. MySQL support. (--with-mysql) phpESP uses a MySQL database to store survey information, responses to surveys, and user information. Information on obtaining MySQL is available at http://www.mysql.com/ (Future versions may allow the use of any database supported by the PEAR database abstraction class.) The following PHP options are RECOMMENDED to enable advanced features in phpESP: a. Gettext support. (--with-gettext) Gettext is the GNU Translation Project's localization library. phpESP uses gettext to provide local translations of text displayed by the designer interface. Information on obtaining the gettext package is available at http://www.gnu.org/software/gettext/gettext.html (See also note below on configuring translations.) 3. Additional PEAR Modules PEAR is short for "PHP Extension and Application Repository". The goal of PEAR is to provide a means of distributing reusable code. For more information, see http://pear.php.net/ At this time, phpESP does not use any PEAR modules. Future versions of phpESP will take advantage of PEAR. INSTALLING PHPESP ----------------- phpESP is written in PHP, and must be installed in a web-accessible directory. The precise location of this directory will differ from system to system. If you have no idea where you should be installing phpESP, install it directly under the root of your web server's document tree. Since phpESP is written in PHP, there is no compilation necessary; simply expand the distribution where you want it to reside and rename the root directory of the distribution to whatever you wish to appear in the URL. For example, with the Apache web server's default document root of '/usr/local/apache/htdocs', you would type: cd /usr/local/apache/htdocs tar zxvf /path/to/phpESP-1.6.tar.gz mv phpESP-1.6 phpESP and you would then find phpESP at the URL http://your-server/phpESP/ Now, before you can use this URL, please read the next section about configuring phpESP. CONFIGURING PHPESP ------------------ 1. Configuring the web server phpESP requires the following web server settings. Examples shown are for Apache; other web servers' configurations will differ. a. PHP interpretation for files matching "*.php" AddType application/x-httpd-php .php Note: The above instructions may not work if you have specified PHP as an output filter with SetOutputFilter directive in Apache 2.x versions. In particular, RedHat 8.0 Apache 2.x RPMS have the output filter set, and MUST NOT have the above AddType directive added. b. "index.php" as an index file (brought up when a user requests a URL for a directory) DirectoryIndex index.php 2. Creating databases If you are upgrading an existing version of phpESP please read "docs/UPDATING" for instructions on updating your database. a. Database and User The preferred method is that you create the database and user for phpESP on your own. This can easily be done with a tool like phpMyAdmin. Alternatively, look at the "scripts/db/mysql5.x_create.sql" (or 4.x if you still have an older mysql) file. This script, when run as the root user in mysql, will create a database and user for phpESP. Be sure to change the default password, "phpesp", to something else before executing the script! (Remember to use this password when you configure phpESP in the next step.) b. Tables and Data Once a database and user have been created for phpESP, go to the configured url, eg. http://your-server/phpESP/, the creation of tables and initial data is all web based. The default user name is "root" and has a password of "esp". You should login and change this password immediately after you configure phpESP. This user name and password are for logging into phpESP, do not confuse them with the database user name and password. 3. Configuring phpESP To configure phpESP, change to the admin/ directory of the installed distribution, and create "phpESP.ini.php". Most users will only have to change a few settings in this file. The most common changes are to the 'base_url', and to the database username and password ('db_user' and 'db_pass'). The defaults for this file can be found "phpESP.ini.php.default", so copy only the things you need to change. Also a file "phpESP.ini.php.fixed" exists, containing values you should never touch. The sequence is this: require (phpESP.ini.php.default); ==> defaults, gets overwritten with every new release require (phpESP.ini.php); ==> your own values, never gets overwritten require (phpESP.ini.php.fixed); ==> fixed parts, you can change these, but they get overwritten with every new release Note for international users: phpESP uses GNU gettext to provide local translations of text displayed by applications; the translations are found in the locale/ directory. If a translation is not yet available for your locale (and you wish to create one), or if you are having trouble using a provided translation, please see the "docs/TRANSLATIONS" file for instructions. 4. Securing phpESP a. Passwords phpESP's configuration file contains passwords which local users could use to access your database. It is recommended to ensure that at least the phpESP configuration files (admin/phpESP.ini.php*) are not readable to system users. An additional approach is to make phpESP's configuration file owned by the user 'root' and by a group which only the web server user belongs to, and then making it readable only to owner and group. For example, if your web server runs as www.www, do as follows: chown root.www admin/phpESP.ini.php.fixed chmod 0440 admin/phpESP.ini.php.fixed chown root.www admin/phpESP.ini.php.default chmod 0440 admin/phpESP.ini.php.default chown root.www admin/phpESP.ini.php chmod 0440 admin/phpESP.ini.php b. Sessions Session data -- including hashed versions of your users' passwords, in some applications -- may not be stored as securely as necessary. If you are using file-based PHP sessions (which are the default), be sure that session files are not being written into /tmp with permissions that allow other users to read them. Ideally, change the 'session.save_path' setting in php.ini to a directory only readable and writeable by your web server. Additionally, if phpESP is deployed at a hosting service that uses a server farm you may have problems with sessions. If all servers do not share a common 'session.save_path', sessions will break. The solution to this problem is to use the php function session_save_path(), to change the path to a shared location. Please make use of one of the support channels (below) if you encounter this problem. 5. Testing phpESP Once you have configured your web server, PHP, and phpESP, bring up the included test page in your Web browser to ensure that all necessary prerequisites have been met. If you installed phpESP as described above, the URL to the test page would be http://your-server/phpESP/admin/test.php Check that your PHP and PEAR versions are acceptably recent, and that all required module capabilities are present. Then note the "Session counter: 1" line under "PHP Sessions", and reload the page. The session counter should increment. OBTAINING SUPPORT ----------------- If you encounter problems with phpESP, help is available! The phpESP Frequently Asked Questions List (FAQ), available on the Web at http://phpesp.sourceforge.net/docs/faq.html A few mailing lists are run for phpESP. Information, archives, and subscription information can be found at http://phpesp.sourceforge.net/ Finally, phpESP developers, contributors and users also make occasional appearances on IRC, on the channel #phpesp on freenode. (irc.freenode.net). Please keep in mind that phpESP is free software written by volunteers. Thanks for using phpESP! The phpESP team ---- $Id$ ------------------------------------------------------------------------ This document was obtained from the Horde project, and modified for phpESP. We would like to thank the Horde project for providing such clean documentation. You may learn more about the Horde project at http://www.horde.org/ ------------------------------------------------------------------------