vSphere Web Client SDK Setup

Table of content:

1. Development Environment
• Java JDK
• Ant
• IDEs (Eclipse, STS and others)
• Flash Builder and Flex SDK
• SDK Tools Eclipse Plug-in
2. Virgo Server Setup
3. vCenter Server Registration
4. Web Browser setup
5. Start and Run
6. Software Requirements Summary
7. Mac OS Setup notes and tips

Introduction

The SDK package can be installed on Windows or Mac OS. It contains the libraries, docs and samples necessary for getting started and building your own UI and Service plug-ins, and also the server component (Virgo) and Web Client bundles used to run and test your plug-ins locally. See the README for an overall description of the SDK files.

Always use a top directory without spaces for the root directory of the SDK package, for instance C:\VMware\vsphere-client-sdk, because long paths or paths containing spaces may cause server deployment errors and script errors.

You must have access to vCenter Server 6.0 for Windows or the VCSA appliance in order to complete this setup.

Most of the instructions below are common to Flex and HTML plug-ins development.

1. Development Environment

Java JDK

• Check which version of java you already have with the command:
  java -version
• Install JDK 1.7.0_17 (64 bit) or newer to your local disk from Java SE Downloads.
  The 64 bit version is recommended if you need to allocate more memory
• Check the JAVA_HOME environment variable to the correct jdk location, for example C:\Program Files\Java\jdk1.7.0_17
  (JAVA HOME is not required on Mac OS).
• Set the Java compiler option -target 1.6 in your build script and in Eclipse's Java compiler preferences
  (in this release the platform libraries are still compiled in in Java 1.6 mode because of internal dependencies).
  Note that this is not the same as setting the Compiler compliance level to 1.6, because this would force you to have installed JRE 1.6 as well.

Ant

Ant is used by default to build the SDK samples but you are not required to use Ant in your own environment:

• To run the Ant build scripts from Eclipse you can rely on the Ant version packaged with Eclipse.
• To use Ant from the command line:
  • Download Apache Ant (version 1.7.1 or above)
  • Set the environment variable ANT_HOME to that location on your disk.
• In all cases you must define the VSPHERE_SDK_HOME environment variable pointing to the SDK directory.

See the Mac OS Setup notes at the end for tips on setting environment variables.

IDEs (Eclipse, STS and others)

Which IDE to choose?

1. Eclipse JEE is the recommended IDE because of its Virgo integration and the SDK Tools Eclipse Plug-in.
2. Spring Tool Suite (STS) can be used the same way as Eclipse since it is a superset, offering additional developer tools that you may be interested in.
3. IntelliJ IDEA is a good IDE. The "ultimate" version includes a Flex debugger.
4. Any editor will work :-)

If you are developing Flex plugins do not use the version of Eclipse that comes with FlashBuilder. Install Eclipse first, then install FlashBuilder as a plugin to Eclipse .

Eclipse and STS setup

• Download Eclipse IDE for Java EE Developers from eclipse.org, or the Spring Tool Suite, and install it anywhere on your disk.
  Note: only Eclipse 4.2 (Juno) and 4.3 (Kepler) are compatible with the Virgo tooling
  Do NOT use the smaller package Eclipse IDE for Java Developers, the JEE version is required.
   
• Edit the Eclipse.ini or STS.ini file.
  (on Mac OS the .ini file is hidden, right-click on the application icon and select Show Package Contents, the file is in Contents/MacOS):

Add these 2 lines to tell Eclipse to use your installed JDK. Remove any space before each line! (on Mac OS, this is not necessary if you used the Java Preferences app to set the correct JDK as default)

-vm
C:/<your JAVA_HOME directory>/bin/java.exe

Add or change these VM arguments to increase memory (more is even better if you can afford it):

-Xmx1024m
-XX:MaxPermSize=512m

• Start Eclipse and go to Window > Preferences
  • In General you can check "Show heap status" to display a memory indicator.
  • In General/Network Connections you can setup proxy settings for your location.
  • In General/Workspace we recommend to keep "Build automatically" on, and also turn on "Refresh using native hooks" in case you edit sources outside Eclipse from time to time.
  • In Java/Code Style/Formatter you should define your code formatting conventions.
  • In Java/Installed JREs add the JDK you had installed earlier and make sure it is the default.

In order to build SDK examples you need to set two VSPHERE_CLIENT_SDK variables. (We recommend that you use VSPHERE_CLIENT_SDK as well in your new Flex and Java projects in order to avoid hard-coding the location of the SDK and make your projects portable):

• Go to Window > Preferences > General > Workspace > Linked Resources as shown below, and add a new path variable VSPHERE_CLIENT_SDK pointing to the location of your vsphere_client_sdk directory.

