WebCalendar Installation Instructions

Note: This document is being phased out in favor of the new WebCalendar System Administrator's Guide (which is not yet complete).

If upgrading, see upgrading notes below.

Requirements

You must have PHP and one of the following databases installed: For the database you choose, you must have its drivers built into PHP. For example, to use MySQL, PHP must be compiled with MySQL support (which is the default setting when installing PHP). See the PHP pages (www.php.net) for more information on setting up PHP.

No optional PHP packages (other than MySQL) are required for this application. However, PHP shoud be compiled with --enable-track-vars on some systems.

Make sure that magic_quotes_gpc in php.ini is turned on (otherwise, you will get database errors when entering quotation marks in HTML forms).

You can run PHP either as a CGI or an Apache module. You'll get better performance with PHP setup as a module. Not only will you not have to deal with the CGI performance hit, but you'll be able to use PHP's database connection pooling. Additionally, this application can use a form/cookie-based authentication or traditional HTTP authentication. For traditional HTTP authentication, PHP must be built as an Apache module.

If you are planning on using email reminders, you will need to build PHP as a CGI in order to run the send_reminders.php script. I would strongly recommend building a module-based PHP for your web server and then a second PHP build to create the CGI version.

File Unpacking

Unpack the calendar software in its own directory somewhere where your web server will find it. (See your web server docs for info.)

