diff --git a/configuration.yaml b/configuration.yaml index 808e5324..fde897c2 100644 --- a/configuration.yaml +++ b/configuration.yaml @@ -1,5 +1,5 @@ name: Radicale -description: CalDAV Server +description: CalDAV and CardDAV Server license: GPLv3 public: true url: http://www.radicale.org/ diff --git a/pages/download.rst b/pages/download.rst index a872e40b..d45817fd 100644 --- a/pages/download.rst +++ b/pages/download.rst @@ -26,6 +26,9 @@ Source Packages You can download the Radicale package for each release: +- `Radicale-0.7.tar.gz + `_ + (34 KiB) - `Radicale-0.6.4.tar.gz `_ (31 KiB) diff --git a/pages/home.rst b/pages/home.rst index 06fd51ae..8450df86 100644 --- a/pages/home.rst +++ b/pages/home.rst @@ -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 diff --git a/pages/project_description.rst b/pages/project_description.rst index d434a7b5..ffddb034 100644 --- a/pages/project_description.rst +++ b/pages/project_description.rst @@ -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 `_. -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. diff --git a/pages/technical_choices.rst b/pages/technical_choices.rst index 365a0270..d7f1c4a7 100644 --- a/pages/technical_choices.rst +++ b/pages/technical_choices.rst @@ -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 `_, 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. diff --git a/pages/user_documentation.rst b/pages/user_documentation.rst index 69115249..86ae7299 100644 --- a/pages/user_documentation.rst +++ b/pages/user_documentation.rst @@ -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 `_ 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 `_. .. 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``.