Quick Install Manual - Kolab 1.0
Author: Martin Konold <martin.konold@erfrakon.de>
$Id: QIM,v 1.15.2.16 2003/07/31 19:02:48 martin Exp $

Please have a look at the documentation available from kolab.kde.org.

Please report Problems with the QIM or the software to kroupware@kde.org so that we can 
improve Kolab and its documentation permanently.

Upgrading from an alpha or beta release we do not encourage, as the LDAP
layout has changed greatly. You may however want to manually merge
old ldif data into the new tree, after the Kolab installation.

For deeper understandig of your packaging strategy we recommend to have a look at 

	http://www.erfrakon.de/projects/kolab/documentation/technical/index.html

Instructions for installing binaries are appended to this documentation.

========================================================================
Important!

We do currently depend on the latest unstable OpenPKG Current - As soon as
available we will port to the very soon expected OpenPKG 1.3. Actually OpenPKG is
already very reliable so that this circumstance should not really matter to
Kolab users currently.

We highly recommend to use the following environment variables in order 
to be safe from some potential surprises. 
We have reports about Redhat Linux having problems with Kolab otherwise.

	LC_ALL=C
	LC_MESSAGES=C
	LANG=C
	SUPPORTED=C
        export LC_ALL LC_MESSAGES LANG SUPPORTED


Do _NOT_ use an NFS mounted partition for installing Kolab (e.g. /kolab).
Cyrus IMAPD cannot work over NFS and it would be suboptimal anyway.
Explanation at http://asg.web.cmu.edu/cyrus/imapd/install-FAQ.html#nfs .

The current kolab installation also does not work well with prefixes of more
than a single directory. You may use symbolic links as a workaround. This will
change when we move to OpenPKG 1.3 and release Kolab 1.1. If you decide for a
different prefix than /kolab please adopt the instruction appropriatly. Using
zhe /kolab prefix allows for simple copy&paste.

=======================================================================

==================== Installation from Source =========================
              (see below for binary installation)

We recommend to install the Kolab Server from source though at the end of this
QIM we provide instructions how to install from binaries on Debian 3.0 (woody).

Preparation of OpenPKG environment (see also http://www.openpkg.de)

1. Download everything from http://www.erfrakon.de/projects/kolab/download/

2. execute bootstrap compile shell script as root
  http://www.erfrakon.de/projects/kolab/download/kolab-server-1.0/src/openpkg-20030606-20030606.src.sh

  sh ./openpkg-20030606-20030606.src.sh --prefix=/kolab --user=kolab \
      --group=kolab 2>&1 | tee kolab.log

Please examine the log file kolab.log carefully for errors.

3. execute the resulting bootstrap install shell script as root

  sh -x ./openpkg-20030606-20030606.ix86-linux2.4-kol.sh

Please note the the binary shell script will have a slightly different name on
non IA32-Linux systems.

Now you succeeded in bootstrapping the kolab environment.
You will have a new user kolab in your /etc/passwd.

4. Put the following script in /etc/init.d/kolab or wherever your system expects startup scripts. 
Depending on the OS you may require a different location or syntax. Please consult the manual 
of your operating system.

For LSB complient systems the startup script /etc/init.d/kolab looks like

#!/bin/sh
#
# kolab -- startup/shutdown transfer script for /kolab OpenPKG hierarchy
#
[ ! -f /kolab/etc/rc.d/rc.kolab ] && exit 0
case $1 in
    start   ) exec /kolab/etc/rc.d/rc.kolab start ;;
    stop    ) exec /kolab/etc/rc.d/rc.kolab stop  ;;
    restart ) $0 stop
              $0 start ;;
esac

5. Become the kolab user
  
  su - kolab

The kolab environment is selfcontained in /kolab. It has its own rpm database 
etc. It explicitly will not interfere with your operating systems package 
database! Please make sure that whenever dealing with the Kolab server
installation that you are using indeed /kolab/bin/rpm and _not_ the package
manager of the hosting operating system. This can be easily accomplished by
entering:

	export PATH=/kolab/bin:/kolab/sbin:$PATH

5. As user kolab install the source packages 
rpm -ihv *.src.rpm

6. compile and install the packages as user root according to the following pattern:

PACKAGE has in this template to be replaced with the corresponding name of the
component (make, patch, binutils,...)

