Revision as of 14:59, 13 July 2015 by Jorge de la Cruz (talk | contribs)
(diff) ← Older revision | Latest revision (diff) | Newer revision → (diff)


   KB 1360        Last updated on 2015-07-13  

(0 votes)

Zimbra developer environment is a little convoluted to bring up. The good news is, we can get the same environment via Zimbra Desktop. Zimbra Desktop comes with installer so its relatively easy and quick to create developer environment on top of that. This wiki page explains everything that's necessary to get your development environment up and running. It also has hacks or tips to make developer's life easier. PS: This wiki page uses window's style for paths.

Zimbra Desktop Basic Configuration

1. Download Zimbra Desktop http://www.Zimbra.com/products/desktop_download.html

2. Install Zimbra desktop to C:\zdesktop or some easy to reach location.

3. Configure your Zimbra Desktop with a dummy/test gmail or yahoo account.

(PS: Steps 4 & 5 can be skipped once Zimbra Desktop goes RC2(build 1513) or later, currently it is RC1(build 1482)

4. Configure Zimbra Desktop to permit Zimlets

Open localconfig.xml in <installDirectory aka zdesktop>\conf\localconfig.xml

And replace..

 <key name="zdesktop_installation_key">

 <key name="zdesktop_installation_key">
 <key name="Zimbra_ldap_password">

.. [CURRENT_VALUE] is whatever key Zimbra Desktop generated and should be same for both "zdesktop_installation_key" and "Zimbra_ldap_password"

5. Restart Zimbra Desktop (Right click on system tray icon and click ShutDown Service, and then start Zimbra Desktop again)

Development Hacks and using Zimbra Desktop as Web Application

PS: Use these tips to get yourself up-and-running with Zimlet development via Zimbra Desktop in no-time

Hack #1 Use Zimbra Desktop as a web-application

Zimbra desktop uses Prism which is essentially Firefox. And it also provides a way to open it via a browser. This means we can use the powerful Firebug for Javascript debugging! Setup:

  1. Open Zimbra Desktop
  2. Click on Account Setup
  3. Click on Open in Web-Browser Link. (PS: if it opens in IE, copy that link to Firefox since we need Firebug)
  4. Click on Launch Application (you need the url after you logged in)
  5. Bookmark the url; its going to look something like:

PS: Remove the last #1(or you might see #2 or #3) at the very end during bookmarking to make it..

Hack #2 dev=1 the developer mode

When Zimbra is loaded it zips and and unformats all the javascript code to speedup the login time. Also, it doesnt load all the modules(like calendar, documents etc) and loads them only when needed(aka 'lazy' loading). Finally, Zimbra also has a built-in debugger-window and is also disabled in non-debug mode. However, For developement and debugging purposes Zimbra provides a developer mode. You can turn-on this mode by simply appending dev=1 to the launch-url. In this mode, all the modules are loaded-upfront, all the javascript code are readable, and you will also see debug-window. Now open the bookmark you made earlier(in hack #2) and append dev=1


Obviously, you can have two bookmarks, one with debug on and the other with off.

One more important note: When you develop Zimlets in debug-mode ON, as mentioned earlier, you will have to test your Zimlet with non-debug mode (without &dev=1 to make sure it still works with lazy loading. In some cases, it wont since your Zimlet might depend on some module being loaded and you will have to write code to load some missing modules and such issues

Hack #3 Create _dev folder:

  • When the Zimlet is deployed, its copied to zdesktop\jetty\webapps\service\Zimlet and needs deploy-restart-service-undeploy for every small change. But for development we can circumvent this by creating a folder called "_dev" under service\Zimlet\ folder and manually copying and developing Zimlet within that folder until its fully done and production ready.

Say you are developing a Zimlet com_Zimbra_test,

  1. First navigate and create a _dev directory like below:
 <Zimbra Desktop install directory aka zdesktop>\jetty\webapps\service\Zimlet\
  1. Then, create the Zimlet folder within _dev

<Zimbra Desktop install directory aka zdesktop>\jetty\webapps\service\Zimlet\_dev\com_Zimbra_test


  1. If your Zimlet is accessing external sites via javascript(not jsp), Please go through Hack #4 Proxy Hack. You will have to deploy a (different) Zimlet that opens-up that domain.

Hack #4 Proxy Hack


  1. This is for accessing external sites directly from javascript (you don't need this if jsp was used)
  2. This provides a Zimlet File:Com zimbra openalldomains.zip that helps open-up all domains for proxy use. But use this only in developer environment

Whenever you access external site(say *.yahoo.com) you need to tell(register in ldap) the backend-server that yahoo.com is OK to access. i.e. we need to set allowedDomains parameter in config_template.xml for that domain and actually *deploy* the zimlet. Now, in _dev, we don't really deploy the zimlet but simply use a server hack to make it work and so the allowedDomains isn't registered in ldap. However, if we deploy the zimlet, then we can't keep it in _dev since it would duplicate zimlets, i.e you will see 2 instances of the zimlets. So, what I normally do is to create a dummy-zimlet (com_zimbra_test) and in that I allow ALL domains( "*" instead of "*.yahoo.com")and deploy that. Since allowedDomains property is a global property, its then applicable for all the zimlets I develop.

So deploythe File:Com zimbra openalldomains.zip Zimlet only on your test-box so that you can use any zimlets _dev that might need to access external websites via Javascript.

This zimlet has a config_template.xml file that has the following:

<zimletConfig name="com_zimbra_openalldomains" version="1.0">
        <property name="allowedDomains">*</property>

Important Notes: 1. Deploy == don't keep in _dev but use manual steps or Zimlet installer to actually install it. Please see the Deploying and Undeploying Production level Zimlets for more information on how to deploy a Zimlet.

2. When a Zimlet goes to production, it needs to have its own config_template.xml file that opens-up only required domain, something like

<zimletConfig name="com_zimbra_myzimlet" version="1.0">
        <property name="allowedDomains">rss.news.yahoo.com</property>

Hack #5 Firebug & debugging tips

Firebug is perhaps world's best javascript debugging tool out there. Download it and enable every setting it, you will use everything during the course of the Zimlet development. http://getfirebug.com/

1. debugger; statement. This is perhaps the most convenient thing within Firebug. Simply write that statement anywhere and javascript execution halts there.

com_Zimbra_test.prototype.function = function() {

 var i =0;
 debugger;  //javascript halts right on this line


2. The other thing that helps is... console.log(someVariable); //this some variable is printed in Firebug's log

3. more information can be found here: http://getfirebug.com/logging.html

Hack #6 Firebug Net(network) tab

When accessing services the two common errors we get are are 403 and 500. In firebug, you can easily debug these and many other http errors using Net or network tab.

  1. Error 403 == permission denied; or access it not allowed and
  2. Error 500 == your request is incorrect; i.e.the url or some parameter isnt properly formatted or constructed

Notes: Of course, apart from debugging errors, you can also see soap-requests and soap-responses and all the network traffic.

Hack #7 Firefox Settings

Everytime we load Zimlets in browser it caches in the browser. To make sure we dont cache but still keep cookies and authtokens, perform the following configuration settings.

  1. Open Firefox's > Tools > Options > Privacy
  2. Click on Settings
  3. Check Cache
  4. Uncheck Authenticated Sessions
  5. Uncheck cookies
  6. Press OK
  7. Also Check "Always clear my private data when i close firefox". This will help in clearing cache whenever we press Refresh.
  8. Finally, Uncheck Ask me before Clearing private data, you most likely dont want it to keep asking your permission.

Deploying and undeploying 'Production-level' Zimlets

PS: only for production level Zimlets that are ready-to-go for actual deployment. For Zimlet that are under construction, see "DEVELOPMENT HACKS or TIPS" section

On Windows:

There are two ways to deploy or undeploy a zimlet in Zimbra Desktop.

  1. Manual installation
  2. Using "Zimlet Installer.hta"

1. Deploying Zimlets manually

1. CD to 'zdesktop' folder (the following command is relative to zdesktop)

2. Run the following java command...

java -cp <required jar files> -DZimbra.config=conf/localconfig.xml com.Zimbra.cs.Zimlet.ZimletUtil deploy <PATH to Zimlet.zip file>\com_Zimbra_hello.zip
java -cp jetty\lib\log4j-1.2.8.jar;jetty\common\lib\commons-httpclient-3.0.jar;jetty\common\lib\mail.jar;jetty\common\lib\commons-logging.jar;jetty\common\lib\commons-codec-1.3.jar;jetty\common\lib\json.jar;jetty\common\lib\dom4j-1.5.jar;jetty\common\lib\zimbracommon.jar;jetty\webapps\service\WEB-INF\lib\zimbrastore.jar -Dzimbra.config=conf\localconfig.xml com.zimbra.cs.zimlet.ZimletUtil deploy C:\path\to\zimletZipfile\com_Zimbra_hello.zip

3. Shutdown Zimbra Service

4. Start Zimbra Desktop again

2. Deploying Zimlets via "Zimlet Installer.hta":

  1. Download File:ZimletInstallerForWindows.zip and unzip to get ZimletInstallerForWindows.hta file
  2. keep Zimbra Desktop should be running
  3. Open Zimlet Installer.hta and browse to the Zimlet zip file
  4. Hit Deploy


  • When Zimlet is deployed, it gets registered in ldap and also the Zimlet files are unzipped and copied to <zdesktop>\jetty\webapps\service\Zimlet folder.
  • This will deploy the Zimlet and restarts Zimbra Desktop Service
  • You should see Zimlet after the restart.
  • All Production Zimlets needs to be *deployed* and needs a restart. While developing a Zimlet however we will use _dev folder which

would over-come this.

1. UnDeploying Zimlets manually

1. CD to 'zdesktop' folder (the following command is relative to zdesktop)

2. Run the following command.

java -cp <required jar files> -DZimbra.config=conf/localconfig.xml com.Zimbra.cs.Zimlet.ZimletUtil undeploy <JUST-THE-Zimlet-HANDLER-NAME-WITHOUT-DOTZIP>
java -cp jetty\lib\log4j-1.2.8.jar;jetty\common\lib\commons-httpclient-3.0.jar;jetty\common\lib\mail.jar;jetty\common\lib\commons-logging.jar;jetty\common\lib\commons-codec-1.3.jar;jetty\common\lib\json.jar;jetty\common\lib\dom4j-1.5.jar;jetty\common\lib\zimbracommon.jar;jetty\webapps\service\WEB-INF\lib\zimbrastore.jar -Dzimbra.config=conf\localconfig.xml com.zimbra.cs.zimlet.ZimletUtil undeploy C:\path\to\zimletZipfile\com_Zimbra_hello.zip

3. Shutdown Zimbra Service

4. Start Zimbra Desktop again

Undeploying Zimlets via "Zimlet Installer.hta":

  1. Keep Zimbra Desktop should be running
  2. Open Zimlet Installer.hta and enter Zimlet's handler name like: com_Zimbra_test (without .zip) in the undeploy field
  3. Hit UnDeploy
  • This will UnDeploy the Zimlet and restarts Zimbra Desktop Service
  • You should see Zimlet go away after the restart.


  • There is a server bug that causes undeployer not to delete Zimlet files in <zdesktop>\jetty\webapps\service\Zimlet folder. It wont hurt, but you can manually delete it if need be.

On MacOSX:

You will have to run java command to install and uninstall..

Deploy Zimlets

1. CD to zdesktop install folder

2. Run the following java command...

java -cp <required jar files> -DZimbra.config=conf/localconfig.xml com.Zimbra.cs.Zimlet.ZimletUtil deploy <PATH to Zimlet.zip file>/com_Zimbra_hello.zip
java -cp jetty/lib/log4j-1.2.8.jar:jetty/common/lib/commons-httpclient-3.0.jar:jetty/common/lib/mail.jar:jetty/common/lib/commons-logging.jar:jetty/common/lib/commons-codec-1.3.jar:jetty/common/lib/json.jar:jetty/common/lib/dom4j-1.5.jar:jetty/common/lib/Zimbracommon.jar:jetty/webapps/service/WEB-INF/lib/Zimbrastore.jar -DZimbra.config=conf/localconfig.xml com.Zimbra.cs.Zimlet.ZimletUtil deploy ~/Y/Zimlets/com_Zimbra_hello.zip

3. Shutdown Zimbra Desktop Service and Start it


  • When Zimlet is deployed, it gets registered in ldap and also the Zimlet files are unzipped and copied to <zdesktop>\jetty\webapps\service\Zimlet.

Undeploy Zimlet:

1. CD to zdesktop install folder

2. Run the following command..

java -cp <required jar files> -DZimbra.config=conf/localconfig.xml com.Zimbra.cs.Zimlet.ZimletUtil undeploy <JUST-THE-Zimlet-HANDLER-NAME-WITHOUT-DOTZIP>
java -cp jetty/lib/log4j-1.2.8.jar:jetty/common/lib/commons-httpclient-3.0.jar:jetty/common/lib/mail.jar:jetty/common/lib/commons-logging.jar:jetty/common/lib/commons-codec-1.3.jar:jetty/common/lib/json.jar:jetty/common/lib/dom4j-1.5.jar:jetty/common/lib/Zimbracommon.jar:jetty/webapps/service/WEB-INF/lib/Zimbrastore.jar -DZimbra.config=conf/localconfig.xml com.Zimbra.cs.Zimlet.ZimletUtil undeploy com_Zimbra_hello
Note: For undeploying just use the Zimlet-handler-name (not the path and also dont include .zip)

3. Shutdown Zimbra Desktop Service and start it


  • There is a server bug that causes undeployer not to delete Zimlet files in <zdesktop>\jetty\webapps\service\Zimlet folder. It wont hurt, but you can manually delete it if need be.

Zimlet Development by manually building ZCS Environment

  • You'll need ZCS 3.0 or later, either Network or Open Source Edition.
  • JDK 5
  • Eclipse or other editors you are familiar with.
  • Apache Ant for building example Zimlets bundled with ZCS source code. You can use the existing build.xml and just add your own zimlet for easy building and deployment.
  • zip / unzip utility. Most Linux distributions come with /usr/bin/zip and /usr/bin/unzip. Windows XP has a built-in support for zip, but you can also use open source zip utilities like 7-Zip.

Verified Against: ZCS 5.0 Date Created: 3/10/2009
Article ID: https://wiki.zimbra.com/index.php?title=ZimletDevSetup Date Modified: 2015-07-13

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