Setting up a Zimbra development environment

Welcome to Zimbra Open Source!!

First things first let’s set up a development environment. I used a separate box and started from a clean install. Feel free to skip this step if you’ve got an existing Fedora or RHEL 4 install. I did a minimal install of Fedora Core 3. To make things easier disable the firewall and SELinux. Otherwise you may have issues getting the install working. The full source build/install notes have been included below. You can also find this readme in the zcs-src.tgz under ZimbraWebClient/WebRoot/adminhelp/CS/txt/readme_source.txt

If you run into issues or have questions please feel free to ask in our developer forums.

Zimbra Collaboration Suite Source – Build HOWTO
———————————————–

Zimbra Collaboration Suite (ZCS) sources can be built in two distinct ways:

(a) binary release that produces RPMs and a wrapper install.sh script

(b) developer install that is amenable to incremental builds

At this time, inside Zimbra, we build on RedHat Enterprise Linux 4 and Fedora Core 3. If you want to build on other distributions, please be aware that our build does use pre-compiled (by us) versions postfix, openldap, etc. – on other distributions, you might run into shared library version problems with these binaries. In the near future, resources permitting and with help from the community, we would like to make our builds as friendly across as many distributions as possible.

For both build types, you need:

– Java Development Kit (version 1.5.0_04 is recommended) from http://java.sun.com/. The bin directory containing the javac, java, jar, etc. commands must be in your PATH.

– Apache Ant (minimum version 1.6.2) from http://ant.apache.org. Make sure the ant command is in your PATH.

– Install gcc and its friends. You will need this if you are rebuilding any of our pre-compiled binaries.

– Install rpm-build. This is required for building a binary release with RPMs.

– Install ‘which’ – this package is not present in a minimal operating system install.

Building (a) binary release is simple:

$ mkdir ~/zcs-src
$ cd ~/zcs-src
$ tar xvfz /path/to/your/downloads/zcs-src.tgz
$ cd ZimbraBuild
$ make allclean
$ make
$ ls -l zcs/

If you got the source, and want to hack on it, you’re probably more interested in the rest of this document – how to do a developer friendly install with incremental builds.

You must not perform a developer install on a system that has had a binary release installed on it earlier – otherwise you might trample files that are under RPM’s ownership/control. One of the primary differences between (a) binary release and (b) developer install is that (a) runs all software as the Linux user ‘zimbra’, while (b) is designed to run as you. At this time, re-purposing a system which has the binary release into a developer install is not recommend as it is not fully tested, but this works for us (see also bug 3791):

# /opt/zimbra/bin/zmiptables -u
# /path/to/your/binary/release/install.sh -u

Similarly, when re-purposing a developer install for installing a binary release, be sure to undo all steps in the developer install,
including removing /etc/sudoers entries with your login name.

We also recommend that you remove any postfix, sendmail, openldap, mysql RPMs that might have come with your distribution installation – or tailor your PATH such that you do not use those programs against data generated by the versions inside ZCS.

Building (b) developer install requires the following steps. In a binary install, these steps are performed by scripts inside the RPMs.
In a developer install we like to make these steps explicit so you are aware what exact changes are made to your development machine – which is important if said machine is also your desktop!

– Make yourself a fresh zimbra directory (substitute ‘john’ with your login name). You need to run these commands as root.

# mv /opt/zimbra /opt/zimbra.old # in case it’s there
# mkdir /opt/zimbra
# chown john:john /opt/zimbra

– Unpack the source tgz file. Note that ‘$’ to indicate you run these as yourself.

$ mkdir ~/zcs-src
$ cd ~/zcs-src
$ tar xvfz /path/to/your/downloads/zcs-src.tgz

– Create a symbolic link /usr/local/java that points at your JDK installation. Ant requires JAVA_HOME to be set, and we set it to
/usr/local/java in the build. Eg:

# ls -l /usr/local/java
ls: /usr/local/java: No such file or directory
# ln -s /usr/java/jdk1.5.0_04 /usr/local/java
# ls -l /usr/local/java
lrwxrwxrwx 1 root root 21 Aug 29 09:22 /usr/local/java -> /usr/java/jdk1.5.0_04

