Difference between revisions of "Building FRANKLIN on CentOS 5"

 
(44 intermediate revisions by one other user not shown)
Line 1: Line 1:
{{WIP}}
+
{{Archive}}
  
 
== Introduction ==
 
== Introduction ==
Line 7: Line 7:
 
The build process for Zimbra is poorly documented. You won't find many useful articles from the Zimbra wiki or from the forums. Lots of the articles are obsolete. The only really good instructions are [http://zimbra.ijichi.org/ here], provided by the [http://sourceforge.net/projects/zimbracommunity Zimbra Community Builds project]. Currently (3rd Dec 2008) the only other useful articles in the Zimbra wiki are located [http://wiki.zimbra.com/index.php?title=Building_Zimbra_using_Perforce here]
 
The build process for Zimbra is poorly documented. You won't find many useful articles from the Zimbra wiki or from the forums. Lots of the articles are obsolete. The only really good instructions are [http://zimbra.ijichi.org/ here], provided by the [http://sourceforge.net/projects/zimbracommunity Zimbra Community Builds project]. Currently (3rd Dec 2008) the only other useful articles in the Zimbra wiki are located [http://wiki.zimbra.com/index.php?title=Building_Zimbra_using_Perforce here]
  
I've filed several bug reports related to CentOS5 build process:
+
I've filed several bug reports related to CentOS5 build process. These bugs are relevant at least for FRANKLIN-5010_2660 and/or FRANKLIN-5011_2695.
  
 
* http://bugzilla.zimbra.com/show_bug.cgi?id=33588
 
* http://bugzilla.zimbra.com/show_bug.cgi?id=33588
 
* http://bugzilla.zimbra.com/show_bug.cgi?id=33658
 
* http://bugzilla.zimbra.com/show_bug.cgi?id=33658
 
* http://bugzilla.zimbra.com/show_bug.cgi?id=33587
 
* http://bugzilla.zimbra.com/show_bug.cgi?id=33587
 +
* http://bugzilla.zimbra.com/show_bug.cgi?id=33659
 +
* http://bugzilla.zimbra.com/show_bug.cgi?id=33661
 +
* http://bugzilla.zimbra.com/show_bug.cgi?id=33662
 +
* http://bugzilla.zimbra.com/show_bug.cgi?id=33960
 +
* http://bugzilla.zimbra.com/show_bug.cgi?id=33961
 +
* http://bugzilla.zimbra.com/show_bug.cgi?id=33962
  
You should definitely check them out beforehand. Those problems have not documented these problems in this HOWTO.
+
Until these problems are fixed, you will probably encounter them.
  
 
== Alternatives to source install ==
 
== Alternatives to source install ==
Line 20: Line 26:
 
* If you're willing to run Zimbra on Ubuntu or Solaris, get the appropriate packages from ''Zimbra Community Builds''. They might (or might not) work.
 
* If you're willing to run Zimbra on Ubuntu or Solaris, get the appropriate packages from ''Zimbra Community Builds''. They might (or might not) work.
 
* If you require Outlook support, Symbian mobile clients or such, get the trial version for a commercial version of Zimbra.
 
* If you require Outlook support, Symbian mobile clients or such, get the trial version for a commercial version of Zimbra.
 
== Overview of the build process ==
 
 
The Zimbra build process well described in these two articles:
 
 
* http://varlogmessages.vroomvroom.org/documentation/ubuntu-port/ubuntu-build-instructions
 
* http://varlogmessages.vroomvroom.org/documentation/solaris-port/build-instructions
 
 
Use the Solaris instructions only as a reference. According to ''dijichi'', Zimbra Community Builds project manager, the Solaris instructions are more up-to-date. Unlike stated in Solaris instructions you should probably add the environment variables to ''/etc/profile.d/zimbra.sh'' instead of ''/etc/profile'' directly.
 
 
The basic build steps are these:
 
 
* Get the source (p4 or Zimbra community builds)
 
* Set up the build environment
 
* Build ThirdParty modules
 
* Build ''memcached, nginx'' and ''tcmalloc'' in ''ThirdParty''
 
* Build Zimbra modules
 
  
 
== Getting the source ==
 
