Before Starting

Debian Users

Ideally you will be running a recent Debian (or Ubuntu) release and will be able to add:

deb http://debian.mcmillan.net.nz/debian lenny awm

to your /etc/apt/sources.list. Once you have done that you can use apt-get or synaptic or some other equivalent package manager to fetch and install DAViCal and all the dependencies.

This repository is signed by Andrew McMillan's public key, which you can install so that you don't get asked for confirmation all the time:

sudo apt-key advanced --keyserver pgp.net.nz --recv-keys F6E0FA5CF0307507BB23A512EAFCFEBF8FEB8EBF

Skip to the "Database Setup" part if you have done that already.

Other Linux Users

Please write something up about your experiences in the Wiki, adding distribution specific notes to pages somewhere under here: http://wiki.davical.org/w/Installation_Stuff

RPM Packages of DAViCal

We have created RPM packages of DAViCal and libawl-php from the .deb packages using "alien". These are reported to work fine, so use them and then proceed to the Pre-requisites section below. If you would like to work with us to create native RPM packages please get in touch!

SuSE Linux

On SuSE Linux you may need to look in /var/lib/pgsql/data/ for the pg_hba.conf file.

Gentoo

Davical and the awl library ebuilds are available on the sunrise overlay. You'll have to add this overlay to your system:

emerge layman
layman -f -a sunrise
echo "source /usr/portage/local/layman/make.conf" >> /etc/make.conf

From there, you can keep the overlay in sync with the command:

layman -s sunrise

Davical can now be installed with a normal:

emerge davical

Slackware, BSD and the rest

You will need to download the latest versions of the DAViCal and awl packages from the sourceforge download page for DAViCal.

You will need to untar these. Preferably you will untar them from within the "/usr/share" directory and everything will be in it's expected location (well, except the docs, but it will at least be tidy and everything will be in one place).

We would like to hear from non-Debian users regarding things which might have been missed, or things you have learned about the system, so please write about your installation experiences on the Wiki, or post a message in the Sourceforge forums.

Non-Linux Users

We would really like to hear from you. As far as we can see there is no reason why this can't all work on FreeBSD, Microsoft Windows, VMS, Mac OS or whatever else, as long as the pre-requisites are able to be installed.

For Unix and unix-like operating systems the "Other Linux Users" instructions are likely to be reasonably close to what you need. For other systems everything will need some adjustment, and in particular some of the path name and shell expectations coded into the database creation scripts are likely to need love.

We're available to answer questions, anyway :-)

Pre-requisites

DAViCal depends on a number of things. Firstly, it depends on Andrew's Web Libraries (AWL) which is a set of useful PHP functions and objects written by Andrew McMillan over a number of years.

The following other software is also needed:

The PostgreSQL database may be installed on a server other than the web server, and that kind of situation is recommended if you want to increase the security or scalability of your installation.

Since the CalDAV store takes over a significant amount of path hierarchy, it can be easier in it's own virtual host. If you want it to operate within the web root of some other application there are instructions on the Wiki about doing this, as well as other fancy tricks such as configuring URL rewriting in order to shorten the path.

Database Setup

Connecting to the Database

Before your database has been created, you should edit your pg_hba.conf file (in /etc/postgresql/8.x/main/pg_hba.conf on Debian or derivatives) in order to grant access to the database for the 'davical_dba' user that will be created to 'own' the database and tables, and also for the 'davical_app' user which will be created for the web application fo connect as.

In a simple installation, where you do not have untrusted users on your database server, and your database is on the same computer as the web server, the following lines (at the very top of the pg_hba.conf file) should be enough:

local   davical    davical_app   trust
local   davical    davical_dba   trust

This means that anyone on the local computer (including the web application) will have rights to connect to the DAViCal database as the 'davical_app' or 'davical_dba' user. It will not allow remote access, or access as any user other than 'davical_app' or 'davical_dba'.

If you want to connect to the database over TCP/IP from your webserver on '192.168.59.231' (e.g. rather than unix sockets which will only work for access from the local machine), the lines in the pg_hba.conf file should look something like:

host davical davical_app 192.168.59.231/32 trust
host davical davical_dba 192.168.59.231/32 trust

If you want greater security, or if you want to have the database on a different server, you should read the PostgreSQL documentation on pg_hba.conf for the version you are using.

Once you have changed the pg_hba.conf file you will need to reload or restart the PostgreSQL process for the change to come into effect.

Creating and Building the Database

To create the database itself, run the script:

dba/create-database.sh

Note that this script calls the AWL database scripts as part of itself and it expects them to be located in /usr/share/awl/dba which might be a reasonable place, but it might not be where you have put them.

