Proposed Documentation

[Jeroen van Meeuwen (Kolab Systems)]

Hi there,

I was going to simply propose a structure for some documentation, but I 
quickly found that wasn't enough.

== Tooling ==

I think Simon Amor and myself are pretty happy with writing 
documentation in Sphinx [1], a not-at-all too complex syntax that does 
not bear as much overhead as the previous attempts with Publican DocBook 
XML.

== Installation ==

We agreed that it should be as easy as possibly to, proverbially: yum -y 
install cyrus-imapd && service cyrus-imapd start && kmail && kthxbye.

I'm thinking of something along the lines of 
https://docs.kolab.org/installation-guide/, minus the prepping, but plus 
the firewall logic, and minus the distinction between a community and 
enterprise edition.

Per target platform, we should have a package of our latest (stable) 
version available for download. Might I suggest we abuse 
build.opensuse.org and start with the existing build logic in 
https://obs.kolabsys.com/package/show/Kolab:Development/cyrus-imapd (6 
Linux platforms, 17 distribution versions). Such build system allows 
triggering builds for platforms based on git commits, and collaboration 
as to improve the packaging can take place there.

Per target platform, we should entertain both the current version 
included in the distribution's repositories, if any, and mention whether 
we (upstream) still actively support that version.

I'm afraid we're going to have to refer to download and build 
instructions for operating systems that do not themselves have package 
repositories or for which we cannot ship packages.

== Configuration ==

Aside from the option value within Cyrus IMAP (deployment, distributed, 
murder, replication, ...) ...

There is a point at which we have to insert verbiage about supported 
MTAs, and how to configure them to work with Cyrus IMAP. There is a goal 
to document the default MTA that comes with each distribution / 
operating system, and perhaps even roll it all up in a setup script. 
 From the top of my head this might include Exim, Postfix, Sendmail, 
qmail and opensmtpd -- but there may be others as well.

Most distributions do not allow various providers of a capability 
"imapserver" to conflict (i.e., a "yum -y install dovecot uw-imap 
cyrus-imapd" succeeds), nor allow one package to touch the configuration 
files of another package (so there's no %post or .postinst allowed that 
points everything to Cyrus IMAP automatically upon installation).

Tumbling down the rabbit hole further, it doesn't become any less messy 
-- so I'm going to make a radical and probably also controversial 
proposal;

   Choose a platform we call the "reference platform", and chose a 
particular implementation scenario we call the "reference 
implementation".

I cannot understate the amount of clarity it brings to a crowd less 
technically savvy than most of us. For the Kolab community for example, 
the reference implementation is a next-next-finish setup of a "yum -y 
install kolab" on a single Enterprise Linux 6 box (i.e. everything 
running on localhost). We'll elect to shift the reference platform to 
Enterprise Linux 7 after some or the other release this month, after 
which Enterprise Linux 6 becomes a legacy platform.

Subsequently, *all* documentation sets off on the basis of this 
reference implementation, and we find out our distro- or OS-specific 
notes to them.

Naturally, additional such reference implementations would be built -- 
how to run a unified murder (behind some NGINX proxy) for example, how 
to do LDAP/SQL authn/authz, etc.

I'll stop here, for your thoughts and remarks.

Kind regards,

Jeroen van Meeuwen

[1] http://sphinx-doc.org/

-- 
Systems Architect, Kolab Systems AG

e: vanmeeuwen at kolabsys.com
m: +41 79 951 9003
w: https://kolabsystems.com

pgp: 9342 BF08