• Go to Window > Preferences > Java > Build path > Classpath variables as shown below, and add a path variable VSPHERE_CLIENT_SDK pointing to the location of your vsphere_client_sdk directory.

Flash Builder and Flex SDK

Adobe Flash Builder is not required for building HTML plugins or even for compiling Flex code, the Flex compiler is included in the Flex SDK. However if you are building Flex UI plugins it is recommended to install Flash Builder in order to take advantage of the debugger and have a better development experience within Eclipse. The other solution is to use IntelliJ IDEA "ultimate" version which includes a Flex debugger.

If you don't install Flash Builder you still need to install the free Flex SDK separately, even for HTML plugins.

Flash Builder

• Download Adobe Flash Builder 4.7 and install it as an Eclipse plug-in, it will be exactly the same Flash Builder features within the IDE.
  • You can start with the free 60-days trial version.
  • Run the Adobe Flash Builder 4.7 Plug-in Utility under /utilities and select your Eclipse 4.2 (Juno) or STS folder.
  • When this is done you should see a file [Eclipse]/dropins/fb-4_7-plugin.link containing the path to your FB 4.7 folder.
  • If you have Eclipse 4.3 (Kepler) the utility won't let you select that Eclipse folder. The work-around is to download 4.2 (Juno) in a separate directory, run the Flash Builder utility using that Eclipse folder and then copy the file dropins/fb-4_7-plugin.link to your Eclipse 4.3 folder!
• Start Eclipse and check that Flash Builder is installed, it will appear in the Help menu.
• Go to Window > Preferences > Flash Builder > Installed Flex SDKs and check that Flex SDK 4.6 is the default SDK.
• Define a FLEX_HOME environment variable pointing to the SDK directory, for instance C:\Program Files (x86)\Adobe\Adobe Flash Builder 4.7\sdks\4.6.0.
  FLEX_HOME will be used by the Ant build scripts.

Flex SDK

Install the Flex SDK either for building HTML plugins (required to compile resources), or for building Flex plugins without Flash Builder.

• Download Adobe Flex SDK 4.6.0, either the free Adobe Flex SDK or the Open Source version works.
• Define a FLEX_HOME environment variable pointing to the Flex SDK directory (used by Ant scripts).

Check if the file $FLEX_HOME/frameworks/libs/player/11.5/playerglobal.swc is not present otherwise you need to download it separately:

• Download http://fpdownload.macromedia.com/get/flashplayer/installers/archive/playerglobal/playerglobal11_5.swc
• Rename it playerglobal.swc and move it to $FLEX_HOME/frameworks/libs/player/11.5/

SDK Tools Eclipse Plug-in

The vSphere Web Client SDK includes an Eclipse plug-in with various tools to help your Web Client development, including a wizard to create Flex and Java plug-in projects easily.

Before trying to installing new software make sure that Eclipse's Network Connections settings are correct, otherwise the UI won't be responsive.
If your work location requires a proxy go to Window > Preferences > General > Network Connections to set it up.

• Go to Help > Install New Software...
• Click Add... to select a new site location
  • Click Local... and browse to your vsphere-client-sdk/tools/Eclipse plugin site directory
  • You can name this local site "vSphere Client SDK plugin site" (you will be able to re-use it later if you install the versions of the Eclipse plugin at the same place)

• Select the vSphere Web Client SDK Tools that appears in the list and click Next

• Continue the wizard.
• Click Finish, this starts the Eclipse plugin installation.
• A popup comes up to warn you that this plugin doesn't have a certificate.
• Finally you are asked to restart Eclipse or STS before you can use the new plugin.

After you restart Eclipse you can verify that the plugin is correctly installed:

• Open Help > About Eclipse
• Click on Installation Details
• See "vSphere Web Client SDK Tools" in the list of Installed Software
• Note that you can also uninstall the plugin from this view
  
  
• Finally, if you select File > New > Other... you should see a vSphere Web Client folder containing the wizard to create new projects:

For more information on how to use this wizard please see the SDK-Tutorial doc.

2. Virgo Server setup

In order to use the Virgo server in the Eclipse IDE during development you must install the Eclipse Virgo Tools:

• Open Help > Install New Software... and click Add...
• Add the repository http://dist.springsource.com/release/TOOLS/virgo-ide as shown below.
  (if the URL is not responding check your Eclipse proxy settings Window > Preferences > General > Network Connections)
• Select Eclipse Virgo Tools and nothing else
• Follow the installation wizard (you will need to restart Eclipse at the end).

There is a known issue installing Virgo tools with Eclipse 4.4 (Luna) or STS 3.6. A work-around is provided in this Eclipse bug: https://bugs.eclipse.org/bugs/show_bug.cgi?id=438506.

Once you have restarted Eclipse:

• Select the Servers view under Window > Show Views
• Look for the Servers tab in the bottom panel and right click to create a new server.