== Getting the source ==
Line 43: Line 32:
  
 
* Zimbra Community Builds (http://sourceforge.net/projects/zimbracommunity)
 
* Zimbra Community Builds (http://sourceforge.net/projects/zimbracommunity)
* Zimbra's official Perforce repositories (instructions below)
+
* Zimbra's official Perforce repositories
  
 
The latest Zimbra code - including the ThirdParty packages - is located in a proprietary Perforce (p4) repository. If you're doing a production build, you should try to download a stable branch. In case you're going to do development, you should probably get HEAD (=development branch). I probably downloaded HEAD at first, as there were numerous stupid errors in the build files that I had to fix.
 
The latest Zimbra code - including the ThirdParty packages - is located in a proprietary Perforce (p4) repository. If you're doing a production build, you should try to download a stable branch. In case you're going to do development, you should probably get HEAD (=development branch). I probably downloaded HEAD at first, as there were numerous stupid errors in the build files that I had to fix.
  
To get FRANKLIN (ZCS 5.0.x) from Perforce repositories, you need to get the proprietary ''Perforce'' (P4) client from http://www.perforce.com/perforce/downloads/index.html
+
To can get FRANKLIN (ZCS 5.0.x) from Perforce repositories, you need to get the proprietary ''Perforce'' (P4) client from http://www.perforce.com/perforce/downloads/index.html
  
 
Once ''p4'' binary is installed, do the following:
 
Once ''p4'' binary is installed, do the following:
Line 54: Line 43:
 
  $ '''export P4EDITOR=nano'''
 
  $ '''export P4EDITOR=nano'''
 
  $ '''export P4PORT=codes.zimbra.com:2666'''
 
  $ '''export P4PORT=codes.zimbra.com:2666'''
$ '''p4 -u public -P public1234 -c public-view sync -f //depot/zcs/FRANKLIN/...'''
 
  
 
You set the variables in root's ''$HOME/.bashrc'', ''/etc/profile.d/zimbra.sh'' or whereever you'd like. That way you don't have to retype them every time you check out the sources. The ''mkdir'' is required, because that's where Perforce wants it's stuff to go. It's probably possible to change it's behavior, but hacking around it is faster. After running this command you should have Zimbra sources in ''/home/public/p4/FRANKLIN/''. If you wish to use another directory, you should symlink it to ''/home/public/p4'' to avoid trouble later on. Zimbra's build system assumes some files are located there.
 
You set the variables in root's ''$HOME/.bashrc'', ''/etc/profile.d/zimbra.sh'' or whereever you'd like. That way you don't have to retype them every time you check out the sources. The ''mkdir'' is required, because that's where Perforce wants it's stuff to go. It's probably possible to change it's behavior, but hacking around it is faster. After running this command you should have Zimbra sources in ''/home/public/p4/FRANKLIN/''. If you wish to use another directory, you should symlink it to ''/home/public/p4'' to avoid trouble later on. Zimbra's build system assumes some files are located there.
  
An alternative to getting sources from Zimbra's Perforce repository is to download the ''Zimbra Community Build'' sources located [http://sourceforge.net/project/showfiles.php?group_id=224243 here]. Make sure you don't download ''FRANKLIN-5010.tar.gz'' as it's full of files with Windows linefeeds which render it useless.
+
Next download the code. If you want to use the latest code, use this command:
  
== Setting up the build environment ==
+
$ '''p4 -u public -P public1234 -c public-view sync -f //depot/zcs/FRANKLIN/...'''
  
=== Installing dependencies ===
+
You should use specific, tested releases for production systems. To download a release branch, use something like this:
  
It's certain that Zimbra won't build cleanly if you just follow the various Wiki articles and README files. When the build fails, it's usually due to a missing dependency. If the error message tells you which software package is missing, you can just guess the package name
+
$ '''p4 -u public -P public1234 -c public-view sync -f //depot/zcs/FRANKLIN-5011/...'''
  
$ yum search package
+
If you're not sure which branch or directory to download, you can list the repository contents like this:
$ yum install package
 
  
Most likely you need lots of development packages. They are named ''something-devel'' in CentOS. If the build process complains about a single missing file, you can find it by installing ''yum-utils'' and then using ''repoquery'' to locate the package containing the missing file:
+
$ '''p4 -u public -P public1234 -c public-view files //depot/zcs/... > /tmp/zimbrarepo'''
 +
$ '''less /tmp/zimbrarepo'''
  
$ yum install yum-utils
+
An alternative to getting sources from Zimbra's Perforce repository is to download the ''Zimbra Community Build'' sources located [http://sourceforge.net/project/showfiles.php?group_id=224243 here]. Make sure you don't download ''FRANKLIN-5010.tar.gz'' as it's full of files with Windows linefeeds which render it useless.
$ repoquery -a -f *missing-file
 
  
This is similar to using ''apt-file'' on Debian-based systems.
+
== Setting up the build environment ==
  
 +
=== Fixing known build problems ===
  
 +
There are known problems in CentOS5 build process for FRANKLIN-5010_2660 and/or FRANKLIN-5011_2695. Instructions for fixing them can be found from the bug reports listed in "Introduction".
  
=== Run-time dependencies ===
+
=== Installing Dag repository ===
  
Run-time dependencies are checked when you run the ''install.sh'' in ''ZimbraBuild/zcs-5.0.10_GA_2660.CentOS5.FRANKLIN''. These are all installable via ''yum'' if you have ''Dag'' repositories configured:
+
Stock CentOS5 install has only a few basic repositories configured. You should definitely add the ''Dag'' repository to your yum repositories. You can get the repository information and instructions from http://dag.wieers.com/rpm/packages/rpmforge-release.
  
* NPTL
+
=== Installing buildtime, runtime and post-install dependencies ===
* sudo
 
* libidn
 
* fetchmail
 
* gmp
 
* compat-libstdc++-296
 
* compat-libstdc++-33
 
* libtool-ltdl
 
* /usr/lib/libstdc++.so.6
 
* perl-5.8.8
 
* perl-LDAP
 
* perl-Net-DNS
 
  
== Debugging the build process ==
+
'''NOTE:''' I've attached complete list of packages installed on my CentOS5.2 build system to [[Zimbra dependencies on CentOS5|this wiki page]]. When you've installed all those packages, most/all dependencies should be satisfied.
  
=== Build problem categories ===
+
Zimbra's ''buildtime'' and ''runtime dependencies'' are very poorly documented, hence it's nearly impossible to list them all. ''Runtime dependencies'' are checked when you run ''install.sh'' in ''ZimbraBuild/zcs-5.0.10-something.CentOS5.FRANKLIN''. They're not an issue when building Zimbra, but you can use the techniques outlined below to fix them. There are also some ''post-install dependencies'' that are needed when Zimbra is launched. If some of your Zimbra modules (e.g. ''amavisd'') don't start, check Zimbra's logs to see what dependency is missing, install it and restart Zimbra. You can use ''zmcontrol status'' to check module status easily.
  
You'll most likely encounter lots of errors in the build process. Instead of trying to cover all the cases, which is impossible, I'll outline the debugging process. Causes for Zimbra build problems can be divided into several categories:
+
Even though you ''should'' install all documented dependencies, they don't get you very far. A typical Zimbra build goes like this:
  
* False assumptions about the build system. For example, the build files assume ''/home/public/...'' exists.
+
* try building
* Undocumented build-time dependencies (there are lots of these)
+
* build fails
* Missing definitions files or directories, in case your OS version is not supported
+
* check the error message
* Outdated definition files, such as RPM spec files
+
* find out which package contains the missing dependency
* Wrong program version numbers or paths in build files
+
* install the missing dependency
* Version mismatches between the included third party software and OS'es *-devel packages
+
* try building
 +
* etc.
  
=== RPM spec files ===
+
In the troubleshooting section (below) I'll show what to do ''when'' a dependency is missing.
  
During actual Zimbra module build you might get errors related to RPM spec files. Most likely you'll encounter problem with legacy SPEC-file format:
+
=== Creating CentOS5-specific files and directories ===
  
#
+
Zimbra does not support building Zimbra on platforms that are not officially supported (see [http://bugzilla.zimbra.com/show_bug.cgi?id=33658 this] bug report). This means that to build on CentOS, we need to do some manual work. First create the ThirdPartyBuild directory for CentOS:
# spec file for zimbra.rpm
 
#
 
Summary: Zimbra LDAP
 
Name: zimbra-ldap
 
Version: @@VERSION@@
 
Release: @@RELEASE@@
 
# Copyright statement is no longer valid, we need to
 
# change it to ''License'' instread
 
'''License:''' OpenLDAP
 
Group: Applications/Messaging
 
URL: http://www.zimbra.com
 
Vendor: Zimbra, Inc.
 
Packager: Zimbra, Inc.
 
BuildRoot: /opt/zimbra
 
AutoReqProv: no
 
requires: zimbra-core
 
  
The ''spec'' files are in ''ZimbraBuild/rpmconf/Spec''.
+
root@zimbra: /opt/build.zimbra/source/FRANKLIN> '''mkdir -p ThirdPartyBuilds/CentOS5'''
  
=== Missing or faulty file and directories ===
+
Next create the necessary platform file for CentOS:
  
Zimbra build makes a lot of (false) assumptions about how the system is configured and what directories are available. Luckily the error messages will be rather clear, so these problems are easy to fix. During my CentOS5 install I had to do a couple of things to get things running. Here I assume you've followed the Ubuntu/Solaris build howtos while setting up your system (see above).
+
root@zimbra: /opt/build.zimbra/source/FRANKLIN/ZimbraBuild/defs> '''cp RHEL5.def CentOS5.def'''
  
P4 downloads fail without this:
+
=== Creating a JDK package for ZimbraBuild ===
  
$ '''mkdir -p /home/public/p4'''
+
The JDK creation is not covered in any other HOWTO's. You can try if your Zimbra sources include the JDK already - mine didn't. To create the JDK, first extract an official Sun JDK to a directory (here ''/opt''). Then create a tgz package from it and copy it to appropriate Zimbra directory:
 
 
Some build scripts fail without these:
 
 
 
$ '''mkdir -p /home/public/p4/zcs'''
 
$ '''ln -s /opt/build.zimbra/source/FRANKLIN /home/public/p4/zcs/main'''
 
 
 
ThirdParty modules won't build without this:
 
 
 
$ '''mkdir -p /opt/build.zimbra/source/FRANKLIN/ThirdPartyBuilds&CentOS5'''
 
 
 
Zimbra modules won't build without these:
 
 
 
$ '''cd /opt/build.zimbra/source/FRANKLIN/ZimbraBuild/defs/'''
 
$ '''cp RHEL5.def CentOS5.def'''
 
 
 
You also need to create a JDK tar.gz package and put it to the correct directory:  
 
  
 
  $ '''mkdir -p /opt/build.zimbra/source/FRANKLIN/ThirdPartyBuilds/i386/java'''
 
  $ '''mkdir -p /opt/build.zimbra/source/FRANKLIN/ThirdPartyBuilds/i386/java'''
Line 167: Line 114:
 
  JAVA_SOURCE    := $(THIRD_PARTY_BUILDS)/i386/$(JAVA_DIR)/$(JAVA_FILE)$(JAVA_VERSION)
 
  JAVA_SOURCE    := $(THIRD_PARTY_BUILDS)/i386/$(JAVA_DIR)/$(JAVA_FILE)$(JAVA_VERSION)
  
You might run into trouble when ThirdParty build creates files which are not the same name/version as those defined in actual Zimbra build files. In this case make a symbolic link or copy the file over from older/newer Zimbra source tree (if available).
+
You should also check which Java version is defined in ''ZimbraBuild/zimbracore.spec'':
 +
 
 +
if [ "x$BIT" = "x64" ]; then
 +
        ln -s /opt/zimbra/jdk1.5.0_16 /opt/zimbra/java
 +
else 
 +
        ln -s /opt/zimbra/jdk1.5.0_16 /opt/zimbra/java
 +
fi
 +
 
 +
Fix as necessary.
  
=== Missing dependencies ===
+
== Overview of the Zimbra build process ==
 +
 
 +
The Zimbra build process is well described in these two articles:
 +
 
 +
* http://varlogmessages.vroomvroom.org/documentation/ubuntu-port/ubuntu-build-instructions
 +
* http://varlogmessages.vroomvroom.org/documentation/solaris-port/build-instructions
  
During ThirdParty build process you'll eventually stumble upon missing dependencies. When a component fails, interrupt the build process with CTRL-C, enter the failed component's directory and run the build manually from there. For most components using ''make'' is enough, but some use custom build scripts. In that case launch the script instead. Once ''make'' has finished and failed, you'll most likely see an error related to a missing header files (''something.h'').
+
Use the Solaris instructions only as a reference. According to ''dijichi'', Zimbra Community Builds project manager, the Solaris instructions are more up-to-date. Unlike stated in Solaris instructions you should probably add the environment variables to ''/etc/profile.d/zimbra.sh'' instead of ''/etc/profile'' directly.
  
If Zimbra bundle already contains the necessary header file, there's most likely a problem with some Makefile. For example, the ''FRANKLIN-5010_2660'' has a bug in ''curl'' Makefile which caused header file (e.g. ''curl.h'') installation to fail silently. For more information take a look here:
+
The basic build steps are these:
  
* http://www.zimbra.com/forums/installation/23102-fc8-installation-source.html)
+
* Get the source (p4 or Zimbra community builds)
 +
* Set up the build environment
 +
* Build ThirdParty modules (''buildThirdParty.sh'')
 +
* Build ''memcached, nginx'' and ''tcmalloc'' in ''ThirdParty'' (see the README)
 +
* Build Zimbra modules (''cd ZimbraBuild;make'')
  
I fixed that issue by copying over ''ThirdParty/curl'' from newer sources obtained from Perforce repository, which seemed to work.
+
== Debugging the build process ==
  
If you verify that an external dependency is missing, you must install the correct RPM development package. The easiest to accomplish by installing ''yum-utils'' (''yum install yum-utils'') and then using ''repoquery'':
+
=== Build problem categories ===
 +
 
 +
You'll most likely encounter lots of errors in the build process. Instead of trying to cover all the cases, which is impossible, I'll outline the debugging process. Causes for Zimbra build problems can be divided into several categories:
 +
 
 +
* False assumptions about the build system. For example, the build files assume ''/home/public/...'' exists.
 +
* Undocumented build-time dependencies (there are lots of these)
 +
* Missing definitions files or directories, in case your OS version is not supported
 +
* Outdated definition files, such as RPM spec files
 +
* Wrong program version numbers or paths in build files
 +
* Version mismatches between the included third party software and OS'es *-devel packages
  
$ '''repoquery -f /usr/include/ldap.h'''
+
I've reported bugs on many of these issues (see ''Introduction'').
openldap-devel-0:2.3.27-8.el5_2.4.i386
 
openldap-devel-0:2.3.27-8.el5_1.3.i386
 
  
Note that you need to include the full path to the file. Alternatively you can use wildcards like this:
+
=== Fixing missing dependencies ===
  
$ '''repoquery -f "*ldap.h"'''
+
If the error message tells you which software package is missing, you can just guess the package name
  
Once you know the package name, install it with ''yum install packagename''.
+
$ yum search something
 +
$ yum install something
  
Then enter that component's directory, run ''make'' (or in some cases ''ant'') and see that it builds cleanly. Then you can restart the build process. If you're trying to fix a ''ThirdParty'' build failure, you might encounter these errors:
+
Most likely you need lots of development packages. They are named ''something-devel'' in CentOS. If the build process complains about a single missing file, you can find it by installing ''yum-utils'' and then using ''repoquery'' to locate the package containing the missing file:  
  
  1 out of 1 hunk ignored -- saving rejects to file servers/slapd/back-meta/search.c.rej
+
  $ yum install yum-utils
  patching file servers/slapd/back-sql/config.c
+
  $ repoquery -a -f *missing-file
Reversed (or previously applied) patch detected!  Assume -R? [n] n
 
Apply anyway? [n] n
 
  
These are caused by the fact that Zimbra-specific patches have already been applied, but the build file tried to apply them anyway. You can safely say ''n'' to all of these. Or just tap return repeatedly
+
If you get several possible packages, make an educated guess.
  
=== Tips to making the build process faster ===
+
=== Debugging ThirdParty build process ===
  
It's highly unlikely that Zimbra build will success on the first try. By default the Zimbra build scripts are pretty stupid, as they remove all that was left in the previous run and recompile everything from start. This means that when a ThirdParty module fails, the script recompiles everything all over again. To avoid this, build try building the modules individually until they all succeed.
+
During ThirdParty build process you'll eventually stumble upon missing dependencies. You can use the ''buildThirdParty.sh'' script at first (see bugs above). When the first component fails, you should interrupt the build process with CTRL-C, enter the failed component's directory and run the build manually from there. For most components using ''make'' is enough, but some use custom build scripts. In that case launch that script instead. Once ''make'' has finished and failed, you'll most likely see an error related to a missing header files (''something.h''). Locate and install the dependency as outlined above. If Zimbra bundle already contains the necessary header file, there's most likely a problem with some Makefile. Next retry building the failed module. If all goes well, you can continue building the next module (and so on).
  
 
The correct compile order for Zimbra ThirdParty software can be seen from the ''ThirdParty/Makefile''. In ''FRANKLIN-5010_2660'' community build the correct order is this:
 
The correct compile order for Zimbra ThirdParty software can be seen from the ''ThirdParty/Makefile''. In ''FRANKLIN-5010_2660'' community build the correct order is this:
Line 228: Line 198:
 
</pre>
 
</pre>
  
When you fix the failed module, enter the next one's directory, build it and fix it (if necessary) and so on. In the end all modules should have been built. You can use the same technique for building the actual ''Zimbra modules''. You just need to follow this order:
+
You might also run into trouble when ThirdParty build creates files which are not the same name/version as those defined in actual Zimbra build files. In this case make a symbolic link or copy the file over from older/newer Zimbra source tree (if available).
 +
 
 +
=== Debugging Zimbra module build ===
 +
 
 +
It's highly unlikely that Zimbra build will success on the first try. By default the Zimbra build scripts are pretty stupid, as they remove all that was left in the previous run and recompile everything from start. You can save time using the same build technique as for ThirdParty modules. You just need to follow this build order:
  
 
<pre>
 
<pre>
Line 243: Line 217:
 
</pre>
 
</pre>
  
This order was taken from http://varlogmessages.vroomvroom.org/documentation/solaris-port/build-instructions/build-zimbra-server.
+
(taken from http://varlogmessages.vroomvroom.org/documentation/solaris-port/build-instructions/build-zimbra-server)
 
 
 
 
 
 
 
 
== Introduction ==
 
 
 
This HOWTO covers the basic steps required to build Zimbra. For more information, see these essential documents:
 
 
 
* [http://varlogmessages.vroomvroom.org/documentation/solaris-port/build-instructions Building Zimbra on Solaris]
 
* [[Building Zimbra using Perforce]]
 
* [[Franklin README]]
 
 
 
These might be helpful, too:
 
 
 
* [http://varlogmessages.vroomvroom.org/documentation/freebsd-port Building Zimbra on FreeBSD]
 
* [http://varlogmessages.vroomvroom.org/documentation/ubuntu-port/ubuntu-build-instructions Building Zimbra on Ubuntu Hardy]
 
 
 
 
 
== Preparing the build environment ==
 
 
 
Stock CentOS5 install has only a few basic repositories configured. You need to add ''rpmforge'' to your list of yum repositories. You can get the repository information and instructions from http://dag.wieers.com/rpm/packages/rpmforge-release.
 
 
 
== Troubleshooting ==
 
 
 
Zimbra build problems can be divided into a couple main categories:
 
  
* Undocumented, missing dependencies
+
== Installing Zimbra ==
* Faulty assumptions about the build environment
 
* Problems with the sources or the downloaded source tree
 
  
Instead of trying to document every problem I encountered, I'll simply describe how these problems can be circumvented.
+
After you've successfully built Zimbra, go to
  
 +
    $ /opt/build.zimbra/source/FRANKLIN/ZimbraBuild/zcs-something-CentOS5.FRANKLIN
 +
    $ ./install.sh
  
 +
That should take care of the Zimbra install. Ignore any complains about the OS version.
  
 
{{Article Footer|unknown|4/28/2008}}
 
{{Article Footer|unknown|4/28/2008}}

Latest revision as of 12:48, 24 March 2015


Introduction

Building Zimbra from source is necessary if we want to make modifications to it. The binary release of the so-called open source version is released under a restrictive ZEULA (Zimbra End-user License Agreement), which disallows any modifications. Building Zimbra from source allows us to use the less restrictive YPL 1.1 (Yahoo Public License). Even though the YPL 1.1 is not an OSI-approved license, it still allows modifications. It is "badgeware", though, meaning that Zimbra/Yahoo logos need to be included in any modifications.

The build process for Zimbra is poorly documented. You won't find many useful articles from the Zimbra wiki or from the forums. Lots of the articles are obsolete. The only really good instructions are here, provided by the Zimbra Community Builds project. Currently (3rd Dec 2008) the only other useful articles in the Zimbra wiki are located here

I've filed several bug reports related to CentOS5 build process. These bugs are relevant at least for FRANKLIN-5010_2660 and/or FRANKLIN-5011_2695.

Until these problems are fixed, you will probably encounter them.

Alternatives to source install

  • If ZEULA restrictions are not a concern, use the ZCS "Open Source Edition" binary installer, which is trivial to install
  • If you're willing to run Zimbra on Ubuntu or Solaris, get the appropriate packages from Zimbra Community Builds. They might (or might not) work.
  • If you require Outlook support, Symbian mobile clients or such, get the trial version for a commercial version of Zimbra.

Getting the source

There are two main places where to get the Zimbra sources:

The latest Zimbra code - including the ThirdParty packages - is located in a proprietary Perforce (p4) repository. If you're doing a production build, you should try to download a stable branch. In case you're going to do development, you should probably get HEAD (=development branch). I probably downloaded HEAD at first, as there were numerous stupid errors in the build files that I had to fix.

To can get FRANKLIN (ZCS 5.0.x) from Perforce repositories, you need to get the proprietary Perforce (P4) client from http://www.perforce.com/perforce/downloads/index.html

Once p4 binary is installed, do the following:

$ mkdir -p /home/public/p4
$ export P4EDITOR=nano
$ export P4PORT=codes.zimbra.com:2666

You set the variables in root's $HOME/.bashrc, /etc/profile.d/zimbra.sh or whereever you'd like. That way you don't have to retype them every time you check out the sources. The mkdir is required, because that's where Perforce wants it's stuff to go. It's probably possible to change it's behavior, but hacking around it is faster. After running this command you should have Zimbra sources in /home/public/p4/FRANKLIN/. If you wish to use another directory, you should symlink it to /home/public/p4 to avoid trouble later on. Zimbra's build system assumes some files are located there.

Next download the code. If you want to use the latest code, use this command:

$ p4 -u public -P public1234 -c public-view sync -f //depot/zcs/FRANKLIN/...

You should use specific, tested releases for production systems. To download a release branch, use something like this:

$ p4 -u public -P public1234 -c public-view sync -f //depot/zcs/FRANKLIN-5011/...

If you're not sure which branch or directory to download, you can list the repository contents like this:

$ p4 -u public -P public1234 -c public-view files //depot/zcs/... > /tmp/zimbrarepo
$ less /tmp/zimbrarepo

An alternative to getting sources from Zimbra's Perforce repository is to download the Zimbra Community Build sources located here. Make sure you don't download FRANKLIN-5010.tar.gz as it's full of files with Windows linefeeds which render it useless.

Setting up the build environment

Fixing known build problems

There are known problems in CentOS5 build process for FRANKLIN-5010_2660 and/or FRANKLIN-5011_2695. Instructions for fixing them can be found from the bug reports listed in "Introduction".

Installing Dag repository

Stock CentOS5 install has only a few basic repositories configured. You should definitely add the Dag repository to your yum repositories. You can get the repository information and instructions from http://dag.wieers.com/rpm/packages/rpmforge-release.

Installing buildtime, runtime and post-install dependencies

NOTE: I've attached complete list of packages installed on my CentOS5.2 build system to this wiki page. When you've installed all those packages, most/all dependencies should be satisfied.

Zimbra's buildtime and runtime dependencies are very poorly documented, hence it's nearly impossible to list them all. Runtime dependencies are checked when you run install.sh in ZimbraBuild/zcs-5.0.10-something.CentOS5.FRANKLIN. They're not an issue when building Zimbra, but you can use the techniques outlined below to fix them. There are also some post-install dependencies that are needed when Zimbra is launched. If some of your Zimbra modules (e.g. amavisd) don't start, check Zimbra's logs to see what dependency is missing, install it and restart Zimbra. You can use zmcontrol status to check module status easily.

Even though you should install all documented dependencies, they don't get you very far. A typical Zimbra build goes like this:

  • try building
  • build fails
  • check the error message
  • find out which package contains the missing dependency
  • install the missing dependency
  • try building
  • etc.

In the troubleshooting section (below) I'll show what to do when a dependency is missing.

Creating CentOS5-specific files and directories

Zimbra does not support building Zimbra on platforms that are not officially supported (see this bug report). This means that to build on CentOS, we need to do some manual work. First create the ThirdPartyBuild directory for CentOS:

root@zimbra: /opt/build.zimbra/source/FRANKLIN> mkdir -p ThirdPartyBuilds/CentOS5

Next create the necessary platform file for CentOS:

root@zimbra: /opt/build.zimbra/source/FRANKLIN/ZimbraBuild/defs> cp RHEL5.def CentOS5.def

Creating a JDK package for ZimbraBuild

The JDK creation is not covered in any other HOWTO's. You can try if your Zimbra sources include the JDK already - mine didn't. To create the JDK, first extract an official Sun JDK to a directory (here /opt). Then create a tgz package from it and copy it to appropriate Zimbra directory:

$ mkdir -p /opt/build.zimbra/source/FRANKLIN/ThirdPartyBuilds/i386/java
$ cd /opt/build.zimbra/source/FRANKLIN/ThirdPartyBuilds/i386/java
$ tar -C /opt -zcf jdk1.5.0_16.tgz jdk1.5.0_16

You probably need to change the Java version in ZimbraBuild/defs/plat_common.def too:

JAVA_VERSION    := 1.5.0_16
JAVA_FILE       := jdk
JAVA_DIR        := java
JAVA_SOURCE     := $(THIRD_PARTY_BUILDS)/i386/$(JAVA_DIR)/$(JAVA_FILE)$(JAVA_VERSION)

You should also check which Java version is defined in ZimbraBuild/zimbracore.spec:

if [ "x$BIT" = "x64" ]; then
        ln -s /opt/zimbra/jdk1.5.0_16 /opt/zimbra/java
else   
        ln -s /opt/zimbra/jdk1.5.0_16 /opt/zimbra/java
fi

Fix as necessary.

Overview of the Zimbra build process

The Zimbra build process is well described in these two articles:

Use the Solaris instructions only as a reference. According to dijichi, Zimbra Community Builds project manager, the Solaris instructions are more up-to-date. Unlike stated in Solaris instructions you should probably add the environment variables to /etc/profile.d/zimbra.sh instead of /etc/profile directly.

The basic build steps are these:

  • Get the source (p4 or Zimbra community builds)
  • Set up the build environment
  • Build ThirdParty modules (buildThirdParty.sh)
  • Build memcached, nginx and tcmalloc in ThirdParty (see the README)
  • Build Zimbra modules (cd ZimbraBuild;make)

Debugging the build process

Build problem categories

You'll most likely encounter lots of errors in the build process. Instead of trying to cover all the cases, which is impossible, I'll outline the debugging process. Causes for Zimbra build problems can be divided into several categories:

  • False assumptions about the build system. For example, the build files assume /home/public/... exists.
  • Undocumented build-time dependencies (there are lots of these)
  • Missing definitions files or directories, in case your OS version is not supported
  • Outdated definition files, such as RPM spec files
  • Wrong program version numbers or paths in build files
  • Version mismatches between the included third party software and OS'es *-devel packages

I've reported bugs on many of these issues (see Introduction).

Fixing missing dependencies

If the error message tells you which software package is missing, you can just guess the package name

$ yum search something
$ yum install something

Most likely you need lots of development packages. They are named something-devel in CentOS. If the build process complains about a single missing file, you can find it by installing yum-utils and then using repoquery to locate the package containing the missing file:

$ yum install yum-utils
$ repoquery -a -f *missing-file

If you get several possible packages, make an educated guess.

Debugging ThirdParty build process

During ThirdParty build process you'll eventually stumble upon missing dependencies. You can use the buildThirdParty.sh script at first (see bugs above). When the first component fails, you should interrupt the build process with CTRL-C, enter the failed component's directory and run the build manually from there. For most components using make is enough, but some use custom build scripts. In that case launch that script instead. Once make has finished and failed, you'll most likely see an error related to a missing header files (something.h). Locate and install the dependency as outlined above. If Zimbra bundle already contains the necessary header file, there's most likely a problem with some Makefile. Next retry building the failed module. If all goes well, you can continue building the next module (and so on).

The correct compile order for Zimbra ThirdParty software can be seen from the ThirdParty/Makefile. In FRANKLIN-5010_2660 community build the correct order is this:

DIRS := openssl \
        mysql \
        sleepycat \
        libxml2 \
        heimdal \
        curl \
        cyrus-sasl \
        openldap \
        aspell \
        clamav \
        apache-httpd \
        php \
        pcre \
        expat \
        popt \
        PostFix \
        dspam \
        rrdtool \
        snmp

You might also run into trouble when ThirdParty build creates files which are not the same name/version as those defined in actual Zimbra build files. In this case make a symbolic link or copy the file over from older/newer Zimbra source tree (if available).

Debugging Zimbra module build

It's highly unlikely that Zimbra build will success on the first try. By default the Zimbra build scripts are pretty stupid, as they remove all that was left in the previous run and recompile everything from start. You can save time using the same build technique as for ThirdParty modules. You just need to follow this build order:

ore
proxy
mta
store
ldap
snmp
logger
apache
spell
zcs_stage

(taken from http://varlogmessages.vroomvroom.org/documentation/solaris-port/build-instructions/build-zimbra-server)

Installing Zimbra

After you've successfully built Zimbra, go to

   $ /opt/build.zimbra/source/FRANKLIN/ZimbraBuild/zcs-something-CentOS5.FRANKLIN
   $ ./install.sh 

That should take care of the Zimbra install. Ignore any complains about the OS version.

Verified Against: unknown Date Created: 4/28/2008
Article ID: https://wiki.zimbra.com/index.php?title=Building_FRANKLIN_on_CentOS_5 Date Modified: 2015-03-24



Try Zimbra

Try Zimbra Collaboration with a 60-day free trial.
Get it now »

Want to get involved?

You can contribute in the Community, Wiki, Code, or development of Zimlets.
Find out more. »

Looking for a Video?

Visit our YouTube channel to get the latest webinars, technology news, product overviews, and so much more.
Go to the YouTube channel »

Jump to: navigation, search