A basic website describing the project with installation and configuration

details.
This commit is contained in:
Andrew McMillan 2006-10-25 21:47:59 +13:00
parent 69ea65e72f
commit fd71ade879
8 changed files with 585 additions and 0 deletions

76
docs/website/clients.php Normal file
View File

@ -0,0 +1,76 @@
<?php
$title = "RSCDS Home";
include("inc/page-header.php");
?>
<h1>Evolution</h1>
<p>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.
<ol>
<li><span class="prompt">Type:</span>CalDAV</li>
<li><span class="prompt">Name:</span>Give the calendar a local name</li>
<li><span class="prompt">URL:</span>caldav://server.domain.name/caldav.php/$username/</li>
<li><span class="prompt">Use SSL:</span>if your server is using SSL you should check this, but there may be bugs in Evolution's handling of SSL.</li>
<li><span class="prompt">Username:</span>$username</li>
</ol>
</p>
<p>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.
</p>
<p>Sometimes evolution writes error messages into the cache file, so if you have ongoing problems you may want to
take a look inside that.</p>
<p>There are some quirks with Evolution's handling of CalDAV too, so perhaps take a look at the following
bugs:
<ul>
<li><a href="http://bugzilla.gnome.org/show_bug.cgi?id=355659">New appointments disappear for 1 minute, and then reappear</a></li>
<li><a href="http://bugzilla.gnome.org/show_bug.cgi?id=354855">Support Response with Relative URLs</a></li>
</ul>
Hopefully those will be fixed before too long...
</p>
<h1>Sunbird / Lightning</h1>
<p>The Mozilla calendar project offers their calendar under two different names: <em>Sunbird</em> is a standalone calendar
application, and <em>Lightning</em> 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.
<ol>
<li>Select "New Calendar" from the "File" menu.</li>
<li>Choose "On the Network" (click "Next")</li>
<li>Choose a format of "CalDAV" and enter a URL like: "caldav://calendar.example.net/caldav.php/username/" (click "Next")</li>
<li>Give the calendar an appropriate display name, and choose a colour for events on this calendar. (click "Next")</li>
<li>click "Finish"</li>
</ol>
</p>
<p>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.</p>
<p>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.
</p>
<h1>Mulberry</h1>
<p>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.
<ol>
<li>Select "Preferences" from the "File" menu.</li>
<li>Choose the "Accounts" tab</li>
<li>Select "New" from the "Account" drop-down and a "Create New Account" dialog will appear.</li>
<li>Enter a name for the account, choose "CalDAV Calendar" for the type and click "OK"</li>
<li>In the "Server" field enter the domain name of your CalDAV server, such as "calendar.example.net"</li>
<li>In the "Authentication" pane of the "Accounts" tab, enter your username.</li>
<li>In the "Options" pane of the "Accounts" tab, enter the path, which should be "/caldav.php/"</li>
<li>"OK" the preferences dialog</li>
<li>A list of the users and resources which you are allowed to access should appear. Some may contain calendars.</li>
<li>If you don't already have a calendar for your own user, ensure your username is highlighted and choose "Create" from the "Calendar" menu.</li>
<li>Once you have a calendar created, you need to <em>subscribe to it. One way is to right-click on it and choose 'Subscribe'.</em></li>
</ol>
</p>
<p>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.</p>
<p>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 <em>just fine</em> when I followed
them to the letter the next day. Go figure. I think I need to record some screenshots of this one...</p>
<?php
include("inc/page-footer.php");
?>

Binary file not shown.

After

Width:  |  Height:  |  Size: 3.3 KiB

View File

@ -0,0 +1,19 @@
</div>
<div id="footer">
<br />
<p class="left" style="vertical-align: text-top;">
<a href="http://validator.w3.org/check?uri=referer" class="flink">XHTML</a> | <a href="http://jigsaw.w3.org/css-validator/check/referer" class="flink">CSS</a>
</p>
<p class="right">
Copyright 2006 | Andrew McMillan
</p>
<p align="center">
<a href="http://sourceforge.net"><img src="http://sflogo.sourceforge.net/sflogo.php?group_id=179845&amp;type=2" width="125" height="37" border="0" alt="SourceForge.net Logo" /></a>
</p>
</div>
</div>
</body>
</html>

View File

@ -0,0 +1,33 @@
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
<html xmlns="http://www.w3.org/1999/xhtml">
<head>
<meta http-equiv="Content-Type" content="text/html; charset=UTF-8" />
<title>Really Simple CalDAV Store<?php
if ( isset($title) ) {
echo " - ". $title;
}
?></title>
<link rel="stylesheet" type="text/css" href="style.css" />
</head>
<body>
<div id="pageContainer">
<div id="header">
<div id="title"><?php
if ( isset($title) ) {
echo $title;
}
else {
echo "Really Simple CalDAV Store";
}
?></div>
<div id="subTitle">Really Simple CalDAV Store</div>
<div id="headerLinks">
<a href="index.php" class="hlink">Home</a> |
<a href="installation.php" class="hlink">Installation</a> |
<a href="clients.php" class="hlink">Client Config</a> |
<a href="http://andrew.mcmillan.net.nz/" class="hlink">Andrew McMillan's Blog</a> |
<a href="http://sourceforge.net/projects/rscds/" class="hlink">RSCDS on Sourceforge</a>
</div>
</div>
<div id="pageContent">
<hr />

