Jeroen van Meeuwen (Kolab Systems)
vanmeeuwen at kolabsys.com
Fri Feb 20 03:39:12 EST 2015
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 , a not-at-all too complex syntax that does
not bear as much overhead as the previous attempts with Publican DocBook
== 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
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
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
Choose a platform we call the "reference platform", and chose a
particular implementation scenario we call the "reference
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.
Jeroen van Meeuwen
Systems Architect, Kolab Systems AG
e: vanmeeuwen at kolabsys.com
m: +41 79 951 9003
pgp: 9342 BF08
More information about the Cyrus-devel