Environment setup

Setting up the Cyclos 3 development environment

Installation requirements

• Java Runtime Environment (JRE), Java 6 or 7 is required;
• Web server: Apache Tomcat 6 (tomcat 7 isn't configured for development in Cyclos);
• Database server: MySQL 5.1 or higher;
• Eclipse Indigo IDE for Java EE Developers;
• Jinto 0.13.5 plugin for Eclipse.

Installation steps

Please make sure the following steps are followed:

• Step 1: Install Java
• Step 2: Install MySQL
• Step 3: Install Tomcat
• Step 4: Configure MySQL

Step I: Install Eclipse

(You can skip this step if you have already installed Eclipse Indigo IDE for Java EE Developers)

• Download Eclipse Indigo IDE for Java EE Developers at http://eclipse.org/downloads/ choose the JEE version.
• Extract eclipse to a directory of your choice, you can start eclipse by opening eclipse.exe
• Select a directory eclipse can use as a workspace for cyclos <eclipse_cyclos_workspace>
• Check in eclipse if the correct JRE is installed (Window – preferences – Java – Installed JREs).

Step II: Install JInto

(You can skip this step if you have already installed JInto 0.13.5)

• Start eclipse by opening eclipse.exe
• Go to Help > Install New Software > Add.
• In name enter "Jinto" and in location "http://www.guh-software.de/eclipse".
• Subsequently select JInto 0.13.5 and click on Next > Next > Accept > Finish.
• In: Window > Preferences > Jinto, deselect "Include JInto header in resource files on saving" and in "Problems severity" set Ignore for all options.

Step III: Add tomcat to Eclipse

Note for linux/ubuntu users: for tomcat to work with eclipse, you first need to make sure that eclipse can change the tomcat configuration files, so you have to set the permissions for this. As windows is less tricky with permissions, there is no need to do this in windows. It also helps to make some links in the tomcat directory. Example:

cd /usr/share/tomcat6
sudo ln -s /var/lib/tomcat6/conf conf
sudo ln -s /etc/tomcat6/policy.d/03catalina.policy conf/catalina.policy
sudo ln -s /var/log/tomcat6 log
sudo chmod -R 777 /usr/share/tomcat6/conf

The following items must be done by both windows and linux users:

• Start eclipse by opening eclipse.exe
• Show server window in eclipse: Window > Show View > Other > Servers.
• In server tab (right below) add new server: right click (in white) > New > Server > Apache > Tomcat vX.X Server (select the server you have already installed, Tomcat 6 or 7) and click on "Next".
  • Click on "Browse" and select the tomcat installation directory <tomcat_home>, and click on "Finish".

Step IV: Get Cyclos code

There are two ways to download the cyclos code. A: The cyclos code can be downloaded trough a repository location. B: The cyclos code can be downloaded trough sourceforge.net.

A. code from SVN repository

First, you need to make SVN available in eclipse.
Note: The SVN repository is currently not publicly available. You can download the source code from Source Forge (basic install).

• Go to window > preferences > install/update > available software sites, and check if the site 'http://download.eclipse.org/technology/subversive/0.7/update-site/' is listed. If so, enable it. If not, add it via the add button. You can give it the name 'Polarion Subversive'.
• Save the preferences
• Go to Help > Install New Software, Select work with 'All Available Sites' and select the plugin Subversive SVN Team Provider Plugin > 'Subversive SVN Team Provider' and 'Subversive SVN JDT Ignore Extensions'.
• Install the plugins by clicking next as often as needed. After that, you will need to restart eclipse.
• After restart (or maybe even earlier), eclipse will prompt you to get the connector. Choose the latest version of the SVN kit. If that creates any version conflict the Native JavaHL is a good alternative.

Once SVN is completely installed, do the following steps:

• In eclipse, open the SVN repository view: Window > Show View > Other > SVN > SVN repositories.
• Now you see the tab SVN repositories, click in this window with your right mouse button and select New > Repository Location...
• In Url: https://server.cyclos.org/svn_cyclos3 and add your password and username.
• Check out the projects in trunk. Checkout the projects by right clicking them and selecting Check Out (in the SVN Repositories window). You should check out the following projects:
  • cyclos3
  • cyclos3_impl
  • cyclos3_web
  • cyclos3_build (optionally)
  • cyclos3_standalone (optionally)

B. Code from installation package source forge

• Download the latest version of Cyclos at http://sourceforge.net/projects/cyclos/
• Unzip the cyclos_3.6_x.zip into a temporary directory.
• In this temporary directory go the directory called web.
• Select all files and directories in the directory web and create a zip file called cyclos.war
• In Eclipse go File > Import.
• Select Web > War file > Next.
• Select the cyclos.war file you created and click "finish".
• A new project with the cyclos name will appear, open that project by going to "<eclipse_cyclos_workspace>/cyclos":
  • Go to the directory: "WebContent/WEB-INF/lib" and delete the file cyclos.jar
  • Go to the directory you unzipped the basic installation file and open the directory "src".
  • Copy all files to the directory in your newly created workspace "<eclipse_cyclos_workspace>/cyclos/src".
  • It will ask to replace files, select yes to all.
• In Eclipse select the cyclos project and do a refresh.
• Click with the right button on the Cyclos project (in the project explorer on the left) and select "properties".
  • in: validation, select "enable project specific settings" select "suspend all validators".
  • in: validation > HTML syntax, select "enable project specific settings" and change all options to ignore errors.
  • Click on "Apply" and afterwards "Yes".
  • in: validation > JSP syntax, select "enable project specific settings" and change all options to ignore errors.
  • Click on "Apply" and afterwards "Yes".
  • in: Java Build Path, go to: Libraries > Add Library > Server Runtime > Next, Choose your tomcat installation and click on "Apply".
  • in: Project Facets - select Java, chose version number 5 (= Java 1.5), Click on "Apply" and then on "OK".
• All compilation errors should be gone

Note: for version 3.5.6 and earlier another step is required (for 3.6 or higher this is not needed). On the directory where you extract the downloaded package, go to web/WEB-INF/lib and open cyclos.jar find the file /nl/strohalm/cyclos/spring/web_beans.xml and extract this file to workspace: cyclos/src/nl/strohalm/cyclos/spring

Step V: Configure MySQL in the cyclos.properties file

• Open the cyclos.properties file, you can quick open file with Ctrl + shift + R, then search for "cyclos.properties" and open the file.
• Here you can set the database configuration, please specify the username and password (use the password you specified in step 4) e.g.:

hibernate.connection.username = cyclos
hibernate.connection.password = cyclos1234

Step VI: Configure tomcat in eclipse

• In server tab open the tomcat server by double clicking on it (or select and pres F3).
• In the tab "Overview" (left bottom): set the time outs (start and stop) to the maximum 999.
• In the tab "Modules" (left bottom): click on "Add Web Module...", select "cyclos" and click on "OK". Then select the cyclos project and select "Edit...", in the pop-up deselect "Auto reloading enabled" finally click on "OK".
• Now start the server: right on tomcat (in the server tab) and select "Start" and then "Yes".
  • This will probably cause a heap space error, now stop it (this is needed, because a run time environment has to be created).
• Now you need to augment the heap space. Go to: Run > Run configurations... > chose the tomcat server, in the arguments tab in VM arguments put "-Xms128M -Xmx512M -XX:MaxPermSize=256m".

Step VII: Other configurations

• Import Format cleanup configurations:
  • In: Windows > Preferences > Java > Code style, import cleanUp.xml, codeTemplates.xml and formatter.xml files in the correct subtabs. These files are located in cyclos3/docs/eclipse_defs.If you download the source package from source forge you can get these files in http://cyclos.org/wiki/attached_files/eclipse
  • In: Windows > Preferences > Java > Appearance > Member sort order, check "sort members in same category by visibility" and set the visibilities to: Public, Protected, Private, Default.
• Set encoding as UTF-8 in:
  • In: Windows > Preferences > General > Content Types > Text, set UTF-8 (must be uppercase) to all file types, remembering to click update every time the text box is set to UTF-8.
  • In: Windows > Preferences > General > Workspace, default encoding must be set to UTF-8.

Step VIII: Start Cyclos

• Clean the project.
• Build projects (Eclipse has the ‘build automatically’ option on by default).
• Start tomcat via server tab in eclipse (right below).
• Browse to http://localhost:8080/cyclos/
• If using the default database you can login with admin: admin password 1234.

TIP: If you don't want your explorer in eclipse to be packed with all kind of libraries listed, use the package explorer (windows > show view > other > java > package explorer), and set its filter to hide the libraries.

If do add new library you will have to have to add them in the properties of cyclos_web project. Select J2EE Module dependencies and add the lib (add jar).

Run Cyclos in Netbeans IDE

If you want to run Cyclos in Netbeans you will have to do the following steps:

• Unzip Cyclos_3.x.x.zip to (src-dir).
• Launch NetBeans
• Ensure you have the "Java Web Applications" plugin installed withing NetBeans, restart as needed.
• Setup your tomcat6 test server according to where you have tomcat6 installed, and test start/stop the server.
• File > New Project...
• Java Web, then Web Application with Existing Sources, click Next.
• At Location, browse to (src-dir).
• Enable "Use Dedicated Folder for Library Directory", browse to web/WEB-INF/lib, and click Next.
• Select the test deployment server you setup earlier, click Next.
• Click Finish.
• right click on the project in left hand side window - Project->Properties->Libraries. and uncheck ption to build required projects / lib
• Configure cyclos.properties files for database username and password.
• before deploying your application, you need to check you web.xml file in WEB-INF, as NetBeans likes to change this which then causes error. If the file has been changed, just replace it with the original, as included in the zip file.
• To test, right-click > Deploy. (build/clean recommended first time)

TIP: When ever you want to deploy the app again, you need to delete the according "web-app-name".xml file in apache/conf/catalina/localhost (or modify apache to run multiple instances).

General tips

During the development it is better to disable the second level cache. You can do this by setting in the cyclos.properties file:

### Second level cache settings
hibernate.cache.use_query_cache=false
hibernate.cache.use_second_level_cache=false

Ten useful eclipse short cuts can be found at this site

Debugging tips

• When a page leads you to an 'illegal form submission' error, create an exception breakpoint of type ValidationException.
• To debug JavaScript, use the firefox's firebug extension.