By default, WebCalendar should create its own directory when you unpack it. The new directory name will typically contain the version name (such as WebCalendar-0.9.35). You can rename this directory after unpacking the files if you prefer a directory name like calendar or webcalendar. Keep in mind that unless you remap the directory (via your web server's configuration settings), it will be part of the URL for the calendar.

Database Setup

You can place the calendar db tables in an existing database or create a new database with the following:
MySQL (from command line):
mysqladmin create intranet
(This will create a database named "intranet".)

Oracle (from within sqlplus):
CREATE TABLESPACE webcalendar DATAFILE 'webcalendar.dat' SIZE 10M AUTOEXTEND ON NEXT 10M MAXSIZE 40M;

PostgreSQL (from within psql):
create database webcalendar;
\c webcalendar
\i tables-postgres.sql
\q

Interbase (from within usql)
CREATE DATABASE 'WEBCAL.gdb';
(This will create a database named "WEBCAL.gdb")

You will want to setup a new user that defaults to this new tablesapce:

Oracle (from within sqlplus):
CREATE USER webcalendar IDENTIFIED BY webcal01 DEFAULT TABLESPACE webcalendar;
GRANT dba TO webcalendar;
(Note: I use "webcal01" for a password rather than "web!calendar" because sqlplus barfs on the "!")

To do this in MySQL:
mysql --user=root mysql
mysql> GRANT ALL PRIVILEGES ON *.* TO webcalendar@"%" IDENTIFIED BY 'webcal01' WITH GRANT OPTION;
mysql> FLUSH PRIVILEGES;

Create the calendar tables using the supplied tables.sql file:
MySQL (from command line):
mysql intranet < tables-mysql.sql
(where "intranet" is the name of your database)

Oracle (from command line):
sqlplus webcalendar/webcal01
@tables-oracle;

PostgreSQL:
(This was already done using the PostgreSQL commands above.)

Interbase (from within isql)
connect /path/WEBCAL.gdb;
input path/table-ibase.sql;

This will create all the needed tables and setup one user account with the login "admin" and password "admin", which you are encouraged to use to create your own account.

Application Setup

Next, you will need to customize the file includes/config.php to tell WebCalendar which database you are using and what the database login/password is. Use your favorite text editor (vim, emacs, notepad, etc.) to make these changes.

To configure your database access. Set the values for:
$db_type One of "mysql", "oracle", "postgresql", "odbc", or "ibase"
$db_host The hostname that database is running on. (Use localhost if it's the same machine as the web server.) (This variable is not used with ODBC)
$db_login The database login
$db_password The database password for the above login
$db_database The name of the database that the calendar tables reside in. ("intranet" in the example above.) For ODBC, this should be the DSN.

You can configure the calendar to run in single-user mode or multi-user mode. If this is your first time using the calendar, it's easier to try single-user. You can always switch to multi-user later. Leave $single_user set to "N" (the default) for multi-user or set it to "Y" and set the value of $single_user_login to a login name of your liking to set the system to single-user mode. (And be sure to set the value of $single_user_login to the login that you would choose if you decide to switch to multi-user mode some day.)

Note: If you do decide to switch from single-user mode to multi-user mode, make sure you add in a user to the system for the login you set the $single_user_login variable to. You will need to do this via the database (mysql, sqlplus, etc...) Look in the tables-mysql.sql (or tables-oracle.sql, etc.) to see the example of adding in the "admin" user.

If you are setting up a multi-user calendar, you will need to choose how your users are authenticated. You must change the settings of $use_http_auth and $user_inc within the config.php configuration file to setup which authentication method to use.

You currently have four choices:

  1. Web-based authentication (login/passwords verified in the WebCalendar database):
    $use_http_auth = false;
    $user_inc = "user.php";
  2. HTTP-based authentication (login/passwords verified by the web server):
    $use_http_auth = true;
    $user_inc = "user.php";
    ... and don't forget to setup your web server to handle user authentication. (Note: In order to use HTTP-based authentication, PHP must be setup as a module for your server rather than a CGI.)
  3. NIS-based authentication (login/passwords verified by NIS):
    $use_http_auth = false;
    $user_inc = "user-nis.php";
    Additional configuration settings will need to be set in includes/config/user-nis.php.
  4. LDAP-based authentication (login/passwords verified by LDAP server):
    $use_http_auth = false;
    $user_inc = "user-ldap.php";
    Additional configuration settings will need to be set in includes/config/user-ldap.php.

Next, you may want to customize the event-specific fields found in the includes/site_extras.php field. If this is your first time using the calendar, you can skip this step and come back later since this step is optional.

You can use this feature to add extra fields to your calendar events. For example, you can add a URL or a contact email address. By default, the file is configured with a single reminder field that allows the user to specify how long before the event the reminder should be sent. The includes/site_extras.php file is well-documented, so look there for examples and specific instructions on setting this up.

Keep in mind that if you want to use reminders, you will need to setup the send_reminders.php script (see below) and keep your admin setting for "Email enabled" set to "Yes" on the admin settings page.

Setting up email reminders

PHP does not come with a utility for executing time-based jobs. So, in order to check periodically for email reminders, a shell script was written in PHP. You will need two things to get this working:
  1. You should have a version of PHP built as a CGI (so that you can run php from the command line). This does not mean you must build all of PHP as a CGI. You can still build PHP as a module for your web server and then build the CGI-based PHP later.
  2. You must setup cron (on Linux/UNIX) or something like cron for Windows to run the send_reminders.php script periodically.

Building PHP as a CGI is outside the scope of these instructions. But, if you read the PHP instructions, you'll see that the default build settings will build the CGI-based PHP. If you really can't do this (perhaps you don't have permission to install anything new on the system), skip down a couple of paragraphs to an alternate solution that does not require PHP CGI.

For Linux/UNIX users, add the following line to the crontab entry of a user. (This would be the same user that the web server process runs as.)

1 * * * * cd /some/directory/webcalendar/tools; ./send_reminders.php

Of course, replace the directory location to wherever the send_reminders.php file can be found. If you moved this out of the tools directory (which is recommended for security reasons), be sure to update send_reminders.php since it needs to know where to find other WebCalendar files.

If you cannot setup PHP as a CGI or have no idea how, you can leave send_reminders.php in its current location and access it via a URL. IMHO, this is not the best choice, but it still works. Setup a cron job to access the URL. For Linux/UNIX users, add the following line to the crontab entry of a user.

1 * * * * wget http://yourserverhere/webcalendardirectoryhere/tools/send_reminders.php > /dev/null

Of course, you should probably test this from the command line first to make sure your setup is correct. If you do not have wget installed on your system, you can use any tool (lynx, perl script, etc.) that is capable of making an HTTP request for this.

Help with Apache/PHP/MySQL

If you're having problems getting Apache/PHP/MySQL setup (which is the most common configuration for PHP), Linux/UNIX users can try the following article from Linux Magazine written by yours truly:
The Scoop on PHP, Linux Magaine

If you're a Windoze user, I highly recommend FoxServ, which will install and configure Apache, PHP and MySQL on a MS Windows machine.

Palm Pilot users

Exporting data to your Palm Pilot is possible with install-datebook tool, which is part of the pilot-link distribution.

Unfortunately, there are some bugs in the install-datebook utility, so you'll need to patch it before you compile and install pilot-link:

patch -p0 < install-datebook.patch
Note that install-datebook does not currently support repeating events, so repeating events will not show up as repeating on your Palm Pilot. The tool is not smart enough to know when it's already added an event, so if you use it twice with the same data, you'll get duplicates in your Palm Pilot Calendar.

Optional!

You might want to configure your web server so that users can not access the "includes" directory. See your web server documentation on how to do this.

The includes directory has a index.html file that should prevent users from obtaining a listing files.

Run with it

Hey, you're done... Give it a try by logging in using the default "admin" account (if you're setup for multi-user) or just go to index.php if you're setup for single-user mode.

The default setup for the web-based authentication includes a single user login "demo" with the password set to "admin".

Problems

See FAQ.html if you run into any problems or not sure how to do something...

If your problem is not listed in the FAQ, you can check the following resources available on SourceForge:

Upgrading

If upgrading from a previous version, see the file UPGRADING.html first.

Version 0.9.35 adds support for groups, views, activity log and system settings. This requires six new database tables. Please see UPGRADING.html.

Version 0.9.27 adds support for custom event fields and reminders. This requires two new database tables. Please see UPGRADING.html.

Version 0.9.22 adds support for calendar layers and adds a new table. Please see UPGRADING.html.

Version 0.9.12 changes the way events with no time are handled. Please see UPGRADING.html.

Version 0.9.7 uses a different set of table names than 0.9.6. Please see UPGRADING.html.