Before Starting

Debian Users

Recent Debian (and Ubuntu) releases have DAViCal 1.1.3.1 and AWL 0.55 (a library referenced by DAViCal) available in their repositories, and you can use apt-get or similar tools to download and install DAViCal. Once you have done that, you should be able to proceed to the Database Setup section, below.

Other Linux Users

In most cases, you will need to download the latest versions of the 'DAViCal' and 'awl' packages from here or the repository on GitLab and should proceed with the 'Pre-requisites' section below.

The DAViCal wiki contains information on installation on other versions of Linux. Please feel free to contribute your experiences, using the mailing list if you don't have a wiki account.

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 on the mailing list.

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 its 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.

Installation from source

DAViCal is a web application. So unlike other software, where you have to compile the source code into a binary that you're then executing, the source files are executed directly by a webserver - even the config files you're going to edit are ordinary PHP source files.

Therefore installation from source is not much different from installing DAViCal from a distribution package. You'll only have to do some of the work manually that your package manager would usually do for you.

First you have to get the DAViCal code from GitLab. You can either download a zip file containing a specified release or you might download the newest version directly out of the "master branch":

git clone https://gitlab.com/davical-project/davical.git
git clone https://gitlab.com/davical-project/awl.git

This will create two new directories davical and awl in your current directory. Now go and delete the .git subdirectories (that contain information about the current revision and possible local changes) out of both of them. Not that they will do any harm but there's no need to have them in a publicly accessible location.

rm -rf ./davical/.git/
rm -rf ./awl/.git/

Several parts of DAViCal expect certain parts of the software to be located in some well known system directories. So the last thing you have to do, is to move the two directories to their expected positions and set the proper file permissions. The most reasonable choices here would be /usr/share or /usr/local/share:

mv davical/ /usr/share/
mv awl/ /usr/share/

chown -R root:www-data /usr/share/davical
cd /usr/share/davical/
find ./ -type d -exec chmod u=rwx,g=rx,o=rx '{}' \;
find ./ -type f -exec chmod u=rw,g=r,o=r '{}' \;

chown -R root:www-data /usr/share/awl
cd /usr/share/awl/
find ./ -type d -exec chmod u=rwx,g=rx,o=rx '{}' \;
find ./ -type f -exec chmod u=rw,g=r,o=r '{}' \;

Database Setup

Preparing the Database Connection

Before your database is being created, you should edit your pg_hba.conf file (in /etc/postgresql/9.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 create-database.sh (make sure the file is executable first, especially if you followed the instructions above to adjust file permissions):

cd /usr/share/davical/dba/
chmod u+x create-database.sh
./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

In case the script fails you probably will have to delete the incompletely created database, fix the error and start over again. A good first shot is to check if all the package dependencies DAViCal and the database scripts rely upon are fullfilled.

To delete the database a simple

su postgres -c "dropdb davical"

should do the job.

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.

If on older versions of PHP 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.

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.

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.

If you only get a blank page, you should check if your DAViCal configuration file is present in /etc/davical/ (see section below), that its readable by your webserver and that you specified the correct database in it that you want DAViCal to connect to.

DAViCal Configuration

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

Note that if you want to run multiple instances of DAViCal for several domains the filename HAS to match the server.domain.net-conf.php scheme following the domain name you specified in your Apache Virtual Host (an IP address will work as well)! If you only want to run a single instance of DAViCal you can simply create a file called /etc/davical/config.php.

If you used a package manager to install DAViCal that file should already exist. If you installed DAViCal manually you can either copy the example config file from /usr/share/davical/config/ or you create a new file and start your configuration from scratch. A minimal configuration file could look like this:

<?php
  $c->domain_name = "calendar.example.net";
  $c->sysabbr     = 'DAViCal';
  $c->admin_email = 'admin@example.net';
  $c->system_name = "Example DAViCal Server";
  $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.