This script expects to be running as a user who has rights to create a new database, so you may need to do this as the "postgres" user, for example:

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

Apache Configuration

Relative to an existing DocumentRoot

You can create a symlink from an existing web root directory to the /usr/share/davical/htdocs directory, such as:

cd /my/apache/docroot
ln -s /usr/share/davical/htdocs davical
You will need to change your global PHP configuration to include the directory '/usr/share/awl/inc' in the 'include_path' setting, along with any other directories already needed by other applications. You will also need to ensure that 'magic_quotes_gpc' is off.

Using a Virtual Host

Your Apache instance needs to be configured for Virtual Hosts. If this is not already the case you may want to read some documentation about that, and you most likely will want to ensure that any existing site becomes the **default** virtual host, with DAViCal only being a single virtual host.

I use a Virtual Host stanza like this:

# Virtual Host def for Debian packaged DAViCal
<VirtualHost 123.4.56.78 >
  DocumentRoot /usr/share/davical/htdocs
  DirectoryIndex index.php index.html
  ServerName davical.example.net
  ServerAlias calendar.example.net
  Alias /images/ /usr/share/davical/htdocs/images/
  <Directory /usr/share/davical/htdocs/>
      AllowOverride None
      Order allow,deny
      Allow from all
  </Directory>
  AcceptPathInfo On
  #
  #  You probably don't need to enable any of these sorts of things other than in exceptional
  #  circumstances.  Apart from the include path (which DAViCal will discover if it is anywhere
  #  'normal') they are the default in newer PHP versions. 
  #
  # php_value include_path /usr/share/awl/inc
  # php_value magic_quotes_gpc 0
  # php_value register_globals 0
  # php_value error_reporting "E_ALL & ~E_NOTICE"
  # php_value default_charset "utf-8"
</VirtualHost>

Replace 123.4.56.78 with your own IP address, of course (you can use a name, but your webserver may fail on restart if DNS happens to be borked at that time).

The various paths and names need to be changed to reflect your own installation, although those are the recommended locations for the various pieces of the code (and are standard if you installed from a package.

Once your VHost is installed an working correctly, you should be able to browse to that address and see a page telling you that you need to configure DAViCal.

On Debian systems (or derivatives such as Ubuntu), when you are using Apache 2, you should put this definition in the /etc/apache2/sites-available directory and you can use the 'a2ensite' command to enable it.

DAViCal Configuration

The DAViCal configuration generally resides in /etc/davical/<domain>-conf.php and is a regular PHP file which sets (or overrides) some specific variables.

<?php
//  $c->domain_name = "calendar.example.net";
//  $c->sysabbr     = 'DAViCal';
//  $c->admin_email = 'admin@example.net';
//  $c->system_name = "Example DAViCal Server";
//  $c->enable_row_linking = true;

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

See the wiki for the full list of DAViCal configuration settings.

Multiple values may be specified for the PostgreSQL connect string, so that you can (e.g.) use PGPool to cache the database connection but fall back to a raw database connection if it is not running.

You should set the 'domain_name' and 'admin_email' as they are used within the system for constructing URLs, and for notifying some kinds of events.

If you are in a non-English locale, you can set the default_locale configuration to one of the supported locales.

Supported Locales

At present the following locales are supported:

If you want locale support you probably know more about configuring it than me, but at this stage it should be noted that all translations are UTF-8, and pages are served as UTF-8, so you will need to ensure that the UTF-8 versions of these locales are supported on your system.

Completed?

If all is going well you should now be able to browse to the admin pages and log in as 'admin' (the password is the bit after the '**' in the 'password' field of the 'usr' table so:

psql davical -c 'select username, password from usr;'

should show you a list. Note that once you change a password it won't be readable in this way - only the initial configuration leaves passwords readable like this for security reasons.

Check the '/setup.php' page in your installation and if everything is working then you should be ready to configure a client to use your new DAViCal installation, and the docs for that are elsewhere.

If you had to do something else that is not covered here, or if you have any other notes you want to add to help others through the installation process, please write something up about your experiences in the Wiki, including distribution specific notes, to pages somewhere under here: http://wiki.davical.org/w/Installation_Stuff

Upgrades

Whenever you upgrade the DAViCal application to a new version you will need to run dba/update-davical-database which will apply any pending database patches, as well as enabling new translations, loading database views and functions, and setting application permissions to database tables.

When the database is created all the tables are owned by a 'davical_dba' user which you will also want to add access for in your pg_hba.conf, although in that case you may want to set the user to have a password, since it has full control over the DAViCal database structure and content.

See http://wiki.davical.org/w/Update-davical-database for more information.