From 55c2c92da855238c86c9fffac500493e7020669e Mon Sep 17 00:00:00 2001 From: Andrew McMillan Date: Tue, 24 Oct 2006 07:51:38 +1300 Subject: [PATCH] Basic installation instructions. --- INSTALL | 159 ++++++++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 159 insertions(+) create mode 100644 INSTALL diff --git a/INSTALL b/INSTALL new file mode 100644 index 00000000..6f08b4b5 --- /dev/null +++ b/INSTALL @@ -0,0 +1,159 @@ +Installation +============ + +Ideally you will be running a recent Debian release and will +be able to add: + +deb http://debian.mcmillan.net.nz/debian unstable 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 rscds and all the dependencies. + +Skip to the "Database Setup" part if you have done that already. + + + +Pre-requisites +============== + +RSCDS 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: 4.3 or greater, including PHP5 + PostgreSQL: 7.4 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. + + + +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 RSCDS only being a +single virtual host. + +I use a Virtual Host stanza like this: + +# +# Virtual Host def for Debian packaged RSCDS + + DocumentRoot /usr/share/rscds/htdocs + DirectoryIndex index.php index.html + ServerName rscds.example.net + ServerAlias calendar.example.net + Alias /images/ /usr/share/rscds/htdocs/images/ + php_value include_path /usr/share/rscds/inc:/usr/share/awl/inc + php_value magic_quotes_gpc 0 + php_value register_globals 1 + + +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 RSCDS. + + + +RSCDS Configuration +=================== + +The RSCDS configuration generally resides in /etc/rscds/-conf.php +and is a regular PHP file which sets (or overrides) some specific variables. + +domainname = "calendar.example.net"; +// $c->sysabbr = 'rscds'; +// $c->admin_email = 'admin@example.net'; +// $c->system_name = "Really Simple CalDAV Store"; +// $c->collections_always_exist = false; + + $c->pg_connect[] = 'dbname=caldav port=5433 user=general'; + $c->pg_connect[] = 'dbname=caldav 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 rscds -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: