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