From fd71ade879922032bb3c8f1b2d33d8dc96920db8 Mon Sep 17 00:00:00 2001 From: Andrew McMillan Date: Wed, 25 Oct 2006 21:47:59 +1300 Subject: [PATCH] A basic website describing the project with installation and configuration details. --- docs/website/clients.php | 76 +++++++++++ docs/website/images/logo.gif | Bin 0 -> 3371 bytes docs/website/inc/page-footer.php | 19 +++ docs/website/inc/page-header.php | 33 +++++ docs/website/index.php | 68 ++++++++++ docs/website/installation.php | 161 +++++++++++++++++++++++ docs/website/style.css | 214 +++++++++++++++++++++++++++++++ rscds.webprj | 14 ++ 8 files changed, 585 insertions(+) create mode 100644 docs/website/clients.php create mode 100644 docs/website/images/logo.gif create mode 100644 docs/website/inc/page-footer.php create mode 100644 docs/website/inc/page-header.php create mode 100644 docs/website/index.php create mode 100644 docs/website/installation.php create mode 100644 docs/website/style.css 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 0000000000000000000000000000000000000000..c96e8f7b74ea2f25a921a97111a18e5d3cfa2210 GIT binary patch literal 3371 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 Bqm2Ln literal 0 HcmV?d00001 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
    • +
  • Simplicity of Setup
    • +
  • Simplicity of Operation
    • +
  • Web-based Administration
    • +
+

+ +

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

    +
  • The project needs a better name - feel free to suggest one!
    • +
  • We need more documentation
    • +
  • The graphic and UI design for the web-based administration is teh suck (but it is basically functional :-)
    • +
  • We need more documentation
    • +
  • I need to find more CalDAV-capable calendar clients to interoperate with
    • +
+

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

    +
  • 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
+<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 @@ + + + + + + + + + + + + + +