Contents:

• Download and Installation Instructions
• Frequently Asked Questions
• Important Notes
• Democracy Groups Documentation

Downloading CALF

The latest version 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:

• calf-0.9.0.tar.gz
• calf-0.9.0.tar.bz2

• download/
• calf-current.tar.bz2

NOTE!!
These installation instructions assume a "standard" GNU/Linux web server 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.

• A web server capable of running CGI scripts (apache is assumed);
• Perl (>=5.6 recommended) with all the default modules;
• The following perl modules:
  • Template Toolkit (>=2.0);
  • DBI (should come default with new version of perl);
• An MTA (Mail Transfer Agent) like Sendmail, Exim, or Postfix if you want to be able to send emails to list submitters when lists are rejected or approved. (optional but highly recommended)

Step 2: Unpack CALF
Make or move into a the directory that your web server has read/execute privileges 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

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 misspelled) 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 (hundreds 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 acquaint yourself with TT2 directives and luckily, TT2 is well 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:

• source HTML files in ./src/. These files are each called directly from the perl scripts. You can't just delete them.
• HTML template "libraries" in ./lib/templates/. These files are usually called by the INCLUDE or PROCESS templating directives. These include the headers, footer, menu, and other chunks of HTML. Also be sure to change the displaylistinfo template to modify the data in your database and the data you will want to display to users and how you want it rendered.
• static HTML in ./src-static/ for things like your "about" page and your "credits" or anything else you will only make infrequent changes to.

Step 7: Configure Webserver
To configure your web server, 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>

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!

Frequently Asked Questions

What other software do I need to install in order to run CALF?
CALF is flexible in that it won't tie you down to specific pieces software (IE a specific web server or a specific database). However, I've prepared installation instructions that will assume a "standard" configuration. It is worth noting that CALF was developed up and will run on a system using only free software! If you need help with configuration on alternate system, the mailing list is probably your best bet. Read the installation instructions for more details and help. You'll need to install the following software before can run CALF:

• A web-server capable of running CGI scripts (apache is assumed);
• Perl (>=5.6 recommended) along with the default modules;
• The following perl modules:
  • Template Toolkit (>=2.0);
  • DBI (should come default with new version of perl);
• An MTA (Mail Transfer Agent) like Sendmail, Exim, or Postfix if you want to be able to send emails to list submitters when lists are rejected or approved.

Will CALF run under Windows?
I've not heard that anyone has tried but as far as I know it should be totally possible. All of the required software listed above is available for Windows and perl programs are, last I heard, totally cross-platform. If you've managed to pull it off, email the list at calf-devel@lists.democracygroups.org and tell us as there are lots of us that I'm sure would like to hear about it.

What's with the name?
Yeah, I know. "Lister and Filer" is a stretch but there's a story. The modified version of CALF which runs the Democracy Groups was nicknamed GOLDEN before the project had a name set in stone. GOLDEN stood for the Grassroots Organizing List Database ENgine which is exactly what it is. However, when it came time to extract the core into a multi-use tool, this named proved too specific. In the interest of having a program named after a biblical reference to idolatry, I took the advice of a friend and named the new version CALF because GOLDEN CALF sounds neat enough and it was something I could talk about in the FAQ anyway.

How much does the software cost? | Can I use CALFon my site?
Nothing and Yes! CALF is free software. Read the license or or the Free Software Foundation's essay What is Free Software? if you're still confused.

I'm stuck and your FAQ doesn't help! Where do I go?
Your best bets are to join the mailing list at Mailing List or just send a message to it at calf-devel@lists.democracygroups.org and be sure to explain that you are not on the list so that they CC you in on the reply.

Important Notes

This release is not heavily tested...
This is the not the full version. You may follow the installation procedure perfectly and things don't work perfectly. If this is a prospect you don't think you can face, please come try again after CALF hits 1.0.

If you feel braver, GREAT. We're willing to walk people through their problems on the mailing list and help you get set up. If you can point out problems with the installation or with the tarball, we'll patch it up and upload a new one so no one else has to deal with the problems you do.

There is still Democracy Groups functionality waiting to be merged into CALF...
If you've visited the Democracy Groups website you've noticed that some major functionality, like the ability to search by area is not included in CALF. This is for a couple reasons: (a) I'm concerned about distributing the zip code file as part of the database because I'm not sure where Organizers' Collaborative and if there are license restrictions on it and (b) because it's the last part of Democracy Groups written and I haven't yet had a chance to abstract it into CALF.

As always, if you want to take this upon yourself to put this functionality into CALF, you can contact the development team and we can give you access to the relevant source code and help you solve the relevant copyright issues with the zip code file. It IS a pretty cool feature.

Democracy Groups Documentation

The following information pertains directly to the Democracy Groups site and not to CALF specifically. However, since Democracy Groups is powered by CALF, much of their documentation, especially the user and editor guidelines and documentation, is still very relevant. It also acts to fill some major gaps in the documentation that is distributed with CALF which is mostly geared toward installing, administering, and developing the software and not with using it.

• About Democracy Groups
• User Guide to Using Democracy Groups
• Democracy Groups Editors' Guide