jms1.net - Setting up a DAViCal Server

The information below pertains to my own server, which is running CentOS 5.0. CentOS is built using the source code from RedHat Enterprise. It uses a different package manager, and not have any official support from RedHat (no more so than any other Linux distribution.) If you are familiar with RedHat, Fedora, CentOS, Whitebox, Yellowdog, Aurora, or some other "RedHat-flavoured" distribution of Linux, you should be able to follow along with this information without too many problems.

Pre-requisites

DAViCal requires the system to have certain packages installed before it can work. The major dependences are a working Apache web server with PHP 5, a PostgreSQL 8.1 (or higher) database server, and the package which allows PHP to talk to PostgreSQL (which my own server didn't already have- I don't write PHP myself, and I try to avoid using it, as I feel the language makes it too easy for bad programmers to write sloppy code.)

My Apache was already configured; if this is an initial installation of Apache on your server, you should stop here and configure Apache in the way you prefer to have it. Please don't just blindly assume that their default settings are correct.

Installing the libawl-php and davical packages

I downloaded the two packages from http://sourceforge.net/project/showfiles.php?group_id=179845. At the time I downloaded them (2008-11-25) the current versions were awl-0.34 and davical-0.9.6.2. I downloaded the ".rpm" files, which were not platform-dependent (i.e. they were ".noarch.rpm" files, since they contain scripts rather than compiled executables.)

# rpm -ivh libawl-php-0.34-2.noarch.rpm
...
# rpm -ivh davical-0.9.6.2-2.noarch.rpm
...

Creating the database

The program comes with a script which automatically creates two users (within the PostgreSQL server, not system users), creates a database "owned" by one of those userids, and populates the database with the set of tables required to hold the events.

If you aren't already familiar with how users are handled under PostgreSQL... The SQL server has its own list of users, which only exist within the SQL server. In many cases, some of those "SQL users" will also exist as system users, however this does not have to be the case. You need to understand that "SQL user" and "system user" are two different things, otherwise parts of the following information may confuse you.

# cd /usr/share/davical/dba
# su postgres -c ./create-database.sh
CREATE DATABASE
Supported locales updated.
CalDAV functions updated.
RRULE functions updated.
Database permissions updated.
NOTE
====
* You will need to edit the PostgreSQL pg_hba.conf to allow the
'davical_dba' database user access to the 'davical' database.

* You will need to edit the PostgreSQL pg_hba.conf to allow the
'davical_app' database user access to the 'davical' database.

* The password for the 'admin' user has been set to 'N0kB9eCA'"
The program picks eight random characters for the password. Yours will probably not match this one. This is not the one it actually chose when I set up my server, and even if it were, I've already changed it.

Thanks for trying DAViCal! Check in /usr/share/doc/davical/examples/ for
some configuration examples. For help, visit #davical on irc.oftc.net.

Before you do anything else, write down the randomly generated password it created for the "admin" user. You will need it when the setup is finished.

The one thing it didn't do, and the DAViCal directions pages alluded to this without explaining it very clearly, was set up the the PostgreSQL security to allow any process on the same system to use the "davical_app" and "davical_dba" SQL users without having to supply a password. I personally don't think this is the best way to handle it, but so far I haven't found the time to dig through the code and figure out how and where to supply passwords.

