Notes on how to upgrade from Zarafa 4.2x to Zarafa 5.00
-------------------------------------------------------

Zarafa 5.00 introduced the new 'storeid'-based SQL backend, which means that
you have to run a conversion on your database before being able to run
Zarafa 5.00. The storeid makes sure that data that from a single store is
located close together on the physical disk. It is therefore faster to
access, especially with large amounts of users. It is also highly
recommended to upgrade to innodb (see below) before upgrading the database
to the Zarafa 5.00 format.

WARNING: The conversion can take several hours, as the largest table, the
'properties' table, needs to be updated and this table may contain several
million rows. You are highly recommended to create a backup before
attempting the conversion. You must also make sure that there is at least
1.5x the size of the properties table free disk space for the conversion to
run propertly. You can find the size of the table with the 'show table
status' command of mysql.

After backing up your data, you can install the Zarafa RPM and then

/usr/share/zarafa/db-convert-4.2x-to-5.00 <user> <pass> <db>

with the correct username, password and database name. This will start the
update.

After updating, you can start the zarafa-server and everything should be
just as it was before.

Notes on how to upgrade from Zarafa 4.20 to Zarafa 4.21
-------------------------------------------------------
No database updates are *required*. However, if you are using an InnoDB
database you can optionally improve database performance by running

/usr/share/zarafa/db-convert-4.20-to-4.21

This will add an extra index to the 'hierarchy' table, speeding up loading
of large rable (~5000 items and up) by indexing the flags of the items.

Notes on how to upgrade from Zarafa 4.1x to 4.2x
------------------------------------------------

Upgrading Zarafa from 4.1x to 4.2x requires the following:

1. Upgrading the actual server binaries
2. Updating the database structure
3. Restarting the server

Additionally, you can optionally convert the database to the InnoDB format.
This is the default for new installations of Zarafa 4.20 but is not
required. Converting your database to InnoDB can take quite some time, but
does significantly improve performance and stability, espescially on heavily
loaded servers. Before upgrading the tables to InnoDB, first make sure you
have done the steps above and the database is running correctly with Zarafa.

Upgrading the server binaries
=============================

Upgrading your server binaries is done in an OS-specific way. For RPM-based
operating system (ie RedHat, SuSE, Fedora), you can simply use the 'rpm'
command to upgrade your system. Please note that upgrading your server
binaries will *not* upgrade your database format.

In debian, you can use 'dpkg' to upgrade the Zarafa binaries.

After upgrading the server binaries, please check your configuration, as
many new configuration directives have been added in Zarafa 4.20. There are
example configurations in /usr/share/zarafa/. In Most cases, you will be
able to re-use the configuration file you were already using.

Updating the database structure
===============================

In Zarafa 4.20, a new user system was introduced. This new system uses
either an LDAP or MySQL-based user storage system and therefore requires a
slightly different table definition. The conversion from the old database
format to the new database format is fairly quick and simple and can be done
by running the provided perl script /usr/share/zarafa/db-convert-4.1-to-4.2
with

perl /usr/share/zarafa/db-convert-4.1-to-4.2 <user> <pass> <db>

This will make your users table compatible for Zarafa 4.20. After doing this
update, Zarafa will be ready to be used with the 'db' user plugin.

Restarting the server
=====================

You can now restart your zarafa server. In Zarafa 4.20 there are now 4
services that need to be started:

- zarafa-server
- zarafa-spooler
- zarafa-monitor (optional)
- zarafa-gateway (optional)

These services all have their own init scripts in /etc/init.d and must be
enabled seperately:

/etc/init.d/zarafa-server start
/etc/init.d/zarafa-spooler start

...

Please consult the man pages for zarafa-monitor and zarafa-gateway to
configure these correctly for your needs, altough the defaults will often be
good for most situations.

Upgrading to InnoDB
===================

WARNING: Upgrading your database to InnoDB is a time-consuming and dangerous
operation. Please backup your database before attempting the conversion.

WARNING: Make sure you have upgraded Zarafa's database to the 4.20 format
using the steps above before attempting to convert the Zarafa database.

WARNING: Make sure you have at least as much diskspace free as the size of
your entire database. MySQL may need this space to run the conversion.

To convert the entire database to innodb, run the following command

mysql <db> -u <dbuser> -p < /usr/share/zarafa/db-convert-4.20-to-innodb.sql

This will run a series of SQL commands to convert your tables to InnoDB.
This can take a very long time (up to a few hours depending on your database
size). Don't restart your server or MySQL while it is running.

Using innodb, less locks are held on tables which improves concurrency, and
the initial loading of tables is much faster; ie. opening your inbox with
a large amount of e-mail when it is not cached runs in only a few seconds
with the InnoDB engine.
