Installation manual for XGAP 1.4 development

This is a very detailed installation manual written for Ubuntu 10.04, AMD64 Desktop edition. The installation for other operating systems is quite similar and often much easier. Notes about the key differences should be added at some point.

Please note that most or all of these commands should be executed as root user, or with sudo.

Install Eclipse

• Basic install by typing apt-get install eclipse, this also installs Java 6 JDK (openjdk)

Install MySQL

• Install using apt-get install mysql-server, set root user password when prompted
• Start MySQL using: mysql -u root -p, enter your password
• Create database with create database xgap_1_4_distro;
• Grant privileges to user molgenis: grant all privileges on xgap_1_4_distro.* to molgenis@localhost identified by 'molgenis'; flush privileges;

Install Tomcat 6

• NOTE: XGAP includes a standalone webserver now, based on TJWS.
• Download Tomcat 6: wget http://apache.xl-mirror.nl//tomcat/tomcat-6/v6.0.29/bin/apache-tomcat-6.0.29.tar.gz
• Untar: tar xvzf apache-tomcat-6.0.29.tar.gz
• Move: mv apache-tomcat-6.0.29 /usr/local/tomcat
• Edit the bash for the appropriate user: nano ~/.bashrc
• In the Nano editor, add “export JAVA_HOME=/usr/lib/jvm/java-6-openjdk”, save and quit
• Grant rights to Tomcat: sudo chmod 777 /usr/local/tomcat * -R

Install Subclipse

• Start Eclipse (either Applications -> Programming -> Eclipse or “eclipse” from terminal), select a workspace location, dismiss welcome screen.
• Select “Help -> Install New Software”
• Click “Add”, use Name ‘svn’ and location ​http://subclipse.tigris.org/update_1.6.x
• Tick ‘Subclipse’, hit Next, Next, Accept, Finish, wait, ignore warning, restart Eclipse
• Select “Window -> Open Perspective -> Other”, “SVN Repository Exploring”, click OK twice (ignore a warning about JavaHL and GNOME keyring)

Install Java2EE developer tools

• “Help -> Install New Software”, in the “Work with” list, drop down and select “Galileo Update Site”
• Tick “Web, XML, and Java EE Development” to select all components. Hit Next, Next, Accept, Finish, restart Eclipse after download

Install XGAP and Molgenis

• Right-click in Repositories window, do “New -> Repository Location”, enter ​http://www.molgenis.org/svn
• Add another repository: ​http://www.xgap.org/svn
• From molgenis.org, perform a default “Checkout -> Finish” on the folder “3.3” inside the folder “molgenis”
• From xgap.org, perform a default “Checkout -> Finish” on the folder “xgap_1_4_distro”
• Go to Java perpective: “Window -> Open Perspective -> Other”, “Java”
• Optional, but recommended: View packages as hierarchy, use the triangluar “View menu” button, “Package Presentation -> Hierarchical”
• Expand “handwritten/java”, “(default package)”, rightclick “XgapGenerate.java”, “Run As -> Java Application”, ignore the warning.
• Rightclick “xgap_1_4_distro” project, hit “Refresh”
• Now you can use "XgapUpdateDatabase", “Run As -> Java Application” to load the XGAP datamodel into your database.

Running on Tomcat

• Rightclick “xgap_1_4_distro” project, “Run As -> Run On Server”, select “Apache -> Tomcat v6.0”, hit Next. Browse for the install directory, /usr/local/tomcat and click Finish.

About the storage directory

The storage directory is used to store DataMatrix data in some cases. In the GUI, you can choose how to save your data. At the moment, the choices are:

• Database - this saves your datamatrix in the regular MySQL database, the storage directory is not used.
• Binary - this saves your datamatrix in a special binary format that is optimized for big data. You can find it inside the storage directory.
• Plain - this saves your datamatrix in a plain CSV file, suitable for small datasets and editing by hand. You can find it inside the storage directory.

Configuring the storage directory

• The webapplication should be running at ​http://localhost:8080/xgap_1_4_distro.
• Go there and select "System", subtab "Settings".
• Fill in your storage directory (for UNIX systems, eg 'data/xgap', for Windows systems eg. C:\data\xgap'), and click "Set path".
• This should yield a green "System table exists" message and a path display. If not, your database is not set up correctly. Make sure MySQL is installed and has PATH access, the xgap_1_4_distro database exists and has privileges for user 'molgenis'.
• Now you can test the validity of this path. Use the two "Test dir" buttons to perform make/exists and read/write tests.
• If both tests succeed, your directory is validated and usable in XGAP. This will display a green "VERIFIED" message at the bottom.
• Under UNIX, these tests will probably fail. You will have to create this directory manually with mkdir. If the application is running as a deployed WAR file, the smartest move is to grant the user 'tomcat' ownership by typing eg. chown tomcat6 /data/xgap. If you're running from Eclipse, try chmod 777 /data/xgap or so.

Loading example dataset and cluster metadata

• Run "QuickStart.java" (in handwritten/quickstart), this should fill up your database and storage locations with all needed data if everything has been set up correctly. It will not overwrite existing data, and load the datamodel if necessary. (though from plugins/emptydb/create_tables.sql for deployment reasons)
• Please note that error can be displayed while the program is running, this is fine, just let it run until it's done and then view the report.
• The same program can be called 'online' with the servlet loadexampledata, there's a hyperlink in the 'About' section. This is very handy to quickly test deployed versions of your application.

Other

• In order for the Rplot plugin to work, your server must have R installed. Use apt-get install r-base-core to do this.