Kolab Groupware 2.4 Documentation

vanmeeuwen's picture

Many people have been wondering why the documentation for Kolab Groupware currently refers to version 2.4, and what that version 2.4 is all about. We have to take a couple of steps back in order to address the question, and review what has happened, and why.

Documentation... regrettably, it's one of those things that tends to lag behind the actual development and release of a software project. Perhaps it's because many people contributing to the software development have little interest in writing up how their software should or could be used. Perhaps some of the people that would write it all up do not have confidence in their documentation skills - perhaps a language barrier is a part of that. In any case, so far, the majority of documentation for Kolab Groupware version 2.4 has therefore been written by yours sincerely, though admittedly parts of it are attributable to others who've created wiki articles on a particular subject, such as the chapter on Combatting Spam.

Kolab Systems, the vendor of Kolab Groupware, and the company that enables me to pay my bills, has a vested interest in the adaptability and continued development of the Kolab Groupware solution. We have found that, using the traditional deployment model for Kolab 2.3, and with the Kolab 2.3 code-base, integration into existing environments, scalability and redundancy had proven to be... suboptimal.

Suboptimal not in that it was impossible to do, but the code-base would have needed customizations that in turn would prove to be mutually exclusive with deployment in other environments, again spawning the need for customizations. This is a virtuous circle, but would have taken a very long time to increment in value and move forward. Long story short, for integration and adaptability purposes, the code-base needed some serious re-factoring.

The Kolab components we are speaking of mainly in this context would include the Kolab daemon, it's Kolab perl library, which is used by kolabconf, and the web administration panel. Inherently, the changes would also impact client software, such as Horde and Roundcube.

On August 26th, 2010, work on PyKolab began. Its goals were set out to be broad yet very clear; allow for sufficient option value to integrate with existing environments sustainably.

PyKolab, today, includes the following components;

  • Kolab daemon
  • Kolab SASL Authentication daemon
  • Kolab SMTP Access Policy
  • Kolab Content Filter
  • Kolab Command-line utilities
  • Format interpreters

All of this was, and still is, somewhat mutually exclusive with Kolab 2.3. It could therefore not be released as part of Kolab 2.3. Furthermore, Kolab 2.3 is product series for which the reference implementation continues to be OpenPKG, and that does not ship Python.

So, we're looking at something that is not Kolab 2.3 to ship PyKolab with. After some deliberations, it was decided that it could also not be called Kolab 3.0 as we were looking to make many other changes, many of which are outlined in the agenda for our last meeting on February 27th, that would, for most of them, each by themselves justify a major release (see KEP #5, "Server Product Versioning").

Because its availability had become urgent, it was decided to dupe the product series "Kolab 2.4". Perhaps, in hindsight, it was not the wisest of decisions, but it happened nonetheless.

So why were most of you not involved in this decision?

First, urgency - a specific customer needed the changes that were in PyKolab right-away.

Second, we had not yet defined any sort of process around development cycles, let alone agreed upon a set of processes with you, the community.

Third, the changes involved are significant. No, let me rephrase - the changes involved are extra-ordinarily humongous. An attempt to outline what was going on with the Kolab SMTP Access Policy implementation outlines the amount of confusion surrounding what was going on, but please allow me to illustrate some further shock-waves that would have hit the development mailing list too early;

  • The reference platform for server implementation is native packages on Red Hat Enterprise Linux 5 - not OpenPKG packages on Debian.
  • The reference implementation for the authentication and authorization database was the technical equivalent of Netscape Directory Server 7.2, and today is 389 Directory Server, not OpenLDAP.
  • Kolab 2.4 ships Cyrus IMAP 2.4 without any Kolab specific patches.
  • Kolab 2.4 does not use the Perl Kolab daemon, nor perl-Kolab, nor kolabconf, nor kolab_bootstrap.
  • Kolab 2.4 ships an LDAP schema that is stripped down (significantly) as to not include organization-specific schema extensions, and not include server configuration items.

All of this, the replacement of components you are comfortable with in Kolab 2.3, and development of new components and new features all needs documentation. This new documentation, of the software I have developed and we are using as the basis to work towards the future, Kolab Groupware 3.0, is what is on http://docs.kolab.org. Now you know why it refers to 2.4.

So why were most of you not informed about 2.4?

Kolab Groupware 2.4 requires a serious transition between what you run today, and what you would be running, regardless of whether you run an OpenPKG-based deployment, or native packages available through, for example, the Debian repositories.

Packages for distributions other then Red Hat Enterprise Linux are barely available, still - a shortage in resources contributes to this, and you, the community, is not yet participating in making anything happen in this area. This of course is quite a vicious circle as well. The changes involved require clear documentation - something I'm working on, but that'll remain a work in progress for quite some time to come. The setup process (you probably know as kolab_bootstrap) is not automated - something I'm working on. The Kolab web administration panel that is compatible with the other changes involved is under active development. Etcetera, etcetera.

How can you help?

The more things you throw back over the fence, the better. We'd like to do a good job, you know, and if you raise an issue you do not have to feel like you're also responsible for resolving it. Here's some ideas of what you could do.

  1. Read the documentation at http://docs.kolab.org/.
    I recommend starting with the Architecture and Design guide. It's only about 124 pages all-inclusive...
    Let us know whether it makes sense, whether you understand what it says / what it is about, what you're missing, etcetera. If you don't understand what you read in the documentation, the issue is with the documentation. I recommend using the issue tracker to create tickets, or discuss on the development mailing list.
  2. Help define how -you think- things should work.
    You of all people know what you want better than anyone else. We're interested to learn about your use-cases, deployment scenarios, requirements. I recommend using the development mailing list for this.
  3. Write documentation.
    There's many things that currently require some text still. You'll recognize the blanks throughout the documentation currently available.
    Writing documentation is one way to enjoy one of the steepest learning curves you'll ever get. Note that any documentation  you do contribute doesn't have to be perfect right off the bat, language- or otherwise, it is a collaborative and an evolutionary process.
  4. Give-It-A-Go(TM).
    Follow the instructions in the Community Installation Guide using an Enterprise Linux 5 system, such as Red Hat Enterprise Linux 5, or CentOS 5 - for the part that has been completed. If you favor a different distribution or a different version, please consider contributing to the packaging effort. Contact me (RPM) or Christoph Wickert (APT) for more information. To avoid any confusion, Christoph is an excellent RPM packager as well, BTW.
    Let us know where things go wrong or things don't make any sense.