– Go into the build directory, and make the dev-install target so your /opt/zimbra directory is populated with the software for the first time. You need to do this step whenever you blow away your /opt/zimbra directory.

$ cd ~/zcs-src/ZimbraBuild
$ make dev-install

– Your /etc/hosts file should identify 127.0.0.1 as ‘localhost’ or ‘localhost.localdomain’. Having any other name as the first name
for this address will cause the developer build to fail because the build’s mysql client will not be able to authenticate. Example
valid entry:

127.0.0.1 localhost.localdomain localhost

– Add these directories to your /etc/ld.so.conf file:

/opt/zimbra/lib
/opt/zimbra/sleepycat/lib
/opt/zimbra/openldap/lib
/opt/zimbra/cyrus-sasl/lib

Run the program ‘ldconfig’ so the change to /etc/ld.so.conf goes
into effect.

# ldconfig

– As root, edit your /etc/sudoers files to add these three lines
(substitute ‘john’ with your login name):

john ALL=NOPASSWD:/opt/zimbra/openldap/libexec/slapd
john ALL=NOPASSWD:/opt/zimbra/postfix/sbin/postfix
john ALL=NOPASSWD:/opt/zimbra/postfix/sbin/postalias

This is mostly because you need to start postfix and ldap, and they
need to bind to ports < 1024 which requires root privileges. - Run these commands as root to initialize postfix: # groupadd postdrop # groupadd postfix # useradd -d /opt/zimbra/postfix -g postfix postfix # /opt/zimbra/postfix/sbin/postfix set-permissions # chmod 775 /opt/zimbra/postfix/conf - Run the following commands as yourself to initialize mysql, ldap, and Zimbra's postfix configurator. $ /opt/zimbra/bin/zmmyinit $ /opt/zimbra/bin/zmldapinit $ /opt/zimbra/bin/zmmtainit localhost $ /opt/zimbra/bin/zmmtaconfig mta - Change the ldap and mysql password to values hardcoded inside developer build. $ /opt/zimbra/bin/zmldappasswd zimbra $ /opt/zimbra/bin/zmldappasswd --root zimbra $ /opt/zimbra/bin/zmmypasswd zimbra $ /opt/zimbra/bin/zmmypasswd --root zimbra You have successfully initialized ZCS. You are now ready for incremental change, build, test cycles: - The build takes caring of starting and stopping tomcat and ldap. In case of a system reboot, the build (right now) does not know how to start mysql or postfix. So make sure you do this step manually at least once after a system reboot: $ /opt/zimbra/bin/postfix stop $ /opt/zimbra/bin/postfix start $ /opt/zimbra/bin/mysql.server stop $ /opt/zimbra/bin/mysql.server start - In order to blow away all mailboxes, and create some new ones (think of it as make clean), you can perform these steps: $ cd ~/zcs-src/ZimbraServer $ ant reset-the-world $ cd ~/zcs-src/ZimbraWebClient $ ant deploy - If you have made a change to the server code inside the ZimbraServer directory, but wish to install these changes without destroying any existing mailboxes and data: $ cd ~/zcs-src/ZimbraServer $ ant service-deploy - If you have made changes to the Ajax/ or ZimbraWebClient/, you have to do: $ cd ~/zcs-src/ZimbraWebClient $ ant deploy - When using the developer install, the URL for the application is: http://localhost:7070/zimbra/mail

No trailing slash, please. This is because tomcat does not bind to port 80 in the developer install. Build creates the account ‘user1’ with password ‘test123’; you should be able to login to with this pair.

– In order to shutdown the developer install, you must shutdown these four services:

$ /opt/zimbra/bin/tomcat stop
$ /opt/zimbra/bin/mysql.server stop
$ /opt/zimbra/bin/ldap stop
$ /opt/zimbra/bin/postfix stop

ZimbraServer and ZimbraClient directories contain ‘.project’ files which make these directories usable with Eclipse 3.0 or higher
(http://www.eclipse.org/). You can import these directories as projects inside Eclipse. You will have to change the Eclipse Java/Compiler/Compliance settings source and target versions to 1.4 – the default settings error on references assert(), a 1.4 feature. You can then perform the ant tasks ‘reset-the-world’, ‘service-deploy’ and ‘deploy’, by visiting the respective build.xml files from inside Eclipse.