commit d8df38f4d731144dfdc4d786f7bb1a45e27ab2df Author: Guillaume Ayoub Date: Wed Jul 29 17:19:55 2009 +0200 Creation of the documentation repository diff --git a/.gitignore b/.gitignore new file mode 100644 index 00000000..ef04f9db --- /dev/null +++ b/.gitignore @@ -0,0 +1 @@ +!*.rst \ No newline at end of file diff --git a/contribute.rst b/contribute.rst new file mode 100644 index 00000000..904c6df8 --- /dev/null +++ b/contribute.rst @@ -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. diff --git a/documentation.rst b/documentation.rst new file mode 100644 index 00000000..023e1102 --- /dev/null +++ b/documentation.rst @@ -0,0 +1,29 @@ +=============== + Documentation +=============== + +User documentation +================== + +This document gives describes how to install and configure the server. + +- `User documentation (HTML) `_ +- 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 (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 (PDF - soon) diff --git a/download.rst b/download.rst new file mode 100644 index 00000000..46861136 --- /dev/null +++ b/download.rst @@ -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 +`_, 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 `_. diff --git a/home.rst b/home.rst new file mode 100644 index 00000000..1a92e1f3 --- /dev/null +++ b/home.rst @@ -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. diff --git a/news.rst b/news.rst new file mode 100644 index 00000000..19bda756 --- /dev/null +++ b/news.rst @@ -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 `_ 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… diff --git a/project_description.rst b/project_description.rst new file mode 100644 index 00000000..da13ae95 --- /dev/null +++ b/project_description.rst @@ -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 `_. + +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 + `_. +.. [#] `Popularity of CalDAV `_, + by Wikipedia. diff --git a/technical_choices.rst b/technical_choices.rst new file mode 100644 index 00000000..92e7ceec --- /dev/null +++ b/technical_choices.rst @@ -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 `_, the web + contents and calendars sharing server build to support the Chandler Project. + +.. [#] `Darwin Calendar Server `_, a + standards-compliant calendar server mainly developped by Apple. + +.. [#] `Mozilla Sunbird `_, + a cross-platform calendar client built upon Mozilla Toolkit. + +.. [#] `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 `_. + +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…* diff --git a/user_documentation.rst b/user_documentation.rst new file mode 100644 index 00000000..8c1989c7 --- /dev/null +++ b/user_documentation.rst @@ -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 `_. +.. [#] `Twisted download page `_. + +Radicale +-------- + +Radicale can be freely downloaded on the `project website, download section +`_. 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 +`_ 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…*