68
docs/website/index.php Normal file
View File

@ -0,0 +1,68 @@
<?php
$title = "RSCDS Home";
include("inc/page-header.php");
?>
<h1>Background</h1>
<p>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.
</p>
<p>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.</p>
<h1>Goals</h1>
<p>CalDAV is a client-server protocol specific to managing and reporting on <em>collections</em> of <em>calendar resources</em>.</p>
<p>As such, my intentions in developing this application are as follows:
<ul>
<li>Simplicity of Prerequisites</li>
<li>Simplicity of Setup</li>
<li>Simplicity of Operation</li>
<li>Web-based Administration</li>
</ul>
</p>
<h2>Simplicity of Prerequisites</h2>
<p>I have chosen to write this in PHP because I believe that PHP is a widely available web scripting language.</p>
<p>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.</p>
<p>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 <em>fully</em> ACID compliant.</p>
<h2>Simplicity of Setup</h2>
<p>I use the <a href="http://www.debian.org/">Debian GNU/Linux</a> distribution, so at this stage I have made Debian packages available. If
I find willing people I will make packages available in other forms.</p>
<p>This goal is not expected to be achieved in the first few releases.</p>
<h2>Simplicity of Operation</h2>
<p>In general RSCDS should not need significant maintenance to keep it operating.</p>
<p>Administrative functionality will be kept as simple as possible, within the target of supporting
organisations of up to several hundred staff.</p>
<p>This is called a <em>Store</em> rather than a <em>Server</em> 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.</p>
<h2>Web-based Administration</h2>
<p>General administration of the system should be through a web-based application.</p>
<p>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.</p>
<h1>Credits</h1>
<p>The Really Simple CalDAV Store was conceived and written by <a href="http://andrew.mcmillan.net.nz/">Andrew McMillan</a>.</p>
<h1>Your Name Here!</h1>
<p>If you are interested in helping, there are several areas where I need help at the moment:
<ul>
<li>The project needs a better name - feel free to suggest one!</li>
<li>We need more documentation</li>
<li>The graphic and UI design for the web-based administration is teh suck (but it is basically functional :-)</li>
<li>We need more documentation</li>
<li>I need to find more CalDAV-capable calendar clients to interoperate with</li>
</ul>
</p>
<?php
include("inc/page-footer.php");
?>

View File

@ -0,0 +1,161 @@
<?php
$title = "Installation";
include("inc/page-header.php");
?>
<h1>Before Starting</h1>
<p>Ideally you will be running a recent Debian release and will
be able to add:</p>
<pre>
deb http://debian.mcmillan.net.nz/debian unstable awm
</pre>
<p>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.</p>
<p>Skip to the "Database Setup" part if you have done that already.</p>
<h1>Pre-requisites</h1>
<p>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.</p>
<p>The following other software is also needed:
<ul>
<li>Apache: 1.3.x or 2.x.x</li>
<li>PHP: 4.3 or greater, including PHP5</li>
<li>PostgreSQL: 7.4 or greater</li>
</ul>
</p>
<p>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.</p>
<p>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.</p>
<h1>Database Setup</h1>
<p>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.</p>
<p>To create the database itself, run the script:</p>
<pre>
dba/create_database.sh
</pre>
<p>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.</p>
<p>This script also expects to be running as a user who has rights
to create a new database.</p>
<h1>Apache VHost Configuration</h1>
<p>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.</p>
<p>I use a Virtual Host stanza like this:</p>
<pre>
#
# Virtual Host def for Debian packaged RSCDS
&lt;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
&lt;/VirtualHost>
</pre>
<p>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).</p>
<p>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.</p>
<p>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.</p>
<p>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.</p>
<h1>RSCDS Configuration</h1>
<p>The RSCDS configuration generally resides in /etc/rscds/<domain>-conf.php
and is a regular PHP file which sets (or overrides) some specific variables.</p>
<pre>
&lt;?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';
?>
</pre>
<p>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.</p>
<p>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.</p>
<p>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.</p>
<h1>Completed?</h1>
<p>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:</p>
<pre>
psql rscds -c 'select username, password from usr;'
</pre>
<p>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.</p>
<p>If all is working then you should be ready to configure a client
to use this, and the docs for that are elsewhere.</p>
<?php
include("inc/page-footer.php");
?>

214
docs/website/style.css Normal file
View File

@ -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;
}

View File

@ -89,5 +89,19 @@
<item url="htdocs/relationship_types.php" uploadstatus="1" /> <item url="htdocs/relationship_types.php" uploadstatus="1" />
<item url="dba/patches/0.99.1.sql" uploadstatus="1" /> <item url="dba/patches/0.99.1.sql" uploadstatus="1" />
<item url="dba/patches/" uploadstatus="1" /> <item url="dba/patches/" uploadstatus="1" />
<item url="INSTALL" />
<item url="README" />
<item url="TODO" />
<item url="docs/" />
<item url="docs/website/installation.php" />
<item url="docs/website/" />
<item url="docs/website/index.php" />
<item url="docs/website/inc/page-header.php" />
<item url="docs/website/inc/" />
<item url="docs/website/inc/page-footer.php" />
<item url="docs/website/style.css" />
<item url="docs/website/news.php" />
<item url="docs/website/background.php" />
<item url="docs/website/clients.php" />
</project> </project>
</webproject> </webproject>