diff --git a/docs/website/clients.php b/docs/website/clients.php new file mode 100644 index 00000000..43284476 --- /dev/null +++ b/docs/website/clients.php @@ -0,0 +1,76 @@ + +

Evolution

+

Novell Evolution is available in most Linux distributions. The CalDAV support was supposedly written +in a frenzy of hacking one day when the draft specification was at around revision 8. As a result there +was little in the way of a client available to test against until recently. +

    +
  1. Type:CalDAV
    2. +
  2. Name:Give the calendar a local name
    3. +
  3. URL:caldav://server.domain.name/caldav.php/$username/
    4. +
  4. Use SSL:if your server is using SSL you should check this, but there may be bugs in Evolution's handling of SSL.
    5. +
  5. Username:$username
    6. +
+

+

If you have problems with Evolution, you will need to quit evolution, remove the cache file which will be in ~/.evolution/cache/calendar/ and +restart. If you still have problems try doing that, but killing evolution-data-server in addition. +

+

Sometimes evolution writes error messages into the cache file, so if you have ongoing problems you may want to +take a look inside that.

+

There are some quirks with Evolution's handling of CalDAV too, so perhaps take a look at the following +bugs: +

+Hopefully those will be fixed before too long... +

+ +

Sunbird / Lightning

+

The Mozilla calendar project offers their calendar under two different names: Sunbird is a standalone calendar +application, and Lightning is a Thunderbird extension. The two are essentially the same, as far as RSCDS is +concerned, and these instructions should work for either of them. +

    +
  1. Select "New Calendar" from the "File" menu.
    2. +
  2. Choose "On the Network" (click "Next")
    3. +
  3. Choose a format of "CalDAV" and enter a URL like: "caldav://calendar.example.net/caldav.php/username/" (click "Next")
    4. +
  4. Give the calendar an appropriate display name, and choose a colour for events on this calendar. (click "Next")
    5. +
  5. click "Finish"
    6. +
+

+

At version 0.3 the Mozilla calendar does not automatically refresh the calendar view, so if someone else has +added a meeting you will have to manually refresh the view to see that.

+

It is early days yet for the Mozilla calendar in it's current incarnation so no doubt there are other quirks +with Mozilla's handling of CalDAV too, so perhaps take a look at their bugzilla. +

+ +

Mulberry

+

Mulberry is the most well-behaved of the applications I have been able to use. It does have some +bugs, however, and a particular annoyance around it's use of non-standard names for time zones. Mulberry +is the only client I have used so far which can issue a MKCALENDAR command or which will display a +hierarchy of calendars from one configured URL. +

    +
  1. Select "Preferences" from the "File" menu.
    2. +
  2. Choose the "Accounts" tab
    3. +
  3. Select "New" from the "Account" drop-down and a "Create New Account" dialog will appear.
    4. +
  4. Enter a name for the account, choose "CalDAV Calendar" for the type and click "OK"
    5. +
  5. In the "Server" field enter the domain name of your CalDAV server, such as "calendar.example.net"
    6. +
  6. In the "Authentication" pane of the "Accounts" tab, enter your username.
    7. +
  7. In the "Options" pane of the "Accounts" tab, enter the path, which should be "/caldav.php/"
    8. +
  8. "OK" the preferences dialog
    9. +
  9. A list of the users and resources which you are allowed to access should appear. Some may contain calendars.
    10. +
  10. If you don't already have a calendar for your own user, ensure your username is highlighted and choose "Create" from the "Calendar" menu.
    11. +
  11. Once you have a calendar created, you need to subscribe to it. One way is to right-click on it and choose 'Subscribe'.
    12. +
+

+

Unfortunately Mulberry is not open-source, though it is free, so we must wait on the developer to fix +the user interface niggles when he gets around to it.

+

Note that Mulberry has a complex user interface. When I wrote this I went back into Mulberry and initially thought that RSCDS had regressed +somewhat and that these instructions didn't exactly work... :-) It turned out that these instructions worked just fine when I followed +them to the letter the next day. Go figure. I think I need to record some screenshots of this one...

