Reason is a web content management system designed for educational institutions. It was created by the Web Services Group at Carleton College. The installation process outlined below assumes you have some basic skills with PHP, MySQL, and server administration.
We are eager to help you get Reason installed on your system. If you run into trouble or have any questions please do not hesitate to contact us at reason-support@lists.carleton.edu.
Reason requires the following packages:
Reason has been installed under Linux, Mac OS X, and Windows. Windows compatibility was new to Reason 4 Beta 6 and is still considered experimental.
When you unpack the Reason distribution you should place the 'reason_package' folder in a web accessible directory. Only certain portions actually need to be under the webroot, but for simplicity we're keeping everything there for now.
Reason requires that the reason_package directory be a part of the include_path. Typically this can be done in either the httpd.conf file (php_value include_path .:/path/to/your/reason_package/) or in your php.ini file (include_path = ".:/path/to/your/reason_package/").
The configuration details we use in production are listed in the PHP_configuration.txt file included alongside this document.
Your default php.ini file is probably fine as long as:
We recommend the following:
Reason will use libcurl and libtidy if installed. If these libraries are not a part of your PHP installation, you should make sure the command-line binaries for curl and tidy are available, and set the paths to these utilities in package_settings.php. Note that your version of tidy needs to support the show-body-only option (should be set to yes in your tidy.conf file).
Reason uses the error handler in carl_util and controls error reporting / display accordingly. The settings you specify in php.ini apply only to applications that do not use the error handler within carl_util. When setting up Reason, it can be useful to have "display_errors" turned on in case the error handler itself is not being properly loaded.
Reason can operate in an insecure mode that does not require an SSL certificate. If you choose to run Reason in an insecure setting (not recommended), you will need to set the HTTPS_AVAILABLE constant in the package_settings.php file to false. Otherwise, You will need to generate or purchase an SSL certificate.
Your web server must obey .htaccess files containing the directive types "Limit", "FileInfo", and "Options" are needed. To permit this you'll need an "AllowOverride Limit FileInfo Options" line either in an appropriate <VirtualHost> or <Directory> block.
Reason will work without modification to your httpd.conf file in many environments, but there are a number of customizations that a savvy administrator may want to make. For more information on Carleton's setup, consult server_configuration.txt in the same directory as this file.
You'll need to connect to MySQL to setup a database for Reason, and a database for Thor, Reason's form utility. You'll need to log into MySQL with a user who has privileges to create databases and grant privileges to other users. You can do these operations from the command line or using a tool such as phpMyAdmin.
Connect to your MySQL instance
Create a database for Reason:
Setup a username/password for Reason to connect to the database:
Next we are going to populate the Reason database with some basic information needed for an empty Reason instance. We can leave the Thor database empty, as Reason will automatically create the necessary tables the first time a form is created. There are many ways you could import the reason4_b5.sql file using phpMyAdmin or from within MySQL.
Here is one way to import the database from the command line:
Change into the directory that contains the file reason4_b7.sql. From within /reason_package:
The database connection information to connect to the databases you just created must be defined in a simple XML file. The location of this file can be specified by the DB_CREDENTIALS_FILEPATH constant in the reason_package/settings/package_settings.php file.
The location should not be web accessible as it will contain the account credentials for your database. It's also sensible to make it readable only by the account your web server runs under.
Create the file with information specific to your site, and set the DB_CREDENTIALS_FILEPATH to reference the location. We recommend using the connection names reason_connection and thor_connection, so that you don't need to change the values in the default settings files.
Here is the format for the credentials XML file:
<databases>
<database>
<connection_name>reason_connection</connection_name>
<db>reason</db>
<user>reason_user</user>
<password>some_password</password>
<host>your.mysql.hostname.or.ip.address</host>
</database>
<database>
<connection_name>thor_connection</connection_name>
<db>thor</db>
<user>reason_user</user>
<password>some_password</password>
<host>your.mysql.hostname.or.ip.address</host>
</database>
</databases>
To properly set up reason, you'll need to configure the following:
You can configure these files after installation:
We recommend copying the distributed settings to a backup folder so that you can revert and/or refer to them later.
The package_settings.php needs to be edited in order to setup paths specific to your instance of Reason. You can also setup the organization name, webmaster e-mail address, and other basic information in this file.
The following constants need to be verified/setup for Reason to function:
If reason sites are going to be placed behind areas that require http authentication, then the HTTP_CREDENTIALS_FILEPATH constant must be defined. The constant should reference a file outside the web tree which defines $http_authentication_username and $http_authentication_password. These variables are used by curl to access areas behind http authentication.
The reason_settings.php file is well-commented and should be configured according to your reason setup.
The following constants should be verified for accuracy - if they are incorrect Reason may not properly function:
Near the top of the file, an array specifies Reason developer e-mail and IP addresses. Set this up with your own local information, so that developers see onscreen warning, and are properly notified via e-mail of more serious errors. You will not see useful error messages until you customize this file with your own IP address. Please see the notes included in the file.
Defines the connection name in your specified in the XML credentials file for Thor connections. If you named the connection thor_connection in the XML credentials file you do not need to edit this file.
This file configures how emails are addressed when generated by Reason forms. The reply to email address defaults to the WEBMASTER_EMAIL_ADDRESS. You can change that entry with the TYR_REPLY_TO_EMAIL_ADDRESS in this file.
Reason has a built-in user system, but can also support authentication and directory lookups from external directory service systems. You can leave this file untouched to use the Reason user system for authentication and directory information. To implement your own system, see /reason_package/carl_util/dir_service/directory.php.
Reason includes a custom 404 error page. The 404 error page includes functionality which will redirect requests for resources that have moved to their new location. To take advantage of the 404 functionality, you must use a custom 404 error page, and have the following two choices.
If you choose not to make these changes you'll see your web server's default 404 page.
To keep the server happy, it is a good idea to setup nightly garbage collection of old objects. To schedule this job create a script in your /etc/cron.daily folder like the following:
#!/bin/sh
/path/to/bin/php /path/to/reason_package/reason_4.0/lib/core/scripts/db_maintenance/scripts/garbage_collector.php3 > /tmp/reason_garbage/web_garbage_dump.`date +\%Y\%m\%d`.txt
Note that you must create the folder /tmp/reason_garbage. In addition, make sure to substitute values specific to your site for the /path/to/ values.
Once everything is configured, run the Reason Setup script through your web browser. The script (reason_setup.php) is located in the reason_package directory.
The script will do some basic verification checks to see if reason is properly setup, and create an administrative user with username "admin" and a random password.
Write down the password!
The user created by the script has a unique name and will only be created once. For extra security, delete or move the script from the web tree after it has been run.
Once everything is configured the setup script will provide you with a link to sign in to the Reason administrative interface. Enjoy.
If your install is not going as planned, or you have questions about this installation information, please contact us at reason-support@lists.carleton.edu. Thank you for your interest in Reason.