• In the new server wizard, select the type Eclipse RT > Virgo Runtime and click Next.

• Click Finish.
• Double click on the server instance in the Server view, this opens an Overview page.
  • Check options Start server with -clean option and Tail application trace files .. at the bottom right.
  • Remove *.xml from the list under Redeploy Behavior (so that changes in plugin.xml files trigger hot deployment of the bundle).

Finally you should increase the memory used by the Virgo Server process:

• Click on Open Launch Configuration in the server Overview page
• Click on the Arguments tab
• Insert the following VM arguments:

-XX:+CMSClassUnloadingEnabled
-XX:MaxPermSize=256m

For more information see the Virgo Guides available through Help > Help Contents.

3. vCenter Server Registration

Web Client 6.0 is compatible with vCenter servers version 5.5 and 6.0 but you need at least one vCenter server 6.0 for the initial registration.

The vCenter installation requires an SSO server (Single Sign-On) for authentication: vCenter registers with the SSO server and with Component Manager (CM). The Web Client finds the registered vCenter(s) at login time when it connects to CM. In order to configure your development environment to use the proper CM and SSO you need to generate two registration files with the scripts dev-setup.sh or dev-setup.bat in /tools/Dev setup scripts (vCenter registration)/.

Registration with vCenter 6.0

Note: to copy files between your development machine and VCSA or vCenter Server for Windows you can use WinSCP on Windows and Cyberduck on Mac OS (or the ssh command line).

1. For VCSA: copy dev-setup.sh to your VCSA root directory and make it executable.
   For vCenter for Windows: copy dev-setup.bat to vCenter for Windows administrator directory.
2. Run the dev-setup script. Three files get generated: webclient.properties, store.jks and ds.properties.
3. Copy these files to your dev machine at the following locations:
   1. webclient.properties
      Windows: C:/ProgramData/VMware/vCenterServer/cfg/vsphere-client/
      Mac OS: /var/lib/vmware/vsphere-client/
   2. store.jks
      Windows: C:/ProgramData/VMware/vCenterServer/cfg/
      Mac OS: /var/lib/vmware/vsphere-client/
   3. ds.properties
      Windows: C:/ProgramData/VMware/vCenterServer/cfg/vsphere-client/config/
      Mac OS: /var/lib/vmware/vsphere-client/config/
4. Define the VMWARE_CFG_DIR environment variable pointing to the following location:
   Windows: C:/ProgramData/VMware/vCenterServer/cfg/
   Mac OS: /var/lib/vmware/vsphere-client/
5. (Mac OS only) Change keystore.jks.path in webclient.properties to use the correct path for Mac OS, i.e. /var/lib/vmware/vsphere-client/store.jks
6. (Mac OS first time only) Edit vsphere-client-sdk/server/configuration/tomcat-server.xml:
   replace

   keystoreFile="C:/ProgramData/VMware/vCenterServer/cfg/store.jks"

   with

   keystoreFile="/var/lib/vmware/vsphere-client/store.jks"

7. Start/restart the Virgo server on your machine. The log should show a successful connection to the CM url defined in webclient.properties.

Tip: if you are developing on Mac OS and want to avoid updating keystore.jks.path each time you generate the files you can modify the script dev-setup.sh or dev-setup.bat to echo the correct path.

Registration with another vCenter 6.0

Repeat the steps above for another VCSA or vCenter Server for Windows setup. It is recommended to make a copy of the vSphere Web Client directory (Windows) or vsphere-client (Mac OS) beforehand and empty the current one, since other files get generated at runtime in this local cache. This way you can easily switch between different vCenter setups, by renaming the directory and restarting the Virgo server.

Configuration parameters in webclient.properties

webclient.properties contains various configuration flags. The copy that gets generated by the dev-setup scripts for your local Windows or Mac OS development machine contains only a subset of the parameters that can be used. See the full version in your VCSA or vCenter for Windows setups at /etc/vmware/vsphere-client/webclient.properties or C:\ProgramData\VMware\vCenterServer\cfg\vsphere-client\webclient.properties.

4. Web Browser Setup

The last step is to setup your browser for Flex development. Flex is supported by all major browsers: Internet Explorer, Firefox, Google Chrome, and also Safari on Mac.

• Pick the browser you want to develop and test with and set it as your default external browser in Eclipse.
  • In Window > Preferences > General > Web Browser select the external web browser of your choice. i.e. the browser used when starting a Flex session from Eclipse.
  • You can keep Default system web browser selected or select a browser that won't change if you modify your default browser outside Eclipse.
  • Note that you can always run vSphere Web Client in any other browser outside Eclipse if you are not interested in debugging client code.
  
  
  
  
