mirror of
https://github.com/Kozea/Radicale.git
synced 2025-06-26 16:45:52 +00:00
Creation of the documentation repository
This commit is contained in:
Guillaume Ayoub
commit
d8df38f4d7
9 changed files with 446 additions and 0 deletions
1
.gitignore
vendored
Normal file
1
.gitignore
vendored
Normal file
|
|
@ -0,0 +1 @@
|
||||||
|
!*.rst
|
||||||
7
contribute.rst
Normal file
7
contribute.rst
Normal file
|
|
@ -0,0 +1,7 @@
|
||||||
|
============
|
||||||
|
Contribute
|
||||||
|
============
|
||||||
|
|
||||||
|
You want to contribute? Please contact ``guillaume.ayoub[a]kozea.fr``.
|
||||||
|
|
||||||
|
Development tools (bugtracker, wiki, etc.) will be soon available.
|
||||||
29
documentation.rst
Normal file
29
documentation.rst
Normal file
|
|
@ -0,0 +1,29 @@
|
||||||
|
===============
|
||||||
|
Documentation
|
||||||
|
===============
|
||||||
|
|
||||||
|
User documentation
|
||||||
|
==================
|
||||||
|
|
||||||
|
This document gives describes how to install and configure the server.
|
||||||
|
|
||||||
|
- `User documentation (HTML) </user_documentation>`_
|
||||||
|
- User documentation (PDF - soon)
|
||||||
|
|
||||||
|
Project description
|
||||||
|
===================
|
||||||
|
|
||||||
|
This document defines the main goals of the Radicale Project, what it covers
|
||||||
|
and what it does not.
|
||||||
|
|
||||||
|
- `Project description (HTML) </project_description>`_
|
||||||
|
- Project description (PDF - soon)
|
||||||
|
|
||||||
|
Technical choices
|
||||||
|
=================
|
||||||
|
|
||||||
|
This document describes the global technical choices of the Radicale Project
|
||||||
|
and the global architectures of its different parts.
|
||||||
|
|
||||||
|
- `Technical choices (HTML) </technical_choices>`_
|
||||||
|
- Technical choices (PDF - soon)
|
||||||
23
download.rst
Normal file
23
download.rst
Normal file
|
|
@ -0,0 +1,23 @@
|
||||||
|
==========
|
||||||
|
Download
|
||||||
|
==========
|
||||||
|
|
||||||
|
Git Repository
|
||||||
|
==============
|
||||||
|
|
||||||
|
The Radicale Server is not stable yet, but you can try it now. Take a look at
|
||||||
|
the `git repository on Gitorious
|
||||||
|
<http://www.gitorious.org/radicale/radicale>`_, or clone it thanks to::
|
||||||
|
|
||||||
|
git clone git://gitorious.org/radicale/radicale.git
|
||||||
|
|
||||||
|
Source Packages
|
||||||
|
===============
|
||||||
|
|
||||||
|
Source packages will be available soon.
|
||||||
|
|
||||||
|
Linux Distribution Packages
|
||||||
|
===========================
|
||||||
|
|
||||||
|
If you are interested in creating packages for Linux distributions, read the
|
||||||
|
`"Contribute" page </contribute>`_.
|
||||||
20
home.rst
Normal file
20
home.rst
Normal file
|
|
@ -0,0 +1,20 @@
|
||||||
|
====================================
|
||||||
|
Radicale, a Simple Calendar Server
|
||||||
|
====================================
|
||||||
|
|
||||||
|
The Radicale Project is a complete CalDAV calendar server solution. It can
|
||||||
|
store multiple calendars.
|
||||||
|
|
||||||
|
Calendars are available from both local and distant accesses, possibly limited
|
||||||
|
through authentication policies.
|
||||||
|
|
||||||
|
General description
|
||||||
|
===================
|
||||||
|
|
||||||
|
The Radicale Project aims to be a light solution, easy to use, easy to install,
|
||||||
|
easy to configure. As a consequence, it requires few software dependances and
|
||||||
|
is pre-configured to work out-of-the-box.
|
||||||
|
|
||||||
|
The Radicale Project runs on most of the UNIX-like platforms (Linux, \*BSD,
|
||||||
|
MacOS X) and Windows. It is free and open-source software, released under GPL
|
||||||
|
version 3.
|
||||||
16
news.rst
Normal file
16
news.rst
Normal file
|
|
@ -0,0 +1,16 @@
|
||||||
|
======
|
||||||
|
News
|
||||||
|
======
|
||||||
|
|
||||||
|
Tuesday, July 28
|
||||||
|
================
|
||||||
|
|
||||||
|
Radicale code has been released on Gitorious! Take a look at the `Radicale main
|
||||||
|
page on Gitorious <http://www.gitorious.org/radicale>`_ to view and download
|
||||||
|
source code.
|
||||||
|
|
||||||
|
Monday, July 27
|
||||||
|
===============
|
||||||
|
|
||||||
|
The Radicale Project is launched. The code has been cleaned up and will be
|
||||||
|
available soon…
|
||||||
105
project_description.rst
Normal file
105
project_description.rst
Normal file
|
|
@ -0,0 +1,105 @@
|
||||||
|
=====================
|
||||||
|
Project Description
|
||||||
|
=====================
|
||||||
|
|
||||||
|
:Author: Guillaume Ayoub
|
||||||
|
|
||||||
|
:Date: 2009-07-21
|
||||||
|
|
||||||
|
:Abstract: This document defines the main goals of the Radicale
|
||||||
|
Project, what it covers and what it does not.
|
||||||
|
|
||||||
|
.. contents::
|
||||||
|
|
||||||
|
Main Goals
|
||||||
|
==========
|
||||||
|
|
||||||
|
The Radicale Project is a complete calendar storing and manipulating
|
||||||
|
solution. It can store multiple calendars.
|
||||||
|
|
||||||
|
Calendar manipulation is available from both local and distant
|
||||||
|
accesses, possibly limited through authentification policies and
|
||||||
|
calendar-based rules.
|
||||||
|
|
||||||
|
|
||||||
|
What Radicale Is
|
||||||
|
================
|
||||||
|
|
||||||
|
Calendar Server
|
||||||
|
---------------
|
||||||
|
|
||||||
|
The Radicale Project is mainly a calendar server, giving local and
|
||||||
|
distant accessess for reading, creating, modifying and deleting
|
||||||
|
multiple calendars.
|
||||||
|
|
||||||
|
What Radicale will Be
|
||||||
|
=====================
|
||||||
|
|
||||||
|
Calendar Access Rights Manager
|
||||||
|
------------------------------
|
||||||
|
|
||||||
|
Different users, identified by authentification, can have different
|
||||||
|
rights of reading, creating, modifying and deleting calendars. These
|
||||||
|
rights are defined through the administration interfaces.
|
||||||
|
|
||||||
|
Calendar Server Console-Based Administration Interface
|
||||||
|
------------------------------------------------------
|
||||||
|
|
||||||
|
This is a console-based interface to add and remove calendars and manage
|
||||||
|
rights, useful for remote servers.
|
||||||
|
|
||||||
|
Calendar Server Web-Based Administration Interface
|
||||||
|
--------------------------------------------------
|
||||||
|
|
||||||
|
This is a web-based interface to add and remove calendars and manage
|
||||||
|
rights, useful for remote servers.
|
||||||
|
|
||||||
|
Calendar Server Graphical Administration Interface
|
||||||
|
--------------------------------------------------
|
||||||
|
|
||||||
|
This is a toolkit-based (GTK+, Qt, whatever…) interface to add and remove
|
||||||
|
calendars and manage rights, useful for local servers.
|
||||||
|
|
||||||
|
|
||||||
|
What Radicale Is not and will not Be
|
||||||
|
====================================
|
||||||
|
|
||||||
|
Calendar User Agent
|
||||||
|
-------------------
|
||||||
|
|
||||||
|
Radicale is a server, not a client. No interfaces will be created to work with
|
||||||
|
the server, as it is a really (really really) much more difficult task [#]_.
|
||||||
|
|
||||||
|
.. [#] I repeat: `we are lazy <http://www.radicale.org/technical_choices#lazy>`_.
|
||||||
|
|
||||||
|
Original Calendar Store Implementation
|
||||||
|
--------------------------------------
|
||||||
|
|
||||||
|
Radicale stores iCal files, and nothing else. No easy way to store anything
|
||||||
|
else, as our iCal library does not know anything of the iCal norm: it just
|
||||||
|
recieves iCal strings from the client and stores it after a really minimal
|
||||||
|
parsing.
|
||||||
|
|
||||||
|
Radicale has no idea of most of the iCal semantics. No joke! Dates, timezones,
|
||||||
|
titles, contents, status, repetitions are never understood, they are just
|
||||||
|
stored and replied as they are sent by the client. This is why storing anything
|
||||||
|
but iCal files (databases, Evolution Data Server, etc.) is impossible with
|
||||||
|
Radicale.
|
||||||
|
|
||||||
|
Original Calendar Access Protocol
|
||||||
|
---------------------------------
|
||||||
|
|
||||||
|
CalDAV is not a perfect protocol. We think that its main default is its
|
||||||
|
complexity [#]_, that is why we decided not to implement the whole standard but
|
||||||
|
just enough to understand some of its client-side implementations [#]_.
|
||||||
|
|
||||||
|
CalDAV is not a perfect protocol, but it is the best open standard available
|
||||||
|
and is quite widely used by both clients and servers [#]_. We decided to use it,
|
||||||
|
and we will not use another one.
|
||||||
|
|
||||||
|
.. [#] Try to read :RFC:`4791`. Then try to understand it. Then try to
|
||||||
|
implement it. Then try to read it again.
|
||||||
|
.. [#] Radicale is `oriented to calendar user agents
|
||||||
|
<http://www.radicale.org/technical_choices#oriented-to-calendar-user-agents>`_.
|
||||||
|
.. [#] `Popularity of CalDAV <http://en.wikipedia.org/wiki/CalDAV#Popularity>`_,
|
||||||
|
by Wikipedia.
|
||||||
154
technical_choices.rst
Normal file
154
technical_choices.rst
Normal file
|
|
@ -0,0 +1,154 @@
|
||||||
|
===================
|
||||||
|
Technical Choices
|
||||||
|
===================
|
||||||
|
|
||||||
|
:Author: Guillaume Ayoub
|
||||||
|
|
||||||
|
:Date: 2009-07-21
|
||||||
|
|
||||||
|
:Abstract: This document describes the global technical choices of the
|
||||||
|
Radicale Project and the global architectures of its different parts.
|
||||||
|
|
||||||
|
.. contents::
|
||||||
|
|
||||||
|
Global Technical Choices
|
||||||
|
========================
|
||||||
|
|
||||||
|
General Description
|
||||||
|
-------------------
|
||||||
|
|
||||||
|
The Radicale Project aims to be a light solution, easy to use, easy to
|
||||||
|
install, easy to configure. As a consequence, it requires few software
|
||||||
|
dependances and is pre-configured to work out-of-the-box.
|
||||||
|
|
||||||
|
The Radicale Project runs on most of the UNIX-like platforms (Linux,
|
||||||
|
\*BSD, MacOS X) and Windows. It is free and open-source software.
|
||||||
|
|
||||||
|
Language
|
||||||
|
--------
|
||||||
|
|
||||||
|
The different parts of the Radicale Project are written in
|
||||||
|
Python. This is a high-level language, fully object-oriented,
|
||||||
|
available for the main operating systems and released with a lot of
|
||||||
|
useful libraries.
|
||||||
|
|
||||||
|
Protocols and Formats
|
||||||
|
---------------------
|
||||||
|
|
||||||
|
The main protocols and formats fully or partially implemented in the
|
||||||
|
Radicale Project are described by RFCs:
|
||||||
|
|
||||||
|
- iCalendar format (iCal) :RFC:`2445`
|
||||||
|
- HTTP Extensions for Distributed Authoring (WebDAV) :RFC:`2518`
|
||||||
|
- HyperText Transfer Protocol (HTTP) :RFC:`2616`
|
||||||
|
- WebDAV Access Control Protocol (ACL) :RFC:`3744`
|
||||||
|
- Calendaring Extensions to WebDAV (CalDAV) :RFC:`4791`
|
||||||
|
- HTTP Extensions for Web Distributed Authoring and Versioning
|
||||||
|
(WebDAV) :RFC:`4918`
|
||||||
|
- Transport Layer Security (TLS) :RFC:`5246`
|
||||||
|
|
||||||
|
.. note::
|
||||||
|
CalDAV implementation **requires** iCal, ACL, WebDAV, HTTP and TLS. The
|
||||||
|
Radicale Server **does not and will not implement correctly** these
|
||||||
|
standards, as explained in the `Development Choices`_ part.
|
||||||
|
|
||||||
|
Development Choices
|
||||||
|
-------------------
|
||||||
|
|
||||||
|
Important global development choices have been decided before writing
|
||||||
|
code. They are very useful to understand why the Radicale Project is
|
||||||
|
different from other CalDAV servers, and why features are included or
|
||||||
|
not in the code.
|
||||||
|
|
||||||
|
Oriented to Calendar User Agents
|
||||||
|
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
|
||||||
|
|
||||||
|
Calendar servers work with calendar clients, using a defined protocol. CalDAV
|
||||||
|
is a good protocol, covering lots of features and use cases, but it is quite
|
||||||
|
hard to implement fully.
|
||||||
|
|
||||||
|
Some calendar servers have been created to follow the CalDAV RFC as much as
|
||||||
|
possible: Cosmo [#]_ and Darwin Calendar Server [#]_, for example, are much
|
||||||
|
more respectful of CalDAV and can be used with a large number of clients. They
|
||||||
|
are very good choices if you want to develop and test new CalDAV clients, or if
|
||||||
|
you have a possibly heterogeneous list of user agents.
|
||||||
|
|
||||||
|
The Radicale Server does not and **will not** support the CalDAV standard. It
|
||||||
|
supports the CalDAV implementation of different clients (only Sunbird 0.9+ [#]_ and
|
||||||
|
Lightning 0.9+ [#]_ for the moment).
|
||||||
|
|
||||||
|
.. [#] `Cosmo <http://chandlerproject.org/Projects/CosmoHome>`_, the web
|
||||||
|
contents and calendars sharing server build to support the Chandler Project.
|
||||||
|
|
||||||
|
.. [#] `Darwin Calendar Server <http://trac.calendarserver.org/>`_, a
|
||||||
|
standards-compliant calendar server mainly developped by Apple.
|
||||||
|
|
||||||
|
.. [#] `Mozilla Sunbird <http://www.mozilla.org/projects/calendar/sunbird/>`_,
|
||||||
|
a cross-platform calendar client built upon Mozilla Toolkit.
|
||||||
|
|
||||||
|
.. [#] `Lightning <http://www.mozilla.org/projects/calendar/lightning/>`_, a
|
||||||
|
calendar plugin bringing Sunbird in Mozilla Thunderbird.
|
||||||
|
|
||||||
|
Simple
|
||||||
|
~~~~~~
|
||||||
|
|
||||||
|
The Radicale Server is designed to be simple to install, simple to configure,
|
||||||
|
simple to use.
|
||||||
|
|
||||||
|
The installation is very easy, particularly with Linux: few dependances, no
|
||||||
|
superuser rights needed, no configuration required. Launching the main script
|
||||||
|
out-of-the-box, as anormal user, is often the only step to have a simple remote
|
||||||
|
calendar access.
|
||||||
|
|
||||||
|
Contrary to other servers that are often complicated, require high privileges
|
||||||
|
or need a strong configuration, the Radicale Server can (sometimes, if not
|
||||||
|
often) be launched in a couple of minutes, if you follow the `User
|
||||||
|
Documentation <http://www.radicale.org/user_documentation>`_.
|
||||||
|
|
||||||
|
Lazy
|
||||||
|
~~~~
|
||||||
|
|
||||||
|
We, Radicale Project developpers, are lazy. That is why we have chosen Python:
|
||||||
|
no more ``;`` or ``{}`` [#]_. This is also why our server is lazy.
|
||||||
|
|
||||||
|
The CalDAV RFC defines what must be done, what can be done and what cannot be
|
||||||
|
done. Many violations of the protocol are totally defined and behaviours are
|
||||||
|
given in such cases.
|
||||||
|
|
||||||
|
The Radicale Server assumes that the clients are perfect and that protocole
|
||||||
|
violations do not exist. That is why most of the errors in client requests have
|
||||||
|
undetermined consequences for the lazy server that can reply good answers, bad
|
||||||
|
answers, or even no answer.
|
||||||
|
|
||||||
|
.. [#] Who says "Ruby is even less verbose!" should read the
|
||||||
|
:PEP:`20`.
|
||||||
|
|
||||||
|
Architectures
|
||||||
|
=============
|
||||||
|
|
||||||
|
General Architecture
|
||||||
|
--------------------
|
||||||
|
|
||||||
|
Here is a simple overview of the global architecture for reaching a
|
||||||
|
calendar through network:
|
||||||
|
|
||||||
|
+-----------+-----------------+---------------------+
|
||||||
|
| Part | Layer | Protocol or Format |
|
||||||
|
+===========+=================+=====================+
|
||||||
|
| Server | Calendar Store | iCal |
|
||||||
|
| +-----------------+---------------------+
|
||||||
|
| | Calendar Server | CalDAV Server |
|
||||||
|
+-----------+-----------------+---------------------+
|
||||||
|
| Transfert | Network | CalDAV (HTTP + TLS) |
|
||||||
|
+-----------+-----------------+---------------------+
|
||||||
|
| Client | Calendar Client | CalDAV Client |
|
||||||
|
| +-----------------+---------------------+
|
||||||
|
| | GUI | Terminal, GTK, etc. |
|
||||||
|
+-----------+-----------------+---------------------+
|
||||||
|
|
||||||
|
The Radical Project is **only the server part** of this architecture.
|
||||||
|
|
||||||
|
Code Architecture
|
||||||
|
-----------------
|
||||||
|
|
||||||
|
*To be written…*
|
||||||
91
user_documentation.rst
Normal file
91
user_documentation.rst
Normal file
|
|
@ -0,0 +1,91 @@
|
||||||
|
====================
|
||||||
|
User Documentation
|
||||||
|
====================
|
||||||
|
|
||||||
|
:Author: Guillaume Ayoub
|
||||||
|
|
||||||
|
:Date: 2009-07-21
|
||||||
|
|
||||||
|
:Abstract: This document is a short description for installing and using the
|
||||||
|
Radicale Calendar Server.
|
||||||
|
|
||||||
|
.. contents::
|
||||||
|
|
||||||
|
Installation
|
||||||
|
============
|
||||||
|
|
||||||
|
Dependencies
|
||||||
|
------------
|
||||||
|
|
||||||
|
Radicale is written in pure python and depends on the following librabry, that
|
||||||
|
must be installed first:
|
||||||
|
|
||||||
|
- ``python-twisted-web``
|
||||||
|
|
||||||
|
On a Debian-based systems, you can install this packages with the following
|
||||||
|
command, with superuser rights::
|
||||||
|
|
||||||
|
apt-get install python-twisted-web
|
||||||
|
|
||||||
|
Other Linux and \*BSD distributions should provide Twisted packages too.
|
||||||
|
|
||||||
|
For Windows and MacOS users, please install Python [#]_ and Twisted [#]_ thanks
|
||||||
|
to the adequate installers. Version 2.6.\* for Python is a good choice.
|
||||||
|
|
||||||
|
.. [#] `Python download page <http://python.org/download/>`_.
|
||||||
|
.. [#] `Twisted download page <http://twistedmatrix.com/trac/wiki/Downloads>`_.
|
||||||
|
|
||||||
|
Radicale
|
||||||
|
--------
|
||||||
|
|
||||||
|
Radicale can be freely downloaded on the `project website, download section
|
||||||
|
<http://www.radicale.org/download>`_. Just get the file and unzip it in a
|
||||||
|
folder of your choice.
|
||||||
|
|
||||||
|
CalDAV Clients
|
||||||
|
--------------
|
||||||
|
|
||||||
|
At this time Radicale has been tested and works fine with the latest version of
|
||||||
|
Mozilla Sunbird (version 0.9+). More clients will be supported in the
|
||||||
|
future. However, it may work with any calendar client which implements CalDAV
|
||||||
|
specifications too (luck is highly recommanded).
|
||||||
|
|
||||||
|
To download Sunbird, go to the `Sunbird project website
|
||||||
|
<http://www.mozilla.org/projects/calendar/sunbird/>`_ and choose the latest
|
||||||
|
version. Follow the instructions depending on your operating system.
|
||||||
|
|
||||||
|
|
||||||
|
Simple Usage
|
||||||
|
============
|
||||||
|
|
||||||
|
Starting Server
|
||||||
|
---------------
|
||||||
|
|
||||||
|
To start Radicale CalDAV server, you have to launch the file called
|
||||||
|
``radicale.py`` located in the root folder of the software.
|
||||||
|
|
||||||
|
Using Sunbird
|
||||||
|
-------------
|
||||||
|
|
||||||
|
After starting Sunbird, click on ``File`` and ``New Calendar``. Upcoming window
|
||||||
|
asks you about your calendar storage. Chose a calendar ``On the Network``,
|
||||||
|
otherwise Sunbird will use its own file system storage instead of Radicale's
|
||||||
|
one and your calendar won't be remotely accessible.
|
||||||
|
|
||||||
|
Next window asks you to provide information about remote calendar
|
||||||
|
access. Protocol used by Radicale is ``CalDAV``. Standard location for a basic
|
||||||
|
use of a Radicale calendar is ``http://localhost:5232/radicale/calendar``.
|
||||||
|
|
||||||
|
You can now customize your calendar by giving it a nickname and a color. This
|
||||||
|
is only used by Sunbird to identify calendars among others.
|
||||||
|
|
||||||
|
If no warning sign appears next to the calendar name, you can now add events
|
||||||
|
and tasks to your calendar. All events and tasks are stored in the server, they
|
||||||
|
can be accessed and modified from multiple clients by multiple users at the
|
||||||
|
same time.
|
||||||
|
|
||||||
|
|
||||||
|
Complex Configuration
|
||||||
|
=====================
|
||||||
|
|
||||||
|
*To be written…*
|
||||||
Loading…
Add table
Add a link
Reference in a new issue