Extend $c->default_collections - adding 'calendar_components' and 'default_properties'

[davical.git] / INSTALL

Installation
============

Debian Users
------------

DAViCal is in Debian Sid so you should be able to simply:

apt-get install davical

Or synaptic or some other equivalent package manager to fetch and install
DAViCal and all the dependencies.

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


Gentoo Users
------------

DAVical is in the Sunrise overlay. You will have to add this overlay,
following the instructions on http://overlays.gentoo.org/proj/sunrise.

You can then use emerge to install DAVical and its dependencies.

emerge davical


Other Linux Users
-----------------

You will need to download the latest versions of the davical and awl packages
from the DAViCal site.  See http://www.davical.org/ for more information.

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

I would like to hear from non-Debian users regarding things I might have
missed, or things you have learned about the system, so please tell us on
IRC, or post to the mailing list or forums.


Non-Linux Users
---------------

I would really like to hear from you. As far as I 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.

I'm available to answer questions, anyway :-)

Getting Help
------------

The best place to get help is on IRC.  The official DAViCal
IRC channel is #davical on irc.oftc.net

The starting point for further help should be the DAViCal website
at http://www.davical.org/ and from there you might visit the wiki
which contains a fair amount of information about configuring
DAViCal in a variety of different circumstances.


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:
  Apache: 1.3.x or 2.x.x
  PHP: 5.1 or greater (along with the PDO and PostgreSQL extensions)
  PostgreSQL: 8.2 or greater

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 is designed to be installed in it's own virtual
host.  If you want it to operate within the web root of some
other application I will happily accept patches to make it do
that, but I am pretty sure it won't work that way out of the
box.

Several helper programs are needed to setup and upgrade davical:
  Perl with DBI and DBD-Pg
    Debian: aptitude install libdbi-perl libdbd-pg-perl
    Gentoo: emerge dev-perl/DBI dev-perl/DBD-Pg

  Yaml
    Debian: aptitude install libyaml-perl
    Gentoo: emerge dev-perl/yaml

  pwgen (not mandatory)
    Debian: aptitude install pwgen
    Gentoo: app-admin/pwgen

Database Setup
==============

On your database server you will need to create a user called
'general' which should not be able to create databases or users,
and which will be granted minimum privileges for the application.

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 also expects to be running as a user who has rights
to create a new database.




Apache VHost Configuration
==========================

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/
  php_value include_path /usr/share/davical/inc:/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).

At this point it is necessary to have register_globals enabled. All
variables are sanitised before use, but some routines do assume
this is turned on.

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.



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->domainname = "calendar.example.net";
//  $c->sysabbr     = 'davical';
//  $c->admin_email = 'admin@example.net';
//  $c->system_name = "DAViCal CalDAV Server";
//  $c->collections_always_exist = false;

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

?>

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.

The "collections_always_exist" value defines whether a MKCALENDAR
command is needed to create a calendar collection before calendar
resources can be stored in it.  You will want to leave this to the
default (true) if people will be using Evolution or Sunbird /
Lightning against this because that software does not support the
creation of calendar collections.

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


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.

If all is working then you should be ready to configure a client
to use this, and the docs for that are elsewhere.

See:

http://wiki.davical.org/

Which is the place where documentation will generally be kept up to
date the most.