Merge branch 'master' of github.com:DAViCal/davical into github
[davical.git] / INSTALL
blobf40f43c8301c16c3fcc8a4fa17b9255dd32e033d
1 Installation
2 ============
4 Debian Users
5 ------------
7 DAViCal is in Debian Sid so you should be able to simply:
9 apt-get install davical
11 Or synaptic or some other equivalent package manager to fetch and install
12 DAViCal and all the dependencies.
14 Skip to the "Database Setup" part if you have done that already.
17 Gentoo Users
18 ------------
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.
23 You can then use emerge to install DAVical and its dependencies.
25 emerge davical
28 Other Linux Users
29 -----------------
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.
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).
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.
44 Non-Linux Users
45 ---------------
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.
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.
57 I'm available to answer questions, anyway :-)
59 Getting Help
60 ------------
62 The best place to get help is on IRC.  The official DAViCal
63 IRC channel is #davical on irc.oftc.net
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.
71 Pre-requisites
72 ==============
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.
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
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.
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.
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
101   Yaml
102     Debian: aptitude install libyaml-perl
103     Gentoo: emerge dev-perl/yaml
105   pwgen (not mandatory)
106     Debian: aptitude install pwgen
107     Gentoo: app-admin/pwgen
109 Database Setup
110 ==============
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.
116 To create the database itself, run the script:
118 dba/create-database.sh
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.
125 This script also expects to be running as a user who has rights
126 to create a new database.
131 Apache VHost Configuration
132 ==========================
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.
140 I use a Virtual Host stanza like this:
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>
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).
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.
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.
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.
176 DAViCal Configuration
177 =====================
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.
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;
189   $c->pg_connect[] = 'dbname=davical port=5432 user=general';
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.
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.
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.
209 Completed?
210 ==========
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:
216 psql davical -c 'select username, password from usr;'
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.
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.
225 See:
227 http://wiki.davical.org/
229 Which is the place where documentation will generally be kept up to
230 date the most.