Downloading CALF

The latest verison of CALF (as of the writing of this document is: 0.9.0

You should be able to download the most recent release of CALF at the following locations:

You should ALWAYS be able to find the latest version of CALF at the following locations: Installing/Configuring CALF

NOTE!!
These installation instructions assume a "standard" GNU/Linux webserver configuration which may or not match the machine you are trying to run CALF on. If you get CALF to install on a different configuration, write it up and we'll include it in the next version of this document.



Step 1: Install Pre-requisit Software
Before you go any further you should install the following software:



Step 2: Unpack CALF
Make or move into a the directory that your webserver has read/execute priveldges in (example: /var/www/) and unpack the calf archive with the command like:

% tar jxvf calf-current.tar.bz2



Step 3: Import Database Template (mysql only)
As mentioned two sections above, you're going to need database software to use CALF. You might have guessed it but you're also going to need some data. While I obviously can't give you the data you're looking for, or even the particular fields in that database you will need, I've included the database that is used on the demonstration at http://calf.democracygroups.org/demonstration/ and you're welcome to use this while you are getting everything worked out.

On most systems one can import the database but typing (you may need to specify your mysql root password):

% mysql -u root < calf-mysql_test_db.txt
This will create the database "calf_demo" and make it accessable by user "calf_demo" identified by the password "changme" (mispelled on purpose).

Continue on and DO NOT try to alter the database to fit your needs yet. Things will be easier if you follow these instructions step-by-step unless you really know what you are doing.



Step 4: Configure CALF
Calf's main configuration file is located at ./lib/perl5/Calf/Config.pm within the CALF distribution. You can change most of the behavior of CALF with this file. You will NEED to read through each option of this file and change it to fit your set-up. There are directory paths hard-coded into this file and it's unlikely that ANY CALF setup will work "out of the box."

NOTE!!
Config.pm is written in perl. You will not have to be a perl hacker to edit it but you should be aware that it is is in code and the introduction of errors that violate perl syntax will cause problems--even stop the software from running. If you are unfamiliar with perl, be VERY careful and file someone who does to check your changes is you run into problems.

I highly recommend changing the MySQL database password. You will need to do this in MySQL and in the configuration file. "changme" (yes I know it's mispelled) will be known by anyone who has looked at or installed CALF (or even read this file).

Pay attention to the fields you have added in the editable_fields hash as it will need to be reflected in the calf_data table of the database.



Step 5: Update the Database Structure
After you get CALF up and running, you're going to want to alter the calf_data table to include the fields that will be useful for your particular data. You will have to make these changes through mysql or a frontend to whichever database you are using. Any field mentioned in editable_fields should be a field in the calf_data table as well. Any field the calf_data table that is not in editable_fields will simply be ignored by CALF.

NOTE!!
A number of the fields in calf_data are used by calf. These fields are marked as such in the editable_fields hashref so please consult this file while removing fields.

Once the structure of the database matches the type of data you will be filling it with you can move on the to the next step. If you have data you want to import into the database from another source or database, now would be a good time to do this. If not, you should be able to add data to the database through CALF's "add item" interface although it would be slow for a large amount of data (hudreds or thousands of items).



Step 6: Edit HTML Templates
Of course, you'll probably want to configure calf so it displays different information (and in a different way) than the default demonstration version.

The templates are pure HTML with templating directives that tell the templating system, Template Toolkit how to render the pages. The basic premise is that the software behind CALF hands off the data in the form of list of variables to TT2 which reads in the HTML source, swaps the data in in a glorified fill-in-the-blanks process and outputs a piece of custom-built HTML. You'll want to aquaint yourself with TT2 directives and luckily, TT2 is qell documented. You can find the documentation at: http://www.template-toolkit.org/docs.html.

The templates included in the basic tarball are, well, basic. They were written by a programmer (myself) with next to no design, artistic, or HTML skills. Luckily, I knew THIS and designed the software so you will be able to change just about ANYTHING one would call look and feel without making any changes to the underlying code. Most of the templates are documented well (although some of the documentation has fallen out of date) so anyone with an introduction to TT2 should be able to do decently well.

The files you will want to edit include:



Step 7: Configure Webserver
To configure your webserver, you should edit the following passage to fit your set-up and then copy it into your httpd.conf (often in /etc/apache/httpd.conf):

<VirtualHost 192.168.0.1>
ServerName calf.mysite.org
DocumentRoot /var/www/calf
<Directory /var/www/calf>
         Options Indexes FollowSymLinks ExecCGI
         order allow,deny
         allow from all
         SetEnv PERL5LIB /var/www/calf/lib/perl5
</Directory>
<Directory ~ ^/var/www/calf/[lib|src|src-static].*>
         AllowOverride None
         Options None
         Order Deny,Allow
         Deny from all
</Directory>
</VirtualHost>
This assumes you have installed CALF in /var/www/calf and your site will be calf.myite.org. The important parts are the two <Directory%> directives which include the CALF configuration and utility modules into PERL's path and then block apache from serving these pages.

Add any other apache configuration options you feel will be necessary and then restart apache with the new configuration.

Point your web browser at your new site and hopefully the friendly calf page should pop up!

GOOD LUCK!