oss/Radicale
oss/Radicale
1
0
Fork 0
mirror of https://github.com/Kozea/Radicale.git synced 2025-08-01 18:18:31 +00:00
Code Wiki Activity

Add static files and reorganize folders.

Browse source
This commit is contained in:
Guillaume Ayoub 2010-07-29 18:14:40 +02:00
parent 2a962b5af8
commit 5666da1d41
12 changed files with 330 additions and 2 deletions
Download patch file Download diff file Expand all files Collapse all files

23
pages/contribute.rst Normal file
View file

@ -0,0 +1,23 @@
============
Contribute
============
As a Lazy Person
================
Want to write kind words? Please contact guillaume.ayoub[a]kozea.fr.
As a Simple User
================
Found a bug? Want a new feature? Report a new issue on the `Radicale bug-tracker
<http://redmine.kozea.fr/projects/radicale>`_ (registration needed).
As a Hacker
===========
Interested in hacking? Feel free to clone the `git repository on Gitorious
<http://www.gitorious.org/radicale/radicale>`_ if you want to add new features,
fix bugs or update documentation.

26
pages/documentation.rst Normal file
View file

@ -0,0 +1,26 @@
===============
Documentation
===============
User documentation
==================
This document describes how to install and configure the server.
- `User documentation <user_documentation>`_
Project description
===================
This document defines the main goals of the Radicale Project, what it covers
and what it does not.
- `Project description <project_description>`_
Technical choices
=================
This document describes the global technical choices of the Radicale Project
and the global architectures of its different parts.
- `Technical choices <technical_choices>`_

43
pages/download.rst Normal file
View file

@ -0,0 +1,43 @@
==========
Download
==========
PyPI
====
Radicale is `available on PyPI <http://pypi.python.org/pypi/Radicale/>`_. To
install, just type as superuser::
easy_install radicale
Git Repository
==============
If you want the development version of Radicale, 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
You can also download the Radicale package of the git repository:
- `Radicale-git.tar.gz <http://gitorious.org/radicale/radicale/archive-tarball/master>`_
Source Packages
===============
You can download the Radicale package for each release:
- `Radicale-0.3.tar.gz </src/radicale/Radicale-0.3.tar.gz>`_ (22 kio)
- `Radicale-0.2.tar.gz </src/radicale/Radicale-0.2.tar.gz>`_ (22 kio)
- `Radicale-0.1.tar.gz </src/radicale/Radicale-0.1.tar.gz>`_ (20 kio)
Linux Distribution Packages
===========================
Radicale has been packaged for:
- `Debian <http://packages.debian.org/radicale>`_ by Jonas Smedegaard
If you are interested in creating packages for other Linux distributions, read
the `"Contribute" page </contribute>`_.

36
pages/home.rst Normal file
View file

@ -0,0 +1,36 @@
==========================
A Simple Calendar Server
==========================
Presentation
============
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. They can be viewed and edited by a calendar
client such as Sunbird or Evolution.
Technical 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 dependencies 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, written in Python,
released under GPL version 3.
Main Features
=============
- Shares calendars through CalDAV and HTTP
- Supports events and todos
- Works out-of-the-box, no installation nor configuration required
- Warns users on concurrent edition
- Limits access by authentication
- Secures connections

108
pages/project_description.rst Normal file
View file

@ -0,0 +1,108 @@
=====================
Project Description
=====================
:Author: Guillaume Ayoub
:Date: 2010-01-22
: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 authentication policies.
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 through a simplified CalDAV protocol.
Data can be encrypted by SSL, and their access can be restricted thanks to
different authentication methods.
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
receives 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 problem 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.

202
pages/technical_choices.rst Normal file
View file

