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

Update the website for 0.7 version

Browse source
This commit is contained in:
Guillaume Ayoub 2012-03-22 01:49:28 +01:00
parent 6fbb0040d5
commit 7a75c086c4
6 changed files with 152 additions and 106 deletions
Download patch file Download diff file Expand all files Collapse all files

3
pages/download.rst
View file

@ -26,6 +26,9 @@ Source Packages
You can download the Radicale package for each release:
- `Radicale-0.7.tar.gz
<http://pypi.python.org/packages/source/R/Radicale/Radicale-0.7.tar.gz>`_
(34 KiB)
- `Radicale-0.6.4.tar.gz
<http://pypi.python.org/packages/source/R/Radicale/Radicale-0.6.4.tar.gz>`_
(31 KiB)

21
pages/home.rst
View file

@ -1,16 +1,16 @@
==========================
A Simple Calendar Server
==========================
======================================
A Simple Calendar and Contact Server
======================================
Presentation
============
The Radicale Project is a complete CalDAV calendar server solution. It can
store multiple calendars.
The Radicale Project is a complete CalDAV (calendar) and CardDAV (contact)
server solution.
Calendars are available for both local and remote access, possibly limited
through authentication policies. They can be viewed and edited by calendar
clients on mobile phones or computers.
Calendars and address books are available for both local and remote access,
possibly limited through authentication policies. They can be viewed and edited
by calendar and contact clients on mobile phones or computers.
Technical Description
@ -28,8 +28,9 @@ GPL version 3.
Main Features
=============
- Shares calendars through CalDAV and HTTP
- Supports events, todos and journal entries
- Shares calendars through CalDAV, WebDAV and HTTP
- Shares contacts through CardDAV, WebDAV and HTTP
- Supports events, todos, journal entries and business cards
- Works out-of-the-box, no installation nor configuration required
- Warns users on concurrent edition
- Limits access by authentication

52
pages/project_description.rst
View file

