ZimletDevSetup

From Zimbra :: Wiki

Jump to: navigation, search
Developer Article

Article Information

This article applies to the following ZCS versions.
  ZCS 5.0 Article  ZCS 5.0

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.

Contents

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">
   <value>[CURRENT_VALUE]</value>
 </key>


 with..
 <key name="zdesktop_installation_key">
   <value>[CURRENT_VALUE]</value>
 </key>
 <key name="Zimbra_ldap_password">
   <value>[CURRENT_VALUE]</value>
 </key>

.. [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:
http://localhost:7633/Zimbra/desktop/login.jsp?at=4343c072e-8f566-4af9-8acb-1656046bd230f#1

PS: Remove the last #1(or you might see #2 or #3) at the very end during bookmarking to make it..
http://localhost:7633/Zimbra/desktop/login.jsp?at=4343c072e-8f566-4af9-8acb-1656046bd230f



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

http://localhost:7633/Zimbra/desktop/login.jsp?at=4343c072e-8f566-4af9-8acb-1656046bd230f&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


Notes:

  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


PS:

  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">
    <global>
        <property name="allowedDomains">*</property>
    </global>
</zimletConfig>


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">
    <global>
        <property name="allowedDomains">rss.news.yahoo.com</property>
    </global>
</zimletConfig>




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
 doSomethingWith(i);

}

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
Example:
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


Notes:

  • 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>
Example: 
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.



Notes:

  • 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
Example: 
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


Notes:

  • 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>
Example:
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

Notes:

  • 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: http://wiki.zimbra.com/index.php?title=ZimletDevSetup Date Modified: 06/7/2012
Personal tools