Kalendus is written in Perl and uses several modules that may need to be installed. The DBI (database interface) and Msql-Mysql DBD (database driver) modules communicate with the MySQL database. These can be obtained from CPAN and installed according to the directions. These may already be installed, depending on your setup. The Time-modules set is used for all date calculations. These are all available from any CPAN mirror http://www.cpan.org/
These Perl modules are installed by downloading the latest .tar.gz file, extracting it, and running make. You normally need root/admin access to install them. If you do not have root/admin access, it is possible to install into a temporary directory using the PREFIX option and copy files to the Kalendus cgi-bin directory. For example, the latest version of Time-modules as of this writing is 100. After downloading the file, extract and install it:
tar -zxvf Time-modules-100.010301.tar.gz cd Time-modules-100.010301 perl Makefile.PL (or use 'perl Makefile.PL PREFIX=/tmp/foo') make make test make install
Kalendus uses MySQL as the backend database. I will not go into the installation of MySQL; see http://www.mysql.com/ for the downloads and documentation. MySQL was chosen because it is a freely available database, it is used by our web hosting organization (Gospelcom), and it is fairly efficient. The scripts could probably be modified to work with other SQL databases without too much difficulty. I will assume you have MySQL setup.
To set the MySQL server hostname, username, password, and database for Kalendus to use, edit the cgi-bin/config.pm file. It should be self explanitory. The Kalendus user needs select, insert, delete, and update priveleges. To give these priveleges (for MySQL 3.22.11 and beyond), use the mysql client to enter:
GRANT select, insert, delete, update ON calendar.* TO calendar@localhost IDENTIFIED BY 'password'
If you do not yet have a database in MySQL for Kalendus to use, create one using the mysql client:
CREATE DATABASE calendar
To create the necesary tables, use the SQL definitions in the tables.sql file. On UNIX, this can simply be redirected into the MySQL command line client. The username used to create the tables needs create privileges, and may be different than the username used by the Kalendus scripts.
mysql -h [mysql_server_host] -u [username] -p [database] < tables.sql
You may use any web server that allows execution of CGI scripts. However, I am familiar with Apache and will describe how to use it.
Kalendus has three directories: cgi-bin, which contains the CGI Perl scripts; images, which contains pre-done graphics for calendars and months; and doc, which contains the documentation. Install the cgi-bin directory where you want the scripts to be, and enable CGI execution in that directory. The Kalendus cgi-bin directory does not have to be named cgi-bin; at IVP it is named calendar. If you install the Kalendus cgi-bin directory in an existing CGI directory, it is often ScriptAliased and you do not need to change Apache's configuration. At IVP, Kalendus is installed outside our normal CGI directory, so I enable ExecCGI and add the CGI handler for Perl scripts. For instance, in the Apache config file 'access.conf':
<Directory /home/httpd/html/calendar/cgi-bin> Options ExecCGI </Directory>
Apache also needs to know what files to run as CGI scripts, rather than downloading. If the cgi-bin directory is ScriptAliased, that should suffice. Otherwise, add a handler for Perl scripts, which end in .pl, to the Apache config file 'srm.conf':
AddHandler cgi-script .pl
If you want password authentication, either the whole Kalendus cgi-bin directory can be password protected, so no unauthorized users can see your calendars, or just the cgi-bin/auth/ directory can be password authentication, so no unauthorized users can add or change events on your calendars. See the excellent tutorials on the Apache site for how to do this. An example configuration might be:
<Directory /home/httpd/html/calendar/cgi-bin> Options ExecCGI # # Only allow people in the 'calendar' group # AuthType Basic AuthName "Calendar" AuthUserFile /home/httpd/passwd AuthGroupFile /home/httpd/group require group calendar </Directory>
Install the images/ and doc/ directories where you want them. This location should be in your normal webspace, not in the CGI directory.
Reload the Apache server (e.g. using 'apachectl restart' or '/etc/init.d/httpd reload').
If everything is setup correctly, you can view the calendar using the month.pl script, e.g.: http://yourhost.domain.com/calendar/cgi-bin/month.pl. If something doesn't work, see the troubleshooting section below.
There are a number of items you may wish to configure in the Kalendus scripts. All configurable values can be set using the cgi-bin/auth/config.pl script. Use the same username for this script as for all the others; it asks for the username/password instead of getting it from the config.pm file as a security measure.
Once you have finished configuring Kalendus to your liking, you may want to change the HTML pages to fit in with your site design. See the HTML templates documentation.
A few common errors and possible causes that might occur when trying to access the Kalendus scripts online.
In debugging, it is very helpful to try running the month.pl Perl script from the command line. Just type control-D after running it to get it to run. Also check the Apache access and error logs, typically found in /var/log/httpd/access_log and error_log.
#!/usr/bin/perl which must be the Perl executable on
your system. Change the path in the scripts if necesary. Perl may
also not be able to find the modules it needs (see installing Perl
above). Try running the month.pl script from the command line or
look at the Apache error logs, to see if you can glean any
information that way.