Installing and configuring WebCalendar

WebCalendar is a LAMP calendar application that can be configured as a single-user calendar, a multi-user calendar for groups of users, or as an event calendar viewable by visitors. It is not particularly intuitive for users or administrators, but it gets the job done.

These notes are a supplement to, not a replacement for, the installation and configuration instructions in the System Administrator’s Guide and are based on my experiences installing WebCalendar 1.2.0 locally on Mandriva Linux 2008.1 and remotely with an InMotion shared hosting account. Every distribution and every web host is different; YMMV and all that.

PREREQUISITES

• Latest stable version of WebCalendar
• A LAMP server, such as a web hosting account with MySQL and PHP
• A MySQL username, password, and database to use with WebCalendar

INSTALLATION
Place the WebCalendar tarball in the document root of the target computer and unpack it there. A new WebCalendar directory will be created; rename it to what you want it to be. Throughout the rest of these notes we shall assume a directory name of cal/.

To begin the installation wizard, point a web browser to http://example.com/cal/install/. Follow the installation instructions in the System Administrator’s Guide. As you proceed, you will be creating several passwords, usernames, and database names. Be sure to document this information.

In step 2 of the installation wizard (the database settings) enter your MySQL username, password, and database name in the WebCalendar installation wizard and press the “Test Settings” button. If all is well, press “Create”.

The basic installation is done. The backend’s default username is “admin”, and the password is “admin”. Its URI is of the form:

http://example.com/cal/login.php

The public calendar’s URI is of the form:

http://example.com/cal/

PATCHING THE INSTALLATION
If you are using WebCalendar 1.2.0 or older, then per these instructions open the file includes/functions.php and find this line (line 3052 or so):

$midnight = gmmktime ( – ( date ( ‘Z’, $item->getDateTimeTS () ) / 3600 ),
0, 0, $lt[4] + 1, $lt[3] + 1, $lt[5] );

Replace it with:

$midnight = gmmktime ( – ( date ( ‘Z’, $item->getDateTimeTS () ) / 3600 ),
0, 0, $lt[4] + 1, $lt[3] + 1, $lt[5] + 1900 );

SECURING THE INSTALLATION
Delete or rename the install/ directory. Do the same to the tools/ directory unless you will be using email reminders, and the ws/ directory unless you will be using web services. TODO: Link to a description of “web services” so the reader can make an informed decision.

Change permissions of all directories to 755, the file includes/settings.php to 400, and all other files to 644.

Some web hosts have issues that will not allow the permissions of settings.php to be so tightly set, in which case attempting to view or use the calendar will fail and the installer will be displayed. Experiment to find the tightest permissions that work; on one host that was 604. Ideally you should resolve this issue. See this discussion. Try using cgiwrap, suexec, or a similar method to avoid ownership and permissions problems. Failing this, contact your host’s support personnel.

TODO: Investigate if it is worthwhile to use .htaccess to block direct public access to parts or all of cal/. See this discussion. Instructions on how to do it with a separate .htaccess in every blocked directory are here, and how to do it using the docroot .htaccess, which is probably more elegant, is described here.

Exclude robots from traversing WebCalendar. I like to check site presentation using Browsershots, so I make an exception for their bot. My robots.txt thus reads in part:

User-agent: Browsershots   # Applies to browsershots.org's robot
Disallow:                  # Give browsershots full access
User-agent: *              # Applies to all other robots
Disallow: /cal/            # For internal use

Log in to WebCalendar at http://example.com/cal/ using the credentials user admin, password admin. Go to Settings – User Manager – Add New User and add at least one administrative account and one non-administrative account for normal use. For security reasons, delete the default administrator. Log out and log back in using the new administrative account.

Enable user access control (Settings – System Settings – User Access Control), then configure it (Settings – User Access Control). Select each user and non-user calendar in turn and configure which functions and calendars each user can access. TODO: Document user access controls and reasonable default values.

Perform a security audit (Reports – Security Audit) and follow the recommendations. See here for help with PHP settings.

Subscribe to WebCalendar’s security announcements via RSS or mail.

Use the non-administrative account for your day-to-day use of WebCalendar, and only use the administrative account for configuration tasks.

CONFIGURATION
As administrator, go to Settings – Preferences – Settings. Set the user’s time zone (not your server’s time zone) and any other desired change. Save. Repeat for user.

Insure that the WebCalendar directory and WebCalendar’s database are included in your site’s standard backup routine.

To prevent WebCalendar’s favicon from appearing on pages that use the minical, delete or replace cal/favicon.ico.

Each installation will probably require additional configuration. Document your per-installation changes to facilitate migration or disaster recovery. As with any LAMP application, customization should be applied to website CSS when possible rather than modifying WebCalendar code. This extends even to customization that is easily done within WebCalendar’s administration module, such as colors. In this way troubleshooting and upgrading WebCalendar is made much easier.

When modifications to WebCalendar code are necessary, best practice is to first make a copy of the file to be modified, rename it to indicate it to be the original, and make it read only. Then modify the file as desired, copiously commenting as you go. Thus for example if you need to modify includes/styles.php, first:

cp styles.php styles-original.php
chmod 444 styles-original.php

Again, this is best practice for modifying any application’s code.

TIPS AND TRICKS
If you get an error along the lines of:

Warning: unlink(/tmp/[random number].dat) [function.unlink]: Operation not permitted in [path to]/cal/includes/dbi4php.php on line 828.

then what you are seeing is a permissions problem with the database cache per this discussion. There are two solutions; take your pick:

• The easy way: In includes/settings.php, find the line “db_cachedir: /tmp” and comment it out with a hash. This deactivates database caching.
• The high performance way: Create a temp directory outside the Apache docroot, give it permissions of 777, and point the db_cachedir statement to it (see discussion cited above).

If WebCalendar stops appearing and is replaced with the installer, then there is a problem with the permissions or content of the file includes/settings.php. Compare it to a recent backup copy and edit or restore as needed. (You do have backups, don’t you?) You really shouldn’t leave the install/ directory sitting around after installing. Delete or rename it per the security instructions above.

I have two installations of WebCalendar for each client: one on a remote host for production use, and a second on my local workstation for development. For web development generally this is a good strategy, but I often wind up overwriting my remote settings.php with my local one, or vice versa. I haven’t found an elegant way to avoid this, but to protect myself I have copies of my settings.php, called settings-localhost.php and settings-domainname.php, both with permissions of 400, and both stored on both computers. And of course all those files are getting backed up daily on both computers. So while I still stupidly clobber settings.php occasionally, it is easy to recover.

REFERENCES
WebCalendar Home Page
Webcalendar Help Forum
Securing WebCalendar after installation
Discussion: Securing WebCalendar after installation

ALTERNATIVES
If WebCalendar doesn’t meed your needs, there are alternatives.