• Then install the latest Flash Player (version 11.5 or above) for the browser of your choice.
• Install also the Flash Player Debugger from the same Adobe site for your target browser, otherwise you won't be able to launch client debugging sessions.

5. Start and Run

Now that you have configured your environment let's run a simple example to make sure everything is working.

Add the Helloworld plug-in

Import the example helloworld-ui in Eclipse and add if to your server:

• Select File > Import > General > Existing projects into Workspace
• Browse to vsphere-client-sdk/flex-samples/helloworld/helloworld-ui
• Select the existing project helloworld-ui and click Finish.

The project is built automatically if you kept the option Project > Build Automatically selected. See the build output in war/target/helloworld-ui-war.

The next step is to deploy this plugin to the Virgo Server within Eclipse.
(In case vSphere Web Client server is already running outside Eclipse on this machine stop the server now in the Windows Services panel. The same instance will be started from Eclipse.)

• Open the Servers tab view at the bottom.
• Right click on the Virgo Server instance and select Add and Remove.

• Select the helloworld-ui resource on the left and click Add to move it to the right list.

The plugin bundle is now visible under the Virgo server

Next you must create a Run/Debug Configuration to launch the vSphere Client:

• Open Run > Run Configurations...
• Select the Web Application category on the left and press the New button
  (Note that you will see this category only if you have installed Flash Builder with Eclipse)
• Name it vSphere Client for instance as you will use the same configuration regardless of the plug-ins you have deployed.
• Under Project select the project Helloworld-ui.
  (Note that it doesn't matter which Flex project is selected, the run configuration will be available as long as the project stays open)
• Under URL or path to launch, uncheck Use default and set the URL to be https://localhost:9443/vsphere-client
  9443 is the default port used when installing VWC, but it may be different in your case.

Start vSphere Client

• Start the server by clicking on the run (or debug) buttons in the panel toolbar or in the right-click menu.

The server takes a couple of minutes to start, the Console tab shows all the bundles being loaded and should be clean of errors.

The bundles loaded by the server are both the runtime bundles installed in server/repository and the plug-ins' Flex and Java bundles from vsphere-client-sdk/vsphere-client/plugin-packages.

In case your server never reaches the state Started, Synchronized, or you see other errors, please check the trouble-shooting steps in the FAQs.

Launch the vSphere Client

Use the Debug or Run menu to start the vSphere-client configuration you created above.

Or you can also right-click on the project and select Debug As/ Run As > Web App

It will appear as a short-cut in the Run or Debug menu only after your have used it once.

Notes:

• The Debug session requires that you have installed the Flash Debugger in your browser as described above.
• If you don't want to debug you can also open the vSphere Client by going directly to https://localhost:9443/vpshere-client in your preferred browser.

Your target browser is launched and lands in the login page.

• Login with your vCenter credentials
• This opens the Flex Client showing vCenter Servers that were registered.
• Go to the Home view and see the Helloworld button. This opens a view with the "Hello world" text in it.

Try other plug-ins

Once the Virgo server is running you can add and remove plug-ins without having to restart it.

• Look at the other samples provided in the SDK.
• Try creating your own Flex or Java project with the SDK Tools Eclipse plug-in.
• If you run into trouble see the FAQs for answers to common questions.

6. Software Requirements Summary

7. Mac OS notes and tips

Here are some important things to remember when setting up your development environment on Mac OS:

• The Finder hides many files by default, it is easiest to make them all visible using this command in your terminal window: defaults write com.apple.Finder AppleShowAllFiles YES
• The Eclipse.ini or STS.ini file used to configure startup options is hidden, right-click on the application icon and select Show Package Contents, the file is in Contents/MacOS.
• When starting Virgo under your user account (on the command line or from Eclipse) your plugin code may not have read/write permissions in local directories being used. The solution is to set the proper permission for your account. For instance, when saving setting values in the globalview sample, you will get an error if you haven't set write permission to /var/lib because the data is saved in /var/lib/globalview.
• Environment variables are a little tricky on the Mac...
  When using scripts on the command line (Terminal window) the easiest is to set them in your ~/.bash_profile. See this article for other solutions.
  However this won't work if you run the Ant build scripts from Eclipse unless you start Eclipse from the command line which is not always practical.
  1. One solution is to edit the JRE in Eclipse's Java Preferences, adding 2 VM arguments defining VSPHERE_SDK_HOME and FLEX_HOME as shown below (Note: this may not work if you use multiple workspaces):

     

  2. Another solution which seems more stable is to edit the Ant Runtime Preferences, adding 2 properties for VSPHERE_SDK_HOME and FLEX_HOME as shown below:

     

  3. Make sure NOT to use quotes around your paths, even if they contain spaces like Abobe Flash Builder above!

See also: FAQs - SDK Tutorial - SDK samples - Flex API docs - Java API docs