Installing FastFrame

You can obtain the latest FastFrame, in either .tar.gz format or .zip format, from: http://www.codejanitor.com/download/fastframe

Bleeding-edge development versions of FastFrame and its applications are available via SVN at http://svn.codejanitor.com/

FastFrame 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 FastFrame, install it directly under the root of your web server’s document tree.

Since FastFrame 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 webserver’s default document root of /usr/local/apache/htdocs, you would type:

cd /usr/local/apache/htdocs
tar zxvf /path/to/FastFrame-X.X.tar.gz
mv FastFrame-X.X FastFrame

If you downloaded FastFrame in .zip format then you would do the following:

cd /usr/local/apache/htdocs
unzip /path/to/FastFrame-X.X.zip
mv FastFrame-X.X FastFrame

and would then find FastFrame at the URL

http://your-server/FastFrame/

FastFrame requires the following webserver settings. Examples shown are for Apache; other webservers’ configurations will differ.

• PHP interpretation for files matching “*.php”

  AddType application/x-httpd-php .php

• “index.php” as an index file (brought up when a user requests a URL for a directory)

  DirectoryIndex index.php

All of the FastFrame applications require a database in which to store data. Currently MySQL is the only supported database. This means you will need to build PHP with MySQL support. After installing MySQL on your server, you will need to create a database and a database user. If you have a database administration tool installed on your server, such as phpMyAdmin, creating a user and a database will be a simple matter via the Priveleges section. Otherwise you will need to use the mysql command line client and execute the following queries:

CREATE DATABASE fastframe;
GRANT USAGE ON *.* TO "fastframe"@"localhost" IDENTIFIED BY "a_password_you_choose";
GRANT ALL PRIVILEGES ON fastframe.* TO "fastframe"@"localhost";
FLUSH PRIVILEGES;

Take note of the password you choose, you will need to put it into the conf.php file later.

To configure FastFrame, change to the config/ directory of the installed distribution, and make copies of all of the configuration “dist” files without the “dist” suffix:

cd config/
for foo in *.dist; do cp $foo `basename $foo .dist`; done

Or if you are installing FastFrame on a Windows system:

cd config
copy *.dist *.

Note: All of the below files live in the config/ directory of your FastFrame installation.

Open up the conf.php file in your favorite text editor. Most of the defaults are sensible and you will not need to change them for a basic installation. However, you will likely want to browse through them to see what sort of customizations you can implement for your particular needs.

The most important settings are at the top of the file, and you will definitely need to change at least the following settings:

1. The fastframe database username and password need to be changed to what you set them as in the creating a database section.
2. The web_root needs to be changed if you named the FastFrame folder anything other than FastFrame.

This file controls which applications are installed and visible on your system. By default the default applications (Login, Profile, and Permissions) are enabled so you don’t need to do anything in this file. However, every time you install any new application you will need to enable it by opening up this file, finding the application in the file, and changing the status to enabled.

Additional, powerful, customizations are also possible in this file.

• Each application can have a hostnames parameter. For example, if you set it to checkout.example.com for the checkout application then when a user arrives at FastFrame via checkout.example.com they will be automatically sent to the checkout application after logging in.
• The profile parameter enables you to have one instance of an application act as two separate installations. For example if you wanted to have two installation of checkout, one for department A and another for department B you would put something like the following in the apps.php file:

   $apps['departmentA_checkout'] = array(
       'name'              => _('Department A Check Out'),
       'status'            => 'enabled',
       'app_dir'           => 'checkout',
       'profile'           => 'departmentA',
       'hostnames'         => array('depta.example.com', 'depta'),
   );
   $apps['departmentB_checkout'] = array(
       'name'              => _('Department B Check Out'),
       'status'            => 'enabled',
       'app_dir'           => 'checkout',
       'profile'           => 'departmentB',
       'hostnames'         => array('deptb.example.com', 'deptb'),
   );

  Note that you would now to copy checkout’s conf.php and menu.php file into checkout/config/departmentA and checkout/config/departmentB. You could then customize each one.

This file allows you to “hook” into FastFrame applications so you can customize them to your needs. For example, you could hook into the login process so that you give all users a certain set of permissions when they log in. Look in the hooks.php file for more details on enabling the different hooks.

This file has a list of the different languages available in FastFrame. It doesn’t need to be edited unless you are adding a new translation.

The cache/ directory contains compiled templates and other cached files while the data/ directory contains uploaded files. Both directories must be writable by the webserver in order FastFrame to work. One way to do this is:

chmod 777 cache/ data/

• HtAccess
  
  Many of the directories (such as the cache/ and data/) directories come with .htaccess files in them that prevent the directory contents from being listed. This prevents malicious users trying to browse through files they shouldn’t. However, in order for the .htaccess files to work you need to have HtAccess enabled on your webserver. You can test if it is working browsing to yourserver.example.com/FastFrame/data/ If you get an access forbidden error then it is working. If the directory contents are listed then you need to edit your Apache conf file and change the Allow Override directive to allow Limit.

• Passwords
  
  Some of FastFrame’s configuration files contain passwords which local users could use to access your database. It is recommended to ensure that at least the FastFrame configuration files (in config/) are not readable to system users. There are .htaccess files restricting access to directories that do not need to be accessed directly; before relying on those, ensure that your webserver supports .htaccess and is configured to use them, and that the files in those directories are in fact inaccessible via the browser.
  
  An additional approach is to make FastFrame’s configuration files owned by the user ‘root’ and by a group which only the webserver user belongs to, and then making them readable only to owner and group. For example, if your webserver runs as www.www, do as follows:

  chown root.www config/*
  chmod 0440 config/*

• 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 onlyreadable and writeable by your webserver.

Once you have configured your webserver, PHP, and FastFrame, bring up the included test page in your Web browser to ensure that all necessary prerequisites have been met. If you installed FastFrame as described above, the URL to the test page would be

http://your-server/FastFrame/test.php

This page will check that your PHP and PEAR versions are acceptably recent, that all required module capabilities are present, that your database connection works, and that sessions work.

Security Note: Because the test page contains lots of information about your PHP setup and makes a connection to your database you should disable the page after using it to ensure it can no longer be accessed. One way to do this would be:

chmod 000 test.php

Now that FastFrame is up and running, you need to configure the applications you wish to use. The following base applications are included with your FastFrame download:

• Login
• Profile
• Permissions

These applications come enabled in the apps.php file, but you still need to configure them and set up the database tables, so you’ll want to the application installation page.

A list of other available applications can be found on the applications page.