@ -0,0 +1,202 @@
===================
Technical Choices
===================
:Author: Guillaume Ayoub
:Date: 2010-01-22
: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
dependencies 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+
[#]_, Lightning 0.9+ [#]_ and Evolution [#]_ 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 developed 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.
.. [#] `Evolution <http://projects.gnome.org/evolution/>`_, the default mail,
addressbook and calendaring client for Gnome.
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: no dependencies, no
superuser rights needed, no configuration required. Launching the main script
out-of-the-box, as a normal 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 developers, 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 protocol
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 Storage | iCal |
| +---------------------+--------------------------+
| | Calendar Server | CalDAV Server |
+-----------+---------------------+--------------------------+
| Transfert | Network | CalDAV (HTTP + TLS) |
+-----------+---------------------+--------------------------+
| Client | Calendar Client | CalDAV Client |
| +---------------------+--------------------------+
| | GUI | Terminal, GTK, etc. |
+-----------+---------------------+--------------------------+
The Radicale Project is **only the server part** of this architecture.
Code Architecture
-----------------
The code is split into 2 parts: the module and the server. The module offers
the complex functions to create a CalDAV server, and the server is the
executable using the module to launch the server.
Server
~~~~~~
The server is a simple executable. Its main work is to read the configuration
from the configuration file and from the options given in the command line;
then it creates a server, according to the configuration, thanks to the module.
Module
~~~~~~
The module offers 5 sub-modules.
``__init__``
This is the core part of the module, with the code for the CalDAV server. The
server inherits from a HTTP or HTTPS server class, which relies on the
default HTTP server class given by Python. The code managing the different
HTTP requests according to the CalDAV normalization is written here.
``config``
This part gives a dict-like access to the server configuration, read from
the configuration file. The configuration can be altered when launching the
executable with some command line options.
``ical``
In this sub-module are written the classes to represent calendars and
calendar items in Radicale. The simple iCalendar readers and writers are
included in this file, to read and write requests and internally stored
calendars. The readers and writers are small and stupid: they do not
fully understand the iCalendar format and do not know at all what a date is.
``xmlutils``
The functions defined in this sub-module are mainly called by the CalDAV
server class to read the XML part of the request, read or alter the
calendars, and create the XML part of the response. The main part of this
code relies on ElementTree.
``acl``
This sub-module is a set of Access Control Lists, a set of methods used by
Radicale to manage rights to access the calendars. When the CalDAV server is
launched, an Access Control List is chosen in the set, according to the
configuration. The HTTP requests are then filtered to restrict the access
using a list of login/password-based access controls.

196
pages/user_documentation.rst Normal file
View file

@ -0,0 +1,196 @@
====================
User Documentation
====================
:Author: Guillaume Ayoub
:Date: 2010-02-11
: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 does not depend on any librabry. It is
known to work on Python 2.5, 2.6, 3.0 and 3.1 [#]_.
Linux users certainly have Python already installed. For Windows and MacOS
users, please install Python [#]_ thanks to the adequate installer.
.. [#] See `Python Versions and OS Support`_ for further information.
.. [#] `Python download page <http://python.org/download/>`_.
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 latests version
of Mozilla Sunbird (versions 0.9+), Mozilla Lightning (0.9+), and Evolution
(2.30+). 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 package.
Using Sunbird or Lightning
--------------------------
After starting Sunbird or Lightning, 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``. A standard location for a basic
use of a Radicale calendar is ``http://localhost:5232/user/calendar/``, where
you can replace ``user`` and ``calendar`` by some strings of your
choice. Calendars are automatically created if needed.
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.
Using Evolution
---------------
First of all, show the calendar page in Evolution by clicking on the calendar
icon at the bottom of the side pane. Then add a new calendar by choosing in the
menu ``File``, ``New``, ``Calendar``.
A new window opens. The calendar ``type`` is ``CalDAV``, and the location is
something like ``caldav://localhost:5232/user/calendar/``, where you can
replace ``user`` and ``calendar`` by some strings of your choice. Calendars are
automatically created if needed.
You can fill other attributes like the color and the name, these are only used
for Evolution and are not uploaded.
Click on ``OK``, and your calendar should be ready for use.
Complex Configuration
=====================
.. note::
This section is only for Linux users. Windows and MacOS advanced support
will be available later.
Installing Server
-----------------
You can install Radicale CalDAV server with the following command, with
superuser rights::
python setup.py install
Then, launching the server can be easily done by typing as a normal user::
radicale
Configuring Server
------------------
Configuration File
~~~~~~~~~~~~~~~~~~
The server configuration can be modified in ``/etc/radicale/config`` or in
``~/.config/radicale/config``. Here is the default configuration file, with the
main parameters::
[server]
# CalDAV server hostname, empty for all hostnames
host =
# CalDAV server port
port = 5232
# Daemon flag
daemon = False
# SSL flag, enable HTTPS protocol
ssl = False
# SSL certificate path (if needed)
certificate = /etc/apache2/ssl/server.crt
# SSL private key (if needed)
key = /etc/apache2/ssl/server.key
[encoding]
# Encoding for responding requests
request = utf-8
# Encoding for storing local calendars
stock = utf-8
[acl]
# Access method
# Value: fake | htpasswd
type = fake
# Htpasswd filename (if needed)
filename = /etc/radicale/users
# Htpasswd encryption method (if needed)
# Value: plain | sha1 | crypt
encryption = crypt
[storage]
# Folder for storing local calendars,
# created if not present
folder = ~/.config/radicale/calendars
This configuration file is read each time the server is launched. If some
values are not given, the default ones are used. If no configuration file is
available, all the default values are used.
Command Line Options
~~~~~~~~~~~~~~~~~~~~
All the options of the ``server`` part can be changed with command line
options. These options are available by typing::
radicale --help
Python Versions and OS Support
==============================
TLS Support
-----------
HTTPS support depends on the ``ssl`` module, only available from Python
2.6. Nevertheless, Radicale without TLS encryption works well with Python 2.5.
Moreover, python 2.6 suffers `a bug <http://bugs.python.org/issue5103>`_
causing huge timeout problems with SSL. No workaround will be added in
Radicale, please ask the Python developers for a fix or use Python 3.x.
Crypt Support
-------------
With the htpasswd access, many encryption methods are available, and crypt is the
default one in Radicale. Unfortunately, the ``crypt`` module is not unavailable on
Windows, you have to pick another method on this OS.