DAViCal tips

Note: The author of DAViCal has made significant revisions for his newest version of DAViCal (ver. 0.9.8). However, the repositories contain 0.9.7 and these instructions are for that version. If you wish instructions for the newer version, see this DAViCal tips page.

DAViCal Calendar Server

DAViCal is a CalDAV, postgreSQL, Apache and php-based shared Calendar server that works with Mozilla Thunderbird/Lightning/Sunbird, Evolution, and other calendar clients. Install:

sudo apt-get install davical

The following detailed instructions are duplicated and updated on the DAViCal website.

Introduction

DaviCal has been included in the Ubuntu repositories as a .deb package.

The instructions below are for a new user with a new Ubuntu Server installation. (Obviously, if you are already using the Ubuntu Server, you will probably have done many of the steps already.)

Preliminary Requirements

It is easiest to install the components at the time of the Ubuntu Server installation.

Select the PostgreSQL database task and the LAMP (Linux, Apache2, MySQL5, PHP) tasks at the time of the server installation (or by sudo tasksel install lamp-server).

At a minimum, you will need PostgreSQL (see below), Apache2 (see below), and PHP. You can install PHP separately (i.e. not part of the integrated LAMP stack), if you wish, following these Ubuntu instructions.

Set up the PostgreSQL database

• See these Ubuntu instructions. Use the Hardy Installation instructions (for PostgreSQL 8.3) as well as the Basic Server Setup instructions for Gutsy/Hardy. In short, install (if you already haven't):

sudo apt-get install postgresql

Basic Server Setup:

sudo -u postgres psql postgres

Set a password for the postgres superuser:

\password postgres

(You may need to quit using \q when you are done).

Create the first database:

sudo -u postgres createdb mydb

Install the DaviCal package from repositories

sudo apt-get install davical

Set up DaviCal PostgreSQL users

• Create the DaviCal users (first becoming the the system root superuser, using sudo su, then becoming the database superuser, postgres):

sudo su
su postgres -c "createuser davical_app"
exit

You will get asked about superusers, roles and databases, but just say "No" to all questions. This functional ID needs only minimum rights. Repeat the process to create one more user, "davical_dba":

sudo su
su postgres -c "createuser davical_dba"
exit

Note: In the (older) main DAViCAL site installation page, the user created at this step is "general." This account name is for older versions. You do not need to create a user named "general" any longer.

• Edit the configuration file pg_hba.conf:

sudo nano /etc/postgresql/8.3/main/pg_hba.conf

(Use 8.4 instead of 8.3 if Postgresql 8.4 was installed on your system.)

Add the following 4 lines near (or at) the top;

local all all trust
local davical davical_dba trust
local davical davical_app trust
host davical davical_app 127.0.0.1/32 trust

(The last line is for accessing the database over TCP/IP, assuming the database and the Apache2 server are on the same computer. See here under "Connecting to the Database" for more details.)

• Restart the postgreSQL server:

sudo /etc/init.d/postgresql-8.3 restart

(Use 8.4 instead of 8.3 if Postgresql 8.4 was installed on your system.)

Setup the DaviCal database

• Run the database creation/installation script:

sudo su
su postgres -c /usr/share/davical/dba/create-database.sh
exit

Write down the admin password when it is displayed. You will need it later.

• Once the creation script has run correctly, again edit the pg_hba.conf file:

sudo nano /etc/postgresql/8.3/main/pg_hba.conf

(Use 8.4 instead of 8.3 if Postgresql 8.4 was installed on your system.)

and remove the line

local all all trust

(This step is not strictly necessary for the installation, but do you really want anybody with a local account to have free access to all the databases?)

• Restart the database daemon:

sudo /etc/init.d/postgresql-8.3 restart

(Use 8.4 instead of 8.3 if Postgresql 8.4 was installed on your system.)

Test that your database creation was successful

sudo su
su postgres
psql davical
davical=# \z
davical=# \q
exit
exit

You should see a table with a list of access permissions to "davical_dba". (Typing "\q" exits pqsl.)

Set up Apache2

Install Apache2, if you have not done so already. See the Ubuntu documentation for help.

sudo apt-get install apache2

In your router settings (assuming you have one), set your port forwarding so that your port 80 (http) and 443 (https) is forwarded to your server. Make sure your server firewall (if you have one) allows incoming ports 80 and 443.

I set up a dynamicDNS URL name (at DynDNS.org) called mydavicalsite.dyndns.org, which gets forwarded to my router's IP address by DynDNS.org. (My router happens to keep the DynDNS settings updated.) I want this to be forwarded to the server on my LAN.

I therefore created a virtual host setup in the Apache2 schema by copying the default virtualhost settings file to a new virtualhost settings file for mydavicalsite:

sudo cp /etc/apache2/sites-available/default /etc/apache2/sites-available/mydavicalsite

I edited the virtualhost config file:

sudo nano /etc/apache2/sites-available/mydavicalsite

so that these lines were used (instead of the original ones):

#
# Virtual Host def for Debian package DAViCal
<VirtualHost *:80>
 DocumentRoot /usr/share/davical/htdocs
 DirectoryIndex index.php index.html
 ServerName mydavicalsite.dyndns.org
 ServerAlias calendar.mydavicalsite.dyndns.org
 Alias /images/ /usr/share/davical/htdocs/images/
 <Directory /usr/share/davical/htdocs/>
     AllowOverride None
     Order allow,deny
     Allow from all
 </Directory>
 php_value include_path /usr/share/awl/inc
 php_value magic_quotes_gpc 0
 php_value register_globals 0
 php_value open_basedir 1
 php_value error_reporting "E_ALL & ~E_NOTICE"
 php_value default_charset "utf-8"
</VirtualHost>

To then make the virtualhost file active, I made a symbolic link from the virtualhost configuration file in the apache2 "sites-available" folder to the apache2 "sites-enabled" folder:

sudo ln -s /etc/apache2/sites-available/mydavicalsite /etc/apache2/sites-enabled/mydavicalsite

Then restart apache2:

sudo /etc/init.d/apache2 restart

Create your configuration file

Edit your own configuration file in /etc/davical. (Use your own domain name instead of the one in the example, of course.):

sudo nano /etc/davical/mydavicalsite.dyndns.org-conf.php

You can merely include the following lines.

<?php
//  $c->domain_name = "mydavicalsite.dyndns.org";
//  $c->sysabbr     = 'rscds';
  $c->admin_email = '[email protected]';
  $c->system_name = "Really Simple CalDAV Store";
//  $c->collections_always_exist = true;
//  $c->enable_row_linking = true;
  $c->default_locale = en_US.UTF-8;
  $c->pg_connect[] = 'dbname=davical port=5432 user=davical_app';
?>

(Beware not to include any empty lines after the '?>'.)

Start up DaviCal

From your browser, go to

http://mydavicalsite.dyndns.org

or

http://mydavicalsite.dyndns.org/cal

Use admin as your initial login, and the password assigned to you at installation (you did write it down, didn't you?)

(See here if you forgot your password. In brief:

>sudo su
>su postgres
>psql davical -c 'select username, password from usr;'

Only the initial "admin" password is stored in plain text. All subsequent users have their password stored in an encrypted state. If you change the admin password through the web interface it will also be encrypted from that point forward.)

• Optionally copy a configuration file for testing on the localhost server (this did not work correctly for me, though):

sudo ln -s /etc/davical/mydavicalsite.dyndns.org-conf.php /etc/davical/localhost-conf.php
sudo ln -s /usr/share/davical/htdocs /var/www/davical

Then you can also log through localhost using your browser:

http://localhost/davical

Create TestUser

I created a testuser (that was not an administrator) using the admin login (above), and gave it a password davtest. I created a calendar, using the default location /testuser/home

I then installed both Sunbird

sudo apt-get install sunbird

and Thunderbird with Lightning:

sudo apt-get install thunderbird lightning-extension

Making sure that my firewall wasn't blocking any ports (while testing), or at least allowed 80 and 443 through, I created a new network calendar in both Sunbird and Thunderbird.

Sunbird -> File -> New Calendar... -> On the Network -> CalDAV ->

Location: http://mydavicalsite.dyndns.org/caldav.php/testuser/home ->

Name: testuser

Thunderbird -> Calendar -> Calendar -> New Calendar... -> On the Network -> CalDAV ->

Location: http://mydavicalsite.dyndns.org/caldav.php/testuser/home

Name: testuser

I then entered a calendar entry in Sunbird. I then reloaded the remote calendar:

Sunbird -> File -> Reload Remote Calendars

and when I did the same in Thunderbird Calendar

Thunderbird -> Calendar -> Reload button

then the two calendars were synchronized and both showed the same events.

Voila! Shared calendars.

Administer users

If I made an error in a user setup (from the DaviCAL web interface as the admin user), to correct it I had to make the user inactive and then activate him/her again, at which time I could change the settings.

I had to make a user Public if I wanted to view his/her calendar. The "relationships" are discussed on other pages.

Clarification of user types and relationships

The official documentation on this site is very confusing to me. Here's what I worked out:

User roles

A "user" is really a type of account. There are four types of "user" roles in DAViCal. Not all of them represent individual users.

• Admin: This type of user does not have a calendar (or calendar folder). This type of user account administers the DAViCal database by logging into the administration web interface (only). It is the only type of user that can create new users and change their status (e.g. "active" vs. "inactive", "language", relationships to other types of user accounts, etc.).

• Public: This is an individual user (as in "John Q. Public," I guess. Don't ask me why it is called a Public account). Every individual user who wants to have an individual calendar must have a Public account. Each individual user (with a Public account) can also belong to (i.e. have a "relationship" with) a group and/or (group calendar) resource.

• Group: This type of account is meant as a placeholder for several Public users to belong to (have a "relationship" with). It acts as a user in some ways, but it is not an individual user's account.

• Resource: This is an account for a group calendar, basically. A group (or an individual Public user) must have a "relationship" with the resource to administer the group calendar associated with it. A Public user should not simultaneously have both an individual relationship with a resource as well as a relationship with a group that has a relationship with the same resource.

Types of relationships

A "relationship" defines the types of privileges one user account has in relation to another user account.

• Administers: This means that this user can change the settings of another user account through the web administration interface. It does not mean that this user can access or change the calendar of another user account (which must be done as an "Assistant to...").

• is Assistant to: This means the user can directly read and change the calendar of another Public user or Resource (using a client program). Also, if a Public user is defined with the relationship that it "Administers" a Group user account, and the Group user account is an "Assistant to" a Resource (calendar) account, then the Public user will also be able to directly read and change the calendar of the Resource account (using a client program), as well.

• Can read from: This means the user can directly read (but not change) the calendar of another Public user or Resource (using a client program). Also, if a Public user is defined with the relationship that it "Administers" a Group user account, and the Group user account is given the relationship privilege "Can read from" a Resource (calendar) account, then the Public user will also be able to directly read (but not change) the calendar of the Resource account (using a client program), as well.

• Can see free/busy time of: The free/busy time setting hides the details of events. This is useful when sensitive details are on a calendar that not every shared user ought to be able to see. When this privilege is given, only that events are scheduled (and not their details) are revealed to the Public user that has this relationship (or to all the Public users that belong to a Group with this type of relationship).

Example

(Other examples are given here).

I have a sensitive PowWow group calendar which I want to share with different users.

Using the web administration interface and the initial "admin" account (see above), I first create a new administrator user (account) named BigChief (user role "Admin"). He does not have his own calendar.

There are seven new "Public" users (each with their own calendar by default) that I then create through the web interface (using either my admin or BigChief user account). The seven Public users are Chief1, Chief 2, Indian1, Indian2, Squaw1, Squaw2, and Janitor. I want to ensure that each can be administered by the BigChief administrator account, so I define the "relationships to" each user to include that the BigChief user "Administers" each account.

Again through the administration web interface, I then set up a new Group user account (with the user role "Group"), with a username of "Braves". I define the relationships to this group: for each Public user (found in the dropdown box), Indian1 and Indian2, I select "Administers" (which confers full rights to each member (Indian1 and Indian2) in the Group to do whatever the Group Braves can do).

I then set up a second Group user account with a username of "Squaws." Again I give each user (in the dropdown box) full privileges for (i.e. "Administers") this group.

Once more through the administration web interface, I finally set up a new user account with the user role of "Resource", which will be the account which contains the actual group calendar. I name this user "PowWowCalendar" (which is what I want to call the group calendar).

For PowWowCalendar, I want BigChief to administer it. In the "Relationship to this user" section, therefore, I select (from the dropdown menu) that the user BigChief "Administers" this (group calendar) resource. I want Chief1 and Chief2 to read and change the PowWowCalendar directly. I therefore select each individually in the dropdown section and defines each with "Is Assistant to..." relationship privileges.

I then want all the Indians in the Braves group to also be able to read and change this group calendar resource, so I then select that the (group) user Braves "is Assistant to" this (group calendar) resource. I want all the squaws to be able to read the calendar only, so I select that the (group) user Squaws "Can read from" this (group calendar) resource.

Lastly, I don't want the Janitor to see the actual details of the calendar, so I select that the Janitor user "Can see free/busy time of" this (group calendar) resource.

Now I have to set up the clients.

Each Public user (Chief1, Chief 2, Indian1, Indian2, Squaw1, Squaw2, and Janitor) will set their own user/password combination in their own calendar client. Then each will create a new CalDAV calendar "on the network" (see above for Sunbird/Thunderbird/Lightning instructions) with the location

http://mydavicalsite.dyndns.org/caldav.php/PowWowCalendar/home

Each user should then be able to see the resource calendar with the privileges assigned above.

(Note that BigChief will not be able to access the calendar as an administrator. I think this is a bug in the system. If you wish BigChief to read and change the events in the calendar, he must be "Assistant to..." the (calendar) resource user).

Clients

Multiple Email/Calendar/PIM clients work with DAViCal. See this list, although almost all CALDAV-compatible clients will work.

Mozilla Sunbird / Thunderbird with Lightning

Mozilla Sunbird is a standalone calendar application, while Lightning is a plugin for the email program Thunderbird which is made to work almost identically to Sunbird (but from within Thunderbird, of course).

Idiosyncracies of Sunbird and Thunderbird Lightning

There are two ways to use Sunbird (or the Lightning Extension for Thunderbird): without a saved user name / password combination, or with one. The first is to leave the user name / password unsaved. This will require that you enter the user name / password each time you log in (which can be tiresome, eventually). If using a computer with many users, this is desirable. When prompted to enter the user name and password, merely do not tick the box prompting whether to save the user name /password.

The second method involves saving the user name / password when prompted. However, Sunbird only likes one saved user name. If there are more than one, it will not know which user name to use when logging in to the server. Therefore, do not attempt to save more than one user name / password.

When a user has subscribed to many calendars, that user can view one or many calendars (for which the user has privileges) at the same time by individually checking or unchecking the boxe next to each calendar name.

However, changes made from the calendar screen itself will only apply to the calendar which is highlighted (in the calendar list), whether or not that calendar's box is actually checked.

To view the calendar (and the changes), however, the calendar must also be checked. It is therefore possible to add/change events to a highlighted calendar but not be able to see the changes (if you have that calendar's name highlighted but not checked).

This point can't be stressed enough -- changes to the calendar are applied to whichever calendar is highlighted, but to see the changes, the calendar must also be checked.

Kontact

Kontact is the personal information manager for KDE (used in Kubuntu). There are some instructions on the DAViCal website, but despite the warnings there, the calendar functions of the current version of Kontact work very nicely with DAViCal. In brief:

• Add a new calendar:

• Kontact -> <Right Click> Calendar -> Add... -> Calendar in remote file

(in French: "Calendrier dans un fichier distant")

• Use the same URL for "Download from" and "Upload to"

Example: http://calendar.example.com/caldav.php/user/home

• The calendar must exist in order to use it, of course, or Kontact will send an error (such as "file http://calendar.example.com/caldav.php/user/home does not exist"). You must create the calendar using the DAViCal web-based administration interface.

• These instructions apply to both Kontact and Korganizer.

Evolution

See the DAViCal website for some details. I haven't used Evolution with DAViCal, so if you have, please add your experience here (as well as on the DAViCal website).