Installing a Jazz Express-C (free for 10 users) server and RTC client for eclipse 3.5 in Windows

I was up far too late getting this to work because there was little to no information on the web in a step by step fashion. What information I did find was scattered and sometimes flat wrong (interestingly, even some info on jazz.net itself was incorrect). Most of this will be from memory, so there might be a few inaccuracies in filenames and such, but the general concept should be solid. Note that your jazz root directory may be different than mine, depending on where you decide to unzip it. I chose C:\IBM\jazz. Adjust the paths below accordingly.

Prerequisite Downloads

• Go to jazz.net and create a free account.
• I suggest using a download manager to download these files as they’re huge and failures occur OFTEN on this site, they even have a FAQ about it. I’m a Chrome guy, but this FireFox download manager suggested by Jazz worked well: DownloadThemAll.
• Once your jazz.net id is activated, visit this link and click on the latest release. Then click on “Other Download Options” under the Express-C column. From there download two of the zips:
  • Server
  • Client for Eclipse 3.5.x (Extension Install)

Server Installation

• For the most part, follow the instructions here to install jazz server, leaving everything at it’s default value. If this is a new installation, skip to this section. My installation was a new one, so I don’t know if these instructions hold up in an upgrade scenario.
• Once that is complete, you will start the server with the command server.startup.bat. This was one of the frustrating steps for me. When I ran the batch file a separate window opened, as it’s supposed to, then immediately closed. There were no logs in the jazz logs directory, no events in the Windows event viewer, and no error output in my command prompt. I finally resorted to adding debug echo statements to the various startup batch files to try to find where the failure was occurring and honestly, it just magically started working at one point. The last debug echo statement I added was to C:\IBM\jazz\server\tomcat\bin\catalina.bat. I added an echo just before the “goto end” that was just before the “:doSecurity” branch target. For reference, I’m on Windows 7 Home Premium. Maybe you won’t have this issue. If someone else has this issue and finds, definitively, what fixes it, please let me know and I’ll update this blog post.
• At this point, the server should be running. If it’s successfully running, a separate java window will be open where the server is running. Don’t close the java window or your server will die. It takes a good 30 seconds before the server is fully started and ready to accept connections. Once it’s ready, you can connect to it by going to https://localhost:9443/jazz/admin. You can do the various set up steps outlined here.NOTE: I had a very difficult time getting email notifications to work over SMTP.  I finally found some information on google help (I use google apps for my email service) that noted that if port 465 doesn’t work, try port 587.  That did the trick for me.  I guess my ISP blocks 465 or something.  So my settings were:
  Server: smtp.gmail.com
Server port: 587
Username: user@domain.com
Password: xxxxxxxx
Use STARTTLS: true
• Now we have a running jazz server. Since I’m using this from remote locations, I had a few stipulations:
  • I need to be able to access this from outside my router’s firewall. So I set up port forwarding on my router to forward 9443 TCP to my server. I use that in conjunction with a free dyndns.org domain name.
  • Two programs need to be added to the Windows Firewall exception list:
    • C:\IBM\jazz\server\tomcat\bin\tomcat5.exe
    • C:\IBM\jazz\server\jre\bin\javaw.exe
  • I need this to start at boot by making it a Windows Service so I don’t have to be logged in for the jazz server to start. Another frustrating step! There is a lot of misleading information on the internet about this, most notably on the jazz site itself! The instructions make a lot of assumptions that you know where certain files are located, etc. For the most part, follow the instructions here with the following changes and clarifications:
    • Step 2: you ARE using Derby, so follow this step. teamserver.properties is located at C:\IBM\jazz\server\conf\jazz.
    • Step 3: the Work Item text index is located at C:\IBM\jazz\server\workitemindex
    • Step 5: at present, this talks about RTC 1.0 and RTC 2.0. I’ve installed 2.0.0.2Fix4, so I followed instructions for RTC 2.0.
    • Step 5: another source of frustration… this says to set the “Maximum memory pool” size to 1536… but that doesn’t work! Much googling revealed this value has to be a power of 2. So you could do 1024 or 2048. I didn’t feel like abusing my system’s memory, so I put 1024. I suppose if I had 64 bit Windows with 8GB of memory, I’d bump this. But I haven’t noticed the performace to be suffering from setting it to 1024.I also added the following to the java options in the java tab:
      -Djava.awt.headless=true
-Dorg.eclipse.emf.ecore.plugin.EcorePlugin.doNotLoadResourcesPlugin=true
-Dcom.ibm.team.repository.tempDir=%TEMP%
-XX:PermSize=128m
-XX:MaxPermSize=256m
    • Once all this configuration is complete, start up the server via the “Start” button in tomcat5w. If it successfully starts (again, it takes a good 30 seconds or more for it to respond to https requests after starting), I’d recommend rebooting your computer to ensure it’s starting at boot time as a Windows service.
• If you made it this far with all issues resolved, you have a running jazz server that starts as a service. Congratulations!

Installing RTC client

• Thankfully, this part was very quick and easy, other than waiting for the enormous zip to download and unzip. Follow the instructions here and it’s installed!
• Start up eclipse. The first start will take a little longer than usual as it’s loading the new plugin extensions you just copied over.
• At the top where you have your perspectives, click on the + to add a perspective. Choose “Other” then select “Work Items” and click OK.
• Switch over to the Work Items perspective.
• On the right, click “Connect to a jazz repository” (I can’t remember the exact terminology)
• Enter the following for the credentials:
  URI: https://localhost:9443/jazz
Name:
User ID:
Password:
• Click Finish
• This blog post isn’t about using RTC, so I’m just going to quit here.

Summary

I hope this helps people save the time and frustration I had to go through. However, in the end it is very worth it. I was previously using SVN as a source control repository but that’s just very clunky and doesn’t work well when collaborating on projects with others. It was decent when I was using it for solo projects, but fell apart when collaborating. I’ve used RTC for a year now at work so I knew the benefits of it and am very excited to be using it on my personal projects now.