The default configuration of PostgreSQL allows any system user on the machine to connect to the server as the SQL user with the same name, if such a SQL user exists (i.e. if I'm logged into the server as "jms1", I am able to connect to the PostgreSQL server as SQL user "jms1" without having to provide a password. This is configured in a file called "pg_hba.conf", which is in the "data" directory where the PostgreSQL server stores the database files. On my system, that directory is "/var/lib/pgsql/data".

To configure the settings for the DAViCal SQL users, I edited this file. Before I changed it, the end of the file looked like this:

# TYPE DATABASE USER CIDR-ADDRESS METHOD # "local" is for Unix domain socket connections only local all all ident sameuser host all all 127.0.0.1/32 ident sameuser host all all ::1/128 ident sameuser

I added these two lines BEFORE the existing lines, so that the PostgreSQL server would evaluate them first and use those rules for the "davical" database.

# TYPE DATABASE USER CIDR-ADDRESS METHOD local davical davical_app trust local davical davical_dba trust # "local" is for Unix domain socket connections only local all all ident sameuser host all all 127.0.0.1/32 ident sameuser host all all ::1/128 ident sameuser

After making this change, I restarted my PostgreSQL server in order for the changes to take effect.

# /etc/init.d/postgresql restart
Stopping postgresql service: [ OK ]
Starting postgresql service: [ OK ]

Configuring Apache

Most of the existing sets of directions I found for configuring Apache for DAViCal showed how to configure things if you only have one web site on the machine, or if you want DAViCal to work on every virtual host on the machine. My server was already hosting several web sites (using the NameVirtualHost mechanism) and I only wanted DAViCal to work within one specific web site- and that site is SSL-secured.

It turns out the Apache configuration is very simple. The .rpm file actually installed an entire directory full of PHP files in the /usr/share/davical/htdocs directory, and the Apache configuration involves telling Apache to map a specific URL to that directory.

The first change is global, which means it needs to be in your httpd.conf file, but NOT within any specific VirtualHost block. Even if you plan to have two or more URLs to access the DAViCal server, this block only needs to exist one time. It looks like this:

<Directory "/usr/share/davical/htdocs">
Order deny,allow
Allow from all
</Directory>

The second change is site-specific, and should only be done within the VirtualHost block for the site(s) under which you wish DAViCal to be visible. It creates a URL "alias" which points to a specific directory on the server. It looks like this:

Configuring DAViCal itself

After restarting Apache, we need to configure DAViCal so it knows how to reach the database, along with some cosmetic settings. This is done by creating a small PHP file with the settings. The DAViCal program uses the hostname from the HTTP request as part of the filename, which allows you to have different DAViCal instances on the same machine which connect to different databases (and can therefore store different clients' information, if you are hosting the DAViCal service for other people.)

This example assumes you are using the hostname "cal.domain.xyz" as the DAViCal server.

# cd /etc/davical
# nano cal.domain.xyz-conf.php
The file needs to look similar to this. Note that there are other settings you could put into this file, the other instruction sets I saw included some other settings but had them as comments. I prefer to simply not include them. If you need to customize things further, DAViCal's documentation should tell you what else you can add here.

<?php

    $c->admin_email = 'webmaster@domain.xyz' ;

    $c->system_name = 'Domain XYZ CalDAV Server' ;

    $c->default_locale = 'en_US.UTF-8' ;

    $c->pg_connect[] = 'dbname=davical port=5432
	user=davical_app' ;

?>

# chmod 644 cal.domain.xyz-conf.php

Once this is done, you should be able to access DAViCal's web interface, using the URL you configured while setting up Apache (i.e. "http://" or "https://", the hostname of the VirtualHost where the "Alias" line is found, and the alias itself. For example, if your httpd.conf contained this...

<VirtualHost 1.2.3.4:80>
ServerName cal.domain.xyz
...
Alias /cal/ /usr/share/davical/htdocs/
...
</VirtualHost>

You should first log in using "admin" as the userid, and the randomly generated password from when the database was created. Once you log in, click the "Users" tab at the top of the page, click the "1" to the left of the "admin" user, click "Edit Calendar Administrator" on the second row of tabs (again, at the top of the page), and change the password (I also changed the userid) of the "admin" user to something you will remember. Make sure to click the "Update" button at the very bottom of the page (in my browser it stretches to almost the full width of the browser window) to save your changes.

This user is only used for administering DAViCal. Your next step should probably be to create a user to hold your calendars. Click "Users" on the top row of tabs, and then "New User" on the second row of tabs.

The rest of the web interface is relatively self-explanatory. I've done some experimenting with it- I like the idea that non-admin users are able to log in and change their own passwords, however I don't like the fact that they can see a list of other users, AND view information (including a list of calendars) about the other users- I think the ability to see other users at all should be limited to "Admin" users.

Final steps

At this point the server is working. You may want to ensure that both PostgreSQL and Apache are configured to automatically start when the system reboots...

Other than creating users within DAViCal, the server side of things is pretty much done. My main DAViCal page has my notes about the CalDAV clients I've tried, as well as a link to DAViCal's instructions for how to set up the various clients.