LICENSE AGREEMENT Before installing Ensemble, refer to the license agreement document, ensemble_license.txt, in the top level directory of this distribution and online at https://atonal.ucdavis.edu/repos/public/ensemble/release/v1/ensemble_license.txt ENSEMBLE INSTALLATION INSTRUCTIONS - Updated 1/8/2010 Before you attempt to install Ensemble, please make sure that you have at least have the required components installed (MySQL and PHP) for the survey (QEI/QPI) portion. -------------------------------------------------------------------------------------------------- PREREQUISITES -------------------------------------------------------------------------------------------------- Operating Systems Ensemble has been deployed most commonly on Linux servers. The web survey (QEI/QPI) portion and MatRPC have been successfully deployed on OS X 10.6 (Snow Leopard), although they have not been tested or used extensively in this environment. Ensemble has not been deployed on a Windows server yet. However it should be possible to run the survey (QEI/QPI) on Windows, since the technologies it uses (PHP/MySQL) are not operating system dependent. MatRPC (see below) may need some modification to run in Windows. Web Server Currently, we use an Apache web server for Ensemble. If you install Ensemble on another web server, please let us know about your experience or any issues you encounter. A sample ensemble.conf file is included. It can be added to your Apache configuration directory (usually located in /etc/httpd/conf.d). This file contains various Apache directives for protecting Ensemble directories and requiring SSL connections to Ensemble. You will likely need to edit this file to suit your environment. PHP PHP provides dynamic web scripting capabilities to the Ensemble QEI and QPI. PHP can be installed on a variety of web server applications for Windows, Linux and OS X. The version of PHP that we currently use is 5.1.6. There are noteworthy differences between major versions of the PHP language, although most sub-versions of PHP 5 should be compatible with Ensemble. Many operating systems such as OS X and some distributions of Linux already include PHP packaged with the installation of the operating system. Installers for PHP can be found at http://us2.php.net/downloads.php If you are running PHP v. 5.2 or later, make sure that you have configured the date.timezone setting in php.ini (usually at /etc/php.ini). Valid timezone values can be found at http://php.net/manual/timezones.php. Here is an example: date.timezone = "America/Los_Angeles" If you do not set the timezone and are using PHP version >= 5.2.0, you will likely see a warning message in the Form Editor, and possibly other utilities. MySQL MySQL serves as the storage for Ensemble data. It is commonly interfaced with PHP for a variety of applications. We currently use MySQL version 5.0.45 and this is the recommended version for use with Ensemble. Sub-versions of MySQL 5.0 should be compatible with Ensemble, however. Downloads for MySQL can be found at http://dev.mysql.com/downloads/ Prerequisite Utilities Open a terminal window, since the installation process requires the running of scripts. The installation script (install.php) uses the PHP command-line interface. This should automatically be available with your installation of PHP. The command-line interface essentially allows you to process PHP scripts on the command-line instead of on the web server. In order to verify that it is working, type: >php -v This will give you the version number of the php command-line interpreter. If you receive an error message when calling php from the command line, the binary may not be in your path. More information on the PHP command-line interface can be found at http://us3.php.net/features.commandline -------------------------------------------------------------------------------------------------- RUNNING THE INSTALLER FOR THE WEB INTERFACES AND DATABASE -------------------------------------------------------------------------------------------------- This distribution is organized so that you can simply copy the entire Ensemble directory to a location under your web root where the Ensemble web interfaces (QPI/QEI) will reside. Then run the install script to install the MySQL schema and configure the Ensemble web interface. Private directory During the installation process, you will be prompted for a secondary directory where Ensemble will store "private" information such as the subject password and the encryption key for encrypting identifying subject data. It is recommended that the "private" directory NOT be located under the server's webroot. Before starting the installation, you may want to consider what path you would like to use for the "private" directory. We often use /var/www/private (which is usually not under the web root) or /var/private. Make sure that you are running the installation script as a user that has privileges to create this directory. In linux or OS X, if you have root access to your server, you can simply run the installation as the root user. Linux and OS X Once you have verified that PHP command-line interpreter is installed, type: >sh ./install.sh in the install directory. This shell script is simply one line of code that calls the install.php PHP script that processes the actual installation. Windows A batch file is not yet available, but you can run the PHP script by typing >php -f install.php on the command line. The installation script hasn't yet been tested on Windows and it might need minor modifications. -------------------------------------------------------------------------------------------------- INSTALL SCRIPT OPTIONS -------------------------------------------------------------------------------------------------- The installation script is divided into the six following sections. The "server configuration parameters" section will always run. However, you may bypass many of the sections if you are running the install script again for reconfiguration. If this is your first installation of Ensemble, it is highly recommended that you run each section. SERVER CONFIGURATION PARAMETERS Hostname or IP address of mysql server: If the MySQL server is on the computer where you are running this script, use localhost. If you have any database connection problems, make sure that MySQL sockets are correctly configured in php.ini, and my.cnf, which usually reside in the /etc directory. Name of the Ensemble database: You do not have to use the default name of "ensemble" for the database. Use a name that is appropriate for your environment. If you previously installed the schema, and are bypassing that section of the installation, make sure to enter the same database name. MYSQL SCHEMA INSTALLATION Install MySQL schema? (y/n): If you are running the install script for the first time, say "y". Otherwise, skip this if you have already installed the MySQL database and tables and are rerunning the script to reinstall the QEI/QPI PHP scripts. MYSQL USER CONFIGURATION This section will create the researcher and subject users and grant them the appropriate privileges to the Ensemble database. Make sure that you didn't bypass the MySQL Schema Installation when you run this section of the script. SUBJECT USER STORAGE This section stores the subject's username and password in the location that you specify. This is stored in the "private" directory referred to in the above text. Please make sure to specify a location on your server that you can easily restrict access to only system administrators and the web server application. It is further recommended that you specify a directory that is not publishable via the web (i.e. not under the web root directory). The information will be stored in a file called conn_subject.php in the directory that you specify. You may specify a directory that doesn't yet exist (as long as the parent directory exists). In this case, the script will create the directory. ENCRYPTION KEY This section creates a text file to store the encryption key (a phrase of any length). At least 16 characters is recommended, and it may include non-alphanumeric characters and spaces. The encryption key is used to encrypt identifying subject data (e.g. name and date of birth). Make sure to choose a path that is not under webroot. Using the same directory as conn_subject.php is recommended. It is very important that you not lose this encryption key. Back it up and make a printout! If the encryption key is lost, you will not be able to retrieve any identifying subject information stored in Ensemble. If you are re-running the installation script and have already saved an encryption key, you may specify an existing encryption key file and Ensemble will use it. QEI AND QPI CONFIGURATION You will be asked for several parameters that configure the QEI and QPI. These are stored in the variables_config.php file in the 'include' subdirectory of Ensemble. -------------------------------------------------------------------------------------------------- POST-INSTALLATION PROCEDURES -------------------------------------------------------------------------------------------------- You should restrict access to the "private" directory so that only administrator users and the webserver have access to it. On a linux server, restricting access to only the root user and apache user is sufficient. If you are running MatRPC, also grant access to the "matrpcuser" (explained in the matrpc installation process). Any users that need to retrieve identifying subject information with Matlab analysis scripts also need access to the "private" directory. All of this can easily be accomplished by creating a user group called "ensemble", and granting read access to the "private" directory by the "ensemble" group. You may then add the apache user, matprcuser, and any other normal users that need access, to the "ensemble" user group. -------------------------------------------------------------------------------------------------- MATRPC -------------------------------------------------------------------------------------------------- MatRPC allows the processing of Matlab scripts for use with Ensemble. An experiment can be configured to call a custom Matlab script using this interface for stimuli selection. MatRPC was programmed in C and uses POSIX threads. It has only been compiled on Linux and OS X although it may be possible to port it to other operating systems with little modification. If you wish to use MatRPC for stimulus selection, you will most likely want to compile the MySQL database connector (see below) so that your Matlab scripts can query the MySQL database. MatRPC is located in the MatRPC directory. Please see the README file in the MatRPC directory for details on compiling and running it. -------------------------------------------------------------------------------------------------- MATLAB -------------------------------------------------------------------------------------------------- We have a number of Matlab scripts for retrieving and analyzing Ensemble data. These scripts are publicly available via svn. In order to obtain our scripts via svn, type: svn co https://atonal.ucdavis.edu/repos/public/matlab/database This will check out the scripts to a directory called "database" in the current working directory. Note that most of these scripts will not work unless the MySQL database connector (below) is installed and in your matlab path. Make sure to add the database directory to the Matlab paths of any users that need to use these scripts. Note that if you create matrpcuser for running MatRPC (see MatRPC readme in the matrpc directory), you will need to add this directory to matrpcuser's Matlab path so that it can access these scripts. To add this directory to a user's path, simply open your startup.m file, located in /matlab/startup.m and add: path(path,); -------------------------------------------------------------------------------------------------- MYSQL DATABASE CONNECTOR -------------------------------------------------------------------------------------------------- This is a mex file through which database queries can be performed. It is available from the Matlab file exchange at: http://www.mathworks.com/matlabcentral/fileexchange/8663 Instructions on compiling can be found in the C++ source code comments. After compiling, simply copy (or move) the mysql.mexXXX and mysql.m files to a directory that is in your Matlab path (where mexXXX corresponds to the mex extension for your system architecture). mysql.m simply contains the help information for mysql.mexXXX Note that if you call "mysql" when your current working directory is the directory where these files are located, the call will default to mysql.m (which does nothing). The solution is to simply change your working directory.