+ + \ No newline at end of file diff --git a/docs/website/images/logo.gif b/docs/website/images/logo.gif new file mode 100644 index 00000000..c96e8f7b Binary files /dev/null and b/docs/website/images/logo.gif differ diff --git a/docs/website/inc/page-footer.php b/docs/website/inc/page-footer.php new file mode 100644 index 00000000..b2463703 --- /dev/null +++ b/docs/website/inc/page-footer.php @@ -0,0 +1,19 @@ + + + + + + + diff --git a/docs/website/inc/page-header.php b/docs/website/inc/page-header.php new file mode 100644 index 00000000..72ff4dde --- /dev/null +++ b/docs/website/inc/page-header.php @@ -0,0 +1,33 @@ + + + + +Really Simple CalDAV Store<?php +if ( isset($title) ) { + echo " - ". $title; +} +?> + + + +
+ +
+
diff --git a/docs/website/index.php b/docs/website/index.php new file mode 100644 index 00000000..01f9612b --- /dev/null +++ b/docs/website/index.php @@ -0,0 +1,68 @@ + +

Background

+

The CalDAV specification has been under development for a few years now, and at the same time I +have seen increasing pressure from clients to provide a solution to their shared calendaring problems. +

+

In evaluating the possibilities for shared calendaring, there are a number of possible approaches, but +I have elected to follow the path of implementing CalDAV because I believe it is a good specification +and that it will in due course gain client implementations and provide the richest user +experience through those client implementations.

+ +

Goals

+

CalDAV is a client-server protocol specific to managing and reporting on collections of calendar resources.

+

As such, my intentions in developing this application are as follows: +

+

+ +

Simplicity of Prerequisites

+

I have chosen to write this in PHP because I believe that PHP is a widely available web scripting language.

+

I have chosen to use the Apache web server because it is also widely available. This is not necessarily a requirement, +but I do not have other PHP environments available to me at this time.

+

I have chosen to use the PostgreSQL database, because it is a free, open-source database, which operates on a very wide set of +operating environments, and which is fully ACID compliant.

+ +

Simplicity of Setup

+

I use the Debian GNU/Linux distribution, so at this stage I have made Debian packages available. If +I find willing people I will make packages available in other forms.

+

This goal is not expected to be achieved in the first few releases.

+ +

Simplicity of Operation

+

In general RSCDS should not need significant maintenance to keep it operating.

+

Administrative functionality will be kept as simple as possible, within the target of supporting +organisations of up to several hundred staff.

+

This is called a Store rather than a Server because the server-side smarts are intended to be +minimised to support CalDAV only in a manner sufficient to inter-operate with clients, and with the focus primarily +on the storage of calendar resources.

+ +

Web-based Administration

+

General administration of the system should be through a web-based application.

+

Calendars will not be made available in a web-based view in initial releases. It is unlikely that calendars will ever be +maintainable through a web-based client, although the server should support the use of web-based client software which +works using the CalDAV protocol.

+ +

Credits

+

The Really Simple CalDAV Store was conceived and written by Andrew McMillan.

+ + +

Your Name Here!

+

If you are interested in helping, there are several areas where I need help at the moment: +

+

+ + diff --git a/docs/website/installation.php b/docs/website/installation.php new file mode 100644 index 00000000..02197518 --- /dev/null +++ b/docs/website/installation.php @@ -0,0 +1,161 @@ + +

Before Starting

+ +

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: +

+

+

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
+<VirtualHost 123.4.56.78 >
+  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
+</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 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.

+ +
+<?php
+//  $c->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.