cd  /kolab/RPM/SRC/PACKAGE
rpm -bb PACKAGE.spec
(becoming root for installing the rpms is required because we install daemon services. 
su # (become root)
/kolab/bin/rpm -Uhv /kolab/RPM/PKG/PACKAGE-nnn-nnn.ix86-linux2.4-kol.rpm

The compilation and installation of the following rpms is analogous. 

make
patch
binutils
gcc
fsl
procmail
zlib
expat
readline
ncurses
perl
perl-openpkg
openssl
perl-ds
perl-time
perl-xml
perl-term
perl-crypto
perl-conv
perl-ssl
perl-sys
perl-util
perl-mail
perl-net
perl-www
perl-ldap 
m4
bison
sed
libiconv
gettext
imap
getopt
bison
flex
pcre
db
mm
getopt
ncurses

and then compile (as user kolab) and install (as user root!) the kolab specific
packages. For this you need to change directory to /kolab/RPM/SRC/PACKAGE and
then create the binary package from there. Please take care to use the correct
define statement. The later is mandatory for a functional Kolab server.

(Please make sure that you use the correct OpenPKG rpm executable when building
the packages and installing!)

rpm -ba gdbm.spec --define 'with_ndbm yes'
rpm -Uvh /kolab/RPM/PKG/gdbm*kol.rpm

rpm -ba openldap.spec --define 'with_sasl no'
rpm -Uhv /kolab/RPM/PKG/openldap*kol.rpm

rpm -ba sasl.spec --define 'with_ldap yes' --define 'with_login yes'
rpm -Uhv /kolab/RPM/PKG/sasl*kol.rpm

rpm -ba postfix.spec --define 'with_sasl yes' \
	 --define 'with_tls yes' --define 'with_ldap yes'
rpm -Uhv /kolab/RPM/PKG/postfix*kol.rpm

patch < kolab.patch # patch for imapd.spec file and groupfile
                    # only required if building from cvs because the patch
                    # is already included in the src.rpm
rpm -ba imapd.spec --define 'with_groupfile_hack yes' \
	--define 'with_vhost_hack yes'
rpm -Uhv /kolab/RPM/PKG/imapd*kol.rpm

rpm -ba apache.spec --define 'with_mod_ssl yes' --define 'with_mod_dav yes' \
	--define 'with_mod_auth_ldap yes' --define 'with_mod_php_openldap yes' 
	--define 'with_mod_php_imap yes' --define 'with_mod_php yes' \
	--define 'with_mod_php_gettext yes' --define 'with_gdbm yes' \
	--define 'with_ndbm yes'
# if you encounter a missing ndbm.h when building apache please copy the
# required header file manually
# cp /kolab/RPM/SRC/gdbm/gdbm-1.8.3/ndbm.h /kolab/include/
rpm -Uhv /kolab/RPM/PKG/apache*kol.rpm

rpm -ba proftpd.spec --define 'with_ldap yes'
rpm -Uhv /kolab/RPM/PKG/proftpd*kol.rpm

rpm -ba kolab.spec 
rpm -Uhv /kolab/RPM/PKG/kolab*kol.rpm


Please follow the instructions in the output when installing the kolab rpm
carefully.


As root you may now start the kolab server manually via

	/kolab/etc/rc.d/rc.kolab start

Note 1: Please watch carefully the output when installing the kolab rpm. 
You will then see the important manager password on the screen which is 
required for administrating kolab server via webinterface.

	https://kolabserver.yourdomain.com/admin

Note 2: Note that kolab startup takes its time. Just give it some seconds and watch the
syslog in the meantime. It should all come up nicely.

On Linux the output of "netstat -ntplou" gives you an idea which services got
activated.

Note 3: For your convinience we also uploaded Debian 3.0 packages of the kolab
server. Though compiling your own kolab server using this QIM should not be too
difficult.

============================================================================
====================== Installation from Binaries  =========================

Currently we only provide binaries for Debian 3.0 (woody) other distributions
and operating systems will follow.

Please follow the recommendations from the Important! section above
about environment variables affecting the locale.


Installation of OpenPKG environment (see also http://www.openpkg.de for details)

1. Download everything from
http://www.erfrakon.de/projects/kolab/download/kolab-server-1.0/bin/Debian-3.0/

2. Install the bootstrap install shell script
sh -x ./openpkg-20030606-20030606.ix86-linux2.4-kol.sh


Now you already succeeded in bootstrapping the kolab environment.
You will have a new user kolab in your /etc/passwd.

3. Replace the following script in /etc/init.d/kolab

#!/bin/sh
#
# kolab -- startup/shutdown transfer script for /kolab OpenPKG hierarchy
#
[ ! -f /kolab/etc/rc.d/rc.kolab ] && exit 0
case $1 in
    start ) exec /kolab/etc/rc.d/rc.kolab start ;;
    stop  ) exec /kolab/etc/rc.d/rc.kolab stop  ;;