@ -14,22 +14,23 @@
Main Goals
==========
The Radicale Project is a complete calendar storing and manipulating
solution. It can store multiple calendars.
The Radicale Project is a complete calendar and contact storing and
manipulating solution. It can store multiple calendars and multiple address
books.
Calendar manipulation is available from both local and distant
Calendar and contact manipulation is available from both local and distant
accesses, possibly limited through authentication policies.
What Radicale Is
================
Calendar Server
---------------
Calendar and Contact 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.
The Radicale Project is mainly a calendar and contact server, giving local and
distant accessess for reading, creating, modifying and deleting multiple
calendars through simplified CalDAV and CardDAV protocols.
Data can be encrypted by SSL, and their access can be restricted thanks to
different authentication methods.
@ -38,38 +39,25 @@ different authentication methods.
What Radicale Is not and will not Be
====================================
Calendar User Agent
-------------------
Calendar or Contact 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
--------------------------------------
Original Calendar or Contact Access Protocol
--------------------------------------------
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.
CalDAV and CardDAV are not perfect protocols. We think that its main problem is
their complexity [#]_, that is why we decided not to implement the whole
standard but just enough to understand some of its client-side implementations
[#]_.
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.
CalDAV and CardDAV are not perfect protocols, but they are the best open
standards available and are 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.

73
pages/technical_choices.rst
View file

@ -45,36 +45,41 @@ Radicale Project are described by RFCs:
(WebDAV) :RFC:`4918`
- Transport Layer Security (TLS) :RFC:`5246`
- iCalendar format (iCal) :RFC:`5545`
- vCard Format Specification :RFC:`6350`
- vCard Extensions to Web Distributed Authoring and Versioning (CardDAV)
:RFC:`6352`
.. 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.
CalDAV and CardDAV implementations **require** iCal, vCard, 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.
code. They are very useful to understand why the Radicale Project is different
from other CalDAV and CardDAV servers, and why features are included or not in
the code.
Oriented to Calendar User Agents
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
Oriented to Calendar and Contact 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.
Calendar and contact servers work with calendar and contact clients, using a
defined protocol. CalDAV and CardDAV are good protocols, 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: Davical [#]_, 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.
Some calendar servers have been created to follow the CalDAV and CardDAV RFCs
as much as possible: Davical [#]_, Cosmo [#]_ and Darwin Calendar Server [#]_,
for example, are much more respectful of CalDAV and CardDAV 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 (Lightning, Evolution,
Android, iPhone and iCal, more are coming [#]_).
The Radicale Server does not and **will not** support the CalDAV and CardDAV
standards. It supports the CalDAV and CardDAV implementations of different
clients (Lightning, Evolution, Android, iPhone and iCal, more are coming [#]_).
.. [#] `Davical <http://www.davical.org/>`_, a standards-compliant calendar
server.
@ -98,7 +103,7 @@ 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.
calendar and contact access.
Contrary to other servers that are often complicated, require high privileges
or need a strong configuration, the Radicale Server can (sometimes, if not
@ -135,13 +140,17 @@ calendar through network:
+-----------+---------------------+--------------------------+
| Part | Layer | Protocol or Format |
+===========+=====================+==========================+
| Server | Calendar Storage | iCal |
| Server | Calendar/Contact | iCal/vCard |
| | Storage | |
| +---------------------+--------------------------+
| | Calendar Server | CalDAV Server |
| | Calendar/Contact | CalDAV/CardDAV Server |
| | Server | |
+-----------+---------------------+--------------------------+
| Transfert | Network | CalDAV (HTTP + TLS) |
| Transfert | Network | CalDAV/CardDAV |
| | | (HTTP + TLS) |
+-----------+---------------------+--------------------------+
| Client | Calendar Client | CalDAV Client |
| Client | Calendar/Contact | CalDAV/CardDAV Client |
| | Client | |
| +---------------------+--------------------------+
| | GUI | Terminal, GTK, etc. |
+-----------+---------------------+--------------------------+
@ -151,7 +160,7 @@ The Radicale Project is **only the server part** of this architecture.
Code Architecture
-----------------
The package offers 7 modules.
The package offers 8 modules.
``__main__``
The main module provides a simple function called ``run``. Its main work is
@ -171,11 +180,10 @@ The package offers 7 modules.
executable with some command line options.
``ical``
In this 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.
In this module are written the classes to represent collections and items in
Radicale. The simple iCalendar and vCard readers and writers are included in
this file. 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 module are mainly called by the CalDAV server
@ -194,3 +202,8 @@ The package offers 7 modules.
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.
``storage``
This folder is a set of storage modules able to read and write
collections. The only one is now ``filesystem``, storing each collection into
one flat plain-text file.

107
pages/user_documentation.rst
View file

@ -7,7 +7,7 @@
:Date: 2010-02-11
:Abstract: This document is a short description for installing and using the
Radicale Calendar Server.
Radicale calendar and contact Server.
.. contents::
@ -50,8 +50,8 @@ of:
- `Apple iCal <http://www.apple.com/macosx/apps/>`_
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).
calendar or contact client which implements CalDAV or CardDAV specifications
too (luck is highly recommanded).
Simple Usage
@ -88,15 +88,20 @@ 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.
Lightning and Thunderbird cannot access CardDAV servers yet.
Evolution
~~~~~~~~~
Calendars
+++++++++
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
something like ``caldav://localhost:5232/user/calendar.ics/``, where you can
replace ``user`` and ``calendar`` by some strings of your choice. Calendars are
automatically created if needed.
@ -105,6 +110,11 @@ for Evolution and are not uploaded.
Click on ``OK``, and your calendar should be ready for use.
Contacts
++++++++
*To be written*
KOrganizer
~~~~~~~~~~
@ -136,6 +146,11 @@ from server to phone only`` if you want to use two-way-sync.
Tap on ``Finish`` and you're done. You're now able to use the new calendars
in the same way you were using Google calendars before.
CalDAV-Sync
~~~~~~~~~~~
*To be written*
aCal
~~~~
@ -169,6 +184,9 @@ of them (display colour, notifications, etc.).
iPhone & iPad
~~~~~~~~~~~~~
Calendars
+++++++++
For iOS devices, the setup is fairly straightforward but there are a few settings
that are critical for proper operation.
@ -191,6 +209,11 @@ that are critical for proper operation.
on another device and they don't appear on your iPad of iPhone, then make sure your sync
settings are correct
Contacts
++++++++
*To be written*
iCal
~~~~
@ -198,6 +221,9 @@ iCal
This description assumes you do not have any authentication or encryption
configured. The procedure will change accordingly if you do.
Calendars
+++++++++
In iCal 4.0 or iCal 5.0:
1. Open the ``Preferences`` dialog and select the ``Accounts`` tab
@ -230,6 +256,11 @@ now set-up. You can close the ``Preferences`` window.
window is confusing as you can't focus an empty account and iCal will just
add a calendar to another account.
Contacts
++++++++
*To be written*
Complex Configuration
=====================
@ -241,8 +272,8 @@ Complex Configuration
Installing the Server
---------------------
You can install Radicale CalDAV server with the following command, with
superuser rights::
You can install Radicale thanks to the following command, with superuser
rights::
python setup.py install
@ -284,6 +315,8 @@ configuration file, with the main parameters:
certificate = /etc/apache2/ssl/server.crt
# SSL private key
key = /etc/apache2/ssl/server.key
# Reverse DNS to resolve client address in logs
dns_lookup = True
[encoding]
@ -315,6 +348,11 @@ configuration file, with the main parameters:
ldap_base = ou=users,dc=example,dc=com
# LDAP login attribute
ldap_attribute = uid
# LDAP filter string
# placed as X in a query of the form (&(...)X)
# example: (objectCategory=…)(objectClass=…)(memberOf=…)
# leave empty if no additional filter is needed
ldap_filter =
# LDAP dn for initial login, used if LDAP server does not allow anonymous searches
# Leave empty if searches are anonymous
ldap_binddn =
@ -338,16 +376,16 @@ configuration file, with the main parameters:
filesystem_folder = ~/.config/radicale/collections
[logging]
# Logging configuration file
# If no config is given, simple information is printed on the standard output
# For more information about the syntax of the configuration file, see:
# http://docs.python.org/library/logging.config.html
config = /etc/radicale/logging
# Set the default logging level to debug
debug = False
# Store all environment variables (including those set in the shell)
full_environment = False
[logging]
# Logging configuration file
# If no config is given, simple information is printed on the standard output
# For more information about the syntax of the configuration file, see:
# http://docs.python.org/library/logging.config.html
config = /etc/radicale/logging
# Set the default logging level to debug
debug = False
# Store all environment variables (including those set in the shell)
full_environment = False
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
@ -524,26 +562,29 @@ explained in `the mod_wsgi documentation
<http://code.google.com/p/modwsgi/wiki/ConfigurationGuidelines#User_Authentication>`_.
.. note::
Read-only calendars can also be served by a simple Apache HTTP server, as
Radicale stores full-text icalendar files.
Read-only calendars or address books can also be served by a simple Apache
HTTP server, as Radicale stores full-text icalendar and vcard files with the
default configuration.
Authentication and URLs
-----------------------
If no authentication method is set, calendars are available at ``/calendar``
and ``/folder/calendar`` URLs. Else, calendars are public, private or personal,
depending on their URLs.
If no authentication method is set, calendars are available at
``/calendar.ics/`` and ``/folder/calendar.ics/`` URLs. Else, calendars are
public, private or personal, depending on their URLs.
Public Calendars
~~~~~~~~~~~~~~~~
This section is written for calendars, but it is the same for address books.
Public users are available for everybody, authenticated or not.
Public Collections
~~~~~~~~~~~~~~~~~~
Calendars at ``/public_user/calendar`` URLs are public. Public users are
Public collections are available for everybody, authenticated or not.
Calendars at ``/public_user/calendar.ics/`` URLs are public. Public users are
defined in the ``acl → public_users`` configuration variable. If ``None`` is in
the list of public users, public calendars are also available at ``/calendar``
URLs.
the list of public users, public calendars are also available at
``/calendar.ics/`` URLs.
.. important::
@ -552,10 +593,10 @@ URLs.
empty string in the ``acl → public_users`` configuration variable.
Private Calendars
~~~~~~~~~~~~~~~~~
Private Collections
~~~~~~~~~~~~~~~~~~~
Private calendars are available for all the authenticated users.
Private collections are available for all the authenticated users.
Calendars at ``/private_user/calendar`` URLs are private. Private users are
defined in the ``acl → private_users`` configuration variable. If ``None`` is
@ -563,10 +604,10 @@ in the list of private users, private calendars are also available at
``/calendar`` URLs.
Personal Calendars
~~~~~~~~~~~~~~~~~~
Personal Collections
~~~~~~~~~~~~~~~~~~~~
Personal calendars are only available for the calendar owner.
Personal collections are only available for the calendar owner.
Calendars at ``/owner/calendar`` URLs are personal. They are only available for
the authenticated user called ``owner``.