+ + diff --git a/docs/website/style.css b/docs/website/style.css new file mode 100644 index 00000000..7282d1d1 --- /dev/null +++ b/docs/website/style.css @@ -0,0 +1,214 @@ +* { + margin: 0px; + padding: 0px; + } + +body { + margin: 0px; + padding: 0px; + background-color: #FFFFFF; + color: #333333; + } + +hr { + height: 0.4em; + width: 100%; + background-color: #000000; + border: none; + color:#000000; + margin-bottom: 0.5em; + } + +#pageContainer { + width: 740px; + margin-left: auto; + margin-right: auto; + } + +#header { + width: 740px; + height: 80px; + background: url(images/logo.gif) #bb1f1f no-repeat center left; + margin-top: 10px; + border-bottom: #d2d2d2 solid 5px; + text-align: right; + margin-bottom: 20px; + } + +#headerLinks { + color: #FFFFFF; + font-family: helvetica, arial, sans-serif; + font-size: 8pt; + font-size: 80%; + padding-top: 60px; + padding-right: 5px; + } + +.hlink:link { + color: #FFFFFF; + font-family: helvetica, arial, sans-serif; + font-size: 8pt; + font-size: 80%; + text-decoration: none; + } + +.hlink:active { + color: #FFFFFF; + font-family: helvetica, arial, sans-serif; + font-size: 8pt; + font-size: 80%; + text-decoration: none; + } + +.hlink:hover { + color: #FFFFFF; + font-family: helvetica, arial, sans-serif; + font-size: 8pt; + font-size: 80%; + text-decoration: underline; + } + +.hlink:visited { + color: #FFFFFF; + font-family: helvetica, arial, sans-serif; + font-size: 8pt; + font-size: 80%; + text-decoration: none; + } + +#pageContent { + /* Not used for anything at present */ + } + +h1 { + color: #600000; + font-family: helvetica, arial, sans-serif; + font-size: 130%; + margin-top: 1em; + margin-bottom: 0.3em; + } + +h2 { + color: black; + font-family: helvetica, arial, sans-serif; + font-size: 110%; + margin-top: 1em; + margin-bottom: 0.3em; + } + +.showcase { + margin: 2px; + padding: 2px; + border: 2px #000000 solid; + } + +p { + font-family: helvetica, arial, sans-serif; + font-size: 8pt; + font-size: 90%; + margin-bottom: 20px; + } + +ol, ul { + margin-bottom: 20px; +} + +ul { + list-style-type: square; +} + +li { + list-style-position: outside; + margin-left: 2em; + font-family: helvetica, arial, sans-serif; + font-size: 90%; + } + +pre { + font-family: courier, courier new, fixed; + font-size: 90%; + padding: 1em; + margin-bottom: 1em; + background-color: #eee; +} + +#footer { + clear: both; + width: 740px; + font-family: helvetica, arial, sans-serif; + font-size: 8pt; + font-size: 80%; + border-top: 2px #000000 solid; + } + +#title { + float: left; + color: #FFFFFF; + padding-left: 100px; + margin-top: 10px; + font-family: helvetica, arial, sans-serif; + font-size: 24pt; + font-size: 200%; + } + +#subTitle { + float: left; + clear: left; + color: #FFFFFF; + padding-left: 102px; + font-family: helvetica, arial, sans-serif; + font-size: 8pt; + font-size: 80%; + } + +.right { + float: right; + margin: 0px; + } + +.left { + float: left; + margin: 0px; + } + +.flink:link { + color: #333333; + font-family: helvetica, arial, sans-serif; + font-size: 8pt; + font-size: 80%; + text-decoration: none; + vertical-align: text-top; + } + +.flink:active { + color: #333333; + font-family: helvetica, arial, sans-serif; + font-size: 8pt; + font-size: 80%; + text-decoration: none; + vertical-align: text-top; + } + +.flink:hover { + color: #333333; + font-family: helvetica, arial, sans-serif; + font-size: 8pt; + font-size: 80%; + text-decoration: underline; + vertical-align: text-top; + } + +.flink:visited { + color: #333333; + font-family: helvetica, arial, sans-serif; + font-size: 8pt; + font-size: 80%; + text-decoration: none; + vertical-align: text-top; + } + +.prompt { + font-weight: 700; + width: 4em; + } + diff --git a/rscds.webprj b/rscds.webprj index 5a66f60e..8e4c6f0d 100644 --- a/rscds.webprj +++ b/rscds.webprj @@ -89,5 +89,19 @@ + + + + + + + + + + + + + +