Building FRANKLIN on CentOS 5
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:
Until these problems are fixed, you will stumble upon 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:
- Zimbra Community Builds (http://sourceforge.net/projects/zimbracommunity)
- 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.
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
Once p4 binary is installed, do the following:
$ mkdir -p /home/public/p4 $ export P4EDITOR=nano $ 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.
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
Installing RPMForge repositories
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 and runtime dependencies
Zimbra's buildtime and runtime dependencies are very poorly documented. Hence it's nearly impossible to list them all. Runtime dependencies are check 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. 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
In the troubleshooting section (below) I'll show what to do when a dependency is missing.
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
- Build memcached, nginx and tcmalloc in ThirdParty
- Create a JDK tgz package
- Build Zimbra modules
The JDK creation is not covered in the above 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)
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. 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). Locate and install the dependency as outline above. Then retry building that module. If all goes well, you can restart the build process. If Zimbra bundle already contains the necessary header file, there's most likely a problem with some Makefile. 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.
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).
Tips to making the build process faster
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.
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
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:
ore proxy mta store ldap snmp logger apache spell zcs_stage
This order was taken from http://varlogmessages.vroomvroom.org/documentation/solaris-port/build-instructions/build-zimbra-server.
This HOWTO covers the basic steps required to build Zimbra. For more information, see these essential documents:
These might be helpful, too:
Zimbra build problems can be divided into a couple main categories:
- Undocumented, missing dependencies
- 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.