INSTALL

   1 Installation
   2 ============
   3
   4 Debian Users
   5 ------------
   6
   7 DAViCal is in Debian Sid so you should be able to simply:
   8
   9 apt-get install davical
  10
  11 Or synaptic or some other equivalent package manager to fetch and install
  12 DAViCal and all the dependencies.
  13
  14 Skip to the "Database Setup" part if you have done that already.
  15
  16
  17 Gentoo Users
  18 ------------
  19
  20 DAVical is in the Sunrise overlay. You will have to add this overlay,
  21 following the instructions on http://overlays.gentoo.org/proj/sunrise.
  22
  23 You can then use emerge to install DAVical and its dependencies.
  24
  25 emerge davical
  26
  27
  28 Other Linux Users
  29 -----------------
  30
  31 You will need to download the latest versions of the davical and awl packages
  32 from the DAViCal site.  See http://www.davical.org/ for more information.
  33
  34 You will need to untar these. Preferably you will untar them from within
  35 the "/usr/share" directory and everything will be in it's expected location
  36 (well, except the docs, but it will at least be tidy and everything will be
  37 in one place).
  38
  39 I would like to hear from non-Debian users regarding things I might have
  40 missed, or things you have learned about the system, so please tell us on
  41 IRC, or post to the mailing list or forums.
  42
  43
  44 Non-Linux Users
  45 ---------------
  46
  47 I would really like to hear from you. As far as I can see there is no
  48 reason why this can't all work on FreeBSD, Microsoft Windows, VMS, Mac OS
  49 or whatever else, as long as the pre-requisites are able to be installed.
  50
  51 For Unix and unix-like operating systems the "Other Linux Users"
  52 instructions are likely to be reasonably close to what you need. For other
  53 systems everything will need some adjustment, and in particular some of
  54 the path name and shell expectations coded into the database creation
  55 scripts are likely to need love.
  56
  57 I'm available to answer questions, anyway :-)
  58
  59 Getting Help
  60 ------------
  61
  62 The best place to get help is on IRC.  The official DAViCal
  63 IRC channel is #davical on irc.oftc.net
  64
  65 The starting point for further help should be the DAViCal website
  66 at http://www.davical.org/ and from there you might visit the wiki
  67 which contains a fair amount of information about configuring
  68 DAViCal in a variety of different circumstances.
  69
  70
  71 Pre-requisites
  72 ==============
  73
  74 DAViCal depends on a number of things.  Firstly, it depends
  75 on Andrew's Web Libraries (AWL) which is a set of useful
  76 PHP functions and objects written by Andrew McMillan over
  77 a number of years.
  78
  79 The following other software is also needed:
  80   Apache: 1.3.x or 2.x.x
  81   PHP: 5.1 or greater (along with the PDO and PostgreSQL extensions)
  82   PostgreSQL: 8.2 or greater
  83
  84 The PostgreSQL database may be installed on a server other
  85 than the web server, and that kind of situation is recommended
  86 if you want to increase the security or scalability of your
  87 installation.
  88
  89 Since the CalDAV store takes over a significant amount of path
  90 hierarchy, it is designed to be installed in it's own virtual
  91 host.  If you want it to operate within the web root of some
  92 other application I will happily accept patches to make it do
  93 that, but I am pretty sure it won't work that way out of the
  94 box.
  95
  96 Several helper programs are needed to setup and upgrade davical:
  97   Perl with DBI and DBD-Pg
  98     Debian: aptitude install libdbi-perl libdbd-pg-perl
  99     Gentoo: emerge dev-perl/DBI dev-perl/DBD-Pg
 100
 101   Yaml
 102     Debian: aptitude install libyaml-perl
 103     Gentoo: emerge dev-perl/yaml
 104
 105   pwgen (not mandatory)
 106     Debian: aptitude install pwgen
 107     Gentoo: app-admin/pwgen
 108
 109 Database Setup
 110 ==============
 111
 112 On your database server you will need to create a user called
 113 'general' which should not be able to create databases or users,
 114 and which will be granted minimum privileges for the application.
 115
 116 To create the database itself, run the script:
 117
 118 dba/create-database.sh
 119
 120 Note that this script calls the AWL database scripts as part
 121 of itself and it expects them to be located in /usr/share/awl/dba
 122 which might be a reasonable place, but it might not be where you
 123 have put them.
 124
 125 This script also expects to be running as a user who has rights
 126 to create a new database.
 127
 128
 129
 130
 131 Apache VHost Configuration
 132 ==========================
 133
 134 Your Apache instance needs to be configured for Virtual Hosts.  If
 135 this is not already the case you may want to read some documentation
 136 about that, and you most likely will want to ensure that any existing
 137 site becomes the **default** virtual host, with DAViCal only being a
 138 single virtual host.
 139
 140 I use a Virtual Host stanza like this:
 141
 142 #
 143 # Virtual Host def for Debian packaged DAViCal
 144 <VirtualHost 123.4.56.78 >
 145   DocumentRoot /usr/share/davical/htdocs
 146   DirectoryIndex index.php index.html
 147   ServerName davical.example.net
 148   ServerAlias calendar.example.net
 149   Alias /images/ /usr/share/davical/htdocs/images/
 150   php_value include_path /usr/share/davical/inc:/usr/share/awl/inc
 151   php_value magic_quotes_gpc 0
 152   php_value register_globals 0
 153   php_value error_reporting "E_ALL & ~E_NOTICE"
 154   php_value default_charset "utf-8"
 155 </VirtualHost>
 156
 157 Replace 123.4.56.78 with your own IP address, of course (you can
 158 use a name, but your webserver may fail on restart if DNS happens
 159 to be borked at that time).
 160
 161 At this point it is necessary to have register_globals enabled. All
 162 variables are sanitised before use, but some routines do assume
 163 this is turned on.
 164
 165 The various paths and names need to be changed to reflect your
 166 own installation, although those are the recommended locations
 167 for the various pieces of the code (and are standard if you
 168 installed from a package.
 169
 170 Once your VHost is installed an working correctly, you should be
 171 able to browse to that address and see a page telling you that
 172 you need to configure DAViCal.
 173
 174
 175
 176 DAViCal Configuration
 177 =====================
 178
 179 The DAViCal configuration generally resides in /etc/davical/<domain>-conf.php
 180 and is a regular PHP file which sets (or overrides) some specific variables.
 181
 182 <?php
 183 //  $c->domainname = "calendar.example.net";
 184 //  $c->sysabbr     = 'davical';
 185 //  $c->admin_email = 'admin@example.net';
 186 //  $c->system_name = "DAViCal CalDAV Server";
 187 //  $c->collections_always_exist = false;
 188
 189   $c->pg_connect[] = 'dbname=davical port=5432 user=general';
 190
 191 ?>
 192
 193 Multiple values may be specified for the PostgreSQL connect string,
 194 so that you can (e.g.) use PGPool to cache the database connection
 195 but fall back to a raw database connection if it is not running.
 196
 197 The "collections_always_exist" value defines whether a MKCALENDAR
 198 command is needed to create a calendar collection before calendar
 199 resources can be stored in it.  You will want to leave this to the
 200 default (true) if people will be using Evolution or Sunbird /
 201 Lightning against this because that software does not support the
 202 creation of calendar collections.
 203
 204 You should set the 'domainname' and 'admin_email' as they are used
 205 within the system for constructing URLs, and for notifying some
 206 kinds of events.
 207
 208
 209 Completed?
 210 ==========
 211
 212 If all is going well you should now be able to browse to the admin
 213 pages and log in as 'admin' (the password is the bit after the '**'
 214 in the 'password' field of the 'usr' table so:
 215
 216 psql davical -c 'select username, password from usr;'
 217
 218 should show you a list.  Note that once you change a password it
 219 won't be readable in this way - only the initial configuration
 220 leaves passwords readable like this for security reasons.
 221
 222 If all is working then you should be ready to configure a client
 223 to use this, and the docs for that are elsewhere.
 224
 225 See:
 226
 227 http://wiki.davical.org/
 228
 229 Which is the place where documentation will generally be kept up to
 230 date the most.
 231