esac

The kolab environment is selfcontained in /kolab. It has its own rpm database 
etc. It explicitly will not interfere with your operating systems package 
database! Please make sure that whenever dealing with the Kolab server
installation that you are using indeed /kolab/bin/rpm and _not_ the package
manager of the hosting operating system. This can be easily accomplished by
entering:

	export PATH=/kolab/bin:/kolab/sbin:$PATH

/kolab/bin/rpm -Uhv make-3.80-20030109.ix86-linux2.4-kol.rpm
/kolab/bin/rpm -Uhv patch-2.5.9-20030520.ix86-linux2.4-kol.rpm
/kolab/bin/rpm -Uhv binutils-2.14-20030613.ix86-linux2.4-kol.rpm
/kolab/bin/rpm -Uhv gcc-3.3-20030614.ix86-linux2.4-kol.rpm
/kolab/bin/rpm -Uhv procmail-3.22-20030330.ix86-linux2.4-kol.rpm
/kolab/bin/rpm -Uhv zlib-1.1.4-20030227.ix86-linux2.4-kol.rpm
/kolab/bin/rpm -Uhv expat-1.95.6-20030130.ix86-linux2.4-kol.rpm
/kolab/bin/rpm -Uhv readline-4.3-20020718.ix86-linux2.4-kol.rpm
/kolab/bin/rpm -Uhv openssl-0.9.7b-20030530.ix86-linux2.4-kol.rpm
/kolab/bin/rpm -Uhv perl*.ix86-linux2.4-kol.rpm
/kolab/bin/rpm -Uhv m4-1.4o-20020206.ix86-linux2.4-kol.rpm
/kolab/bin/rpm -Uhv bison-1.35-20030604.ix86-linux2.4-kol.rpm
/kolab/bin/rpm -Uhv flex-2.5.4a-20030402.ix86-linux2.4-kol.rpm
/kolab/bin/rpm -Uhv pcre-4.3-20030530.ix86-linux2.4-kol.rpm
/kolab/bin/rpm -Uhv fsl-1.1.0-20030522.ix86-linux2.4-kol.rpm
/kolab/bin/rpm -Uhv gdbm-1.8.3-20030213.ix86-linux2.4-kol.rpm
/kolab/bin/rpm -Uhv db-4.1.25.1-20030605.ix86-linux2.4-kol.rpm
/kolab/bin/rpm -Uhv mm-1.3.0-20030307.ix86-linux2.4-kol.rpm
/kolab/bin/rpm -Uhv ncurses-5.3.20030614-20030615.ix86-linux2.4-kol.rpm
/kolab/bin/rpm -Uhv openldap*kol.rpm
/kolab/bin/rpm -Uhv sasl*kol.rpm
/kolab/bin/rpm -Uhv postfix*kol.rpm
/kolab/bin/rpm -Uhv imapd*kol.rpm
/kolab/bin/rpm -Uhv apache*kol.rpm
/kolab/bin/rpm -Uhv proftpd*kol.rpm
/kolab/bin/rpm -Uhv kolab*kol.rpm


Please follow the instructions in the output when installing the kolab rpm
carefully.


As root you may now start the kolab server manually via

	/kolab/etc/rc.d/rc.kolab start

Note 1: Please watch carefully the output when installing the kolab rpm. 
You will then see the important manager password on the screen which is 
required for administrating kolab server via webinterface.

	https://kolabserver.yourdomain.com/admin

Note 2: Note that kolab startup takes its time. Just give it some seconds and watch the
syslog in the meantime. It should all come up nicely.

On Linux the output of "netstat -ntplou" gives you an idea which services got
activated.

===========================================================================