UTGB uses the embedded Tomcat web server, so you don't have to read this page for simply browsing UTGB launched by utgb server command. This page is written for system administrators, who have to publish UTGB servers on the Web by using Apache or Tomcat web servers.

You can start UTGB at any machines. The utgb server command launches a stand-alone proxy server (AJP) using port 8990, and a Tomcat engine listening port 8989 at the same time. To start utgb as a background process, prepare the following script under your UTGB project:

start-utgb.sh

#!/bin/zsh

h=`hostname -s`
UTGB=(full path to utgb command. e.g., /home/leo/local/bin/utgb )
JVM_OPT=-Xmx8g
export JAVA_HOME=(Your java installation folder)
JVM_OPT="${JVM_OPT}" nohup ${UTGB} server > log-$h.out 2>&1 < /dev/null &

Then chmod +x start-utgb.sh.

Now you can start the server by running the script:

$ ./start-utgb.sh

To shutdown the utgb instance, find the utgb process ID, then simply kill the process:

$ jps -v
20599 Launcher -Xmx8g -Dclassworlds.conf=/home/leo/local/utgb/current/bin/utgb.conf -Dutgb.home=...
22907 Jps -Dapplication.home=/bio/package/java/jdk1.7.0_02 -Xms8m

$ kill -9 20599

(TODO: Add a command to shutdown the utgb server)

If you need to browse UTGB started behind firewall (but accessible through ssh), use dynamic proxy. Suppose that you have a server machine hx that runs utgb server, and a gate way machine gate. Common firewall settings prohibit accesses to port 8989 of the utgb server running at hx. To access hx, you need to bypass gate server:

hx <- gate <- (your machine)

To browse UTGB running in hx from your machine, use the dynamic proxy support of ssh:

$ ssh -D localhost:1080 gate

This command creates a network tunnel to hx through gate. You can access arbitrary ports of hx through the port 1080 of your machine.

Next, in your web browser, open network settings and set SOCK Host to use port 1080 at localhost:

SOCK Host = localhost   port = 1080

If you are using Google Chrome, Proxy Switchy! extension would be useful to switch the configurations quickly.

When the address of hx is 192.168.1.100, you can browse the UTGB (e.g., myapp project) at http://192.168.1.100:8989/myapp. This configuration is useful when you want to share the UTGB data only within laboratory members.

When you need to create public web services backed by UTGB, a recommended way is to use Apache web server to access UTGB contents. Add the follwoing settings in your Apache's configuration file (e.g., /etc/httpd/conf/httpd.conf, or /etc/httpd/conf.d/proxy_ajp.conf):

LoadModule proxy_module modules/mod_proxy.so
LoadModule proxy_ajp_module modules/mod_proxy_ajp.so 
# necessary for load balancing (see below)
LoadModule proxy_balancer_module  modules/mod_proxy_balancer.so

ProxyPass /myapp ajp://localhost:8990/myapp
ProxyPassReverseCookiePath / /

This configuration redirects web accesses to http://(your hostname)/myapp to the UTGB server (http://localhost:8989/myapp through ajp port 8990), but the web user still sees the address http://(your hostname)/myapp without noticing such redirections.

After editing the configuration file, restart the apache server to reload the configuration:

# /etc/init.d/httpd restart

When the performance of UTGB server matters, replicate the UTGB instances. That is one of the simple ways to distribute the workload of your UTGB server.

First, create replicas of your UTGB project folder (e.g., myapp) on several machines. To do this, you need to copy the entire UTGB folder (myapp) complied by utgb compile command. To synchronize the myapp folder contents, rsync command would be useful:

$ cd /somewhere/myapp
$ for i in $(seq -w 10 14); do rsync -av . hx$i:/somewhere/; done

Then login and cd to each of the copied folders to start utgb server. For example, you can start utgb server in 4 machines (e.g., hx10-hx14) as follows:

$ for i in $(seq -w 10 14); do ssh hx$i "cd /somewhere/myapp; ./start-utgb.sh"; done

If hx10-hx14 have IP addresses 192.168.1.(111-114), add the following configuration to your Apache2 server to redirect the web requests to the UTGB servers. (Modify the configuration below according to your system):

ProxyPass / balancer://utgb/ nofailover=Off

<Proxy balancer://utgb/>
   BalancerMember ajp://192.168.1.111:8990/ loadfactor=10
   BalancerMember ajp://192.168.1.112:8990/ loadfactor=10
   BalancerMember ajp://192.168.1.113:8990/ loadfactor=10
   BalancerMember ajp://192.168.1.114:8990/ loadfactor=10
</Proxy>

Then restart your Apache server. That's all. Done!

You can browse your UTGB thorough the Apache web server as the same as before. But in this configuration, accesses to tracks and databases are distributed to four machines. It is much faster than the single server configuration.

Since no installation of Tomcat is necessary (although you can use locally installed Tomcat servers as explained below), you can quickly improve the performance of the UTGB browser.

Since utgb server can be used in the standalone mode, no need exists to install Tomcat to your system. If you need to deploy UTGB, for some reasons, to system-installed Tomcat servers, here are the tips to do so.

Tomcat (http://tomcat.apache.org/) is a web server engine for running Java-based web applications. Tomcat version 6.x or higher is recommended for using UTGB. To setup a stand-alone Tomcat server, see the installation instruction here: http://www.xerial.org/trac/Xerial/wiki/WebApplication/Tomcat

Web applications generated by UTGB use SQLite JDBC database driver. Because of the native library loading problem of JNI (described in here), you have to manually copy SQLite JDBC library into your Tomcat installation folder.

• First, download sqlite-jdbc-3.6.20.1.jar.
• Put the downloaded jar file into (TOMCAT_HOME)/lib folder. (for Tocmat 6.x or higher)

In order to deploy your UTGB browser, you have to set up the Tomcat manager's user account by editing the (TOMCAT_HOME)/conf/tomcat-users.xml file:

• (TOMCAT_HOME)/conf/tomcat-users.xml

<?xml version='1.0' encoding='utf-8'?>
<tomcat-users>
  <role rolename="manager"/>
  <role rolename="admin"/>
  <user username="tomcat-admin" password="pass" roles="admin,manager"/>
</tomcat-users>

• Then, restart your Tomcat to apply the above configuration change.

Next, you have to create .m2/settings.xml file in your home directory:

• (HOME)/.m2/settings.xml

<settings>
 <servers>
  <server>
    <id>tomcat</id>
    <username>tomcat-admin</username>
    <password>pass</password>
   </server>
 </servers>
</settings>

• In this file, write the same user name and password described in your tomcat-users.xml file.

Now, you are ready to deploy your UTGB browser to your Tomcat server. Type utgb deploy in your project folder. Suppose that your web application name is 'myapp' (which is generated by 'utgb create myapp' command):

$ cd myapp
$ utgb deploy

Then, access the http://localhost:8080/myapp

Load balancing using multiple servers can be done using the same configuration as explained before, except the port number of AJP. Instead of 8989 used in UTGB, you need to specify 8009, which is the default port number of AJP launched in Tomcat engine:

ProxyPass / balancer://utgb/ nofailover=Off

<Proxy balancer://utgb/>
   BalancerMember ajp://192.168.1.111:8009/ loadfactor=10
   BalancerMember ajp://192.168.1.112:8009/ loadfactor=10
   BalancerMember ajp://192.168.1.113:8009/ loadfactor=10
   BalancerMember ajp://192.168.1.114:8009/ loadfactor=10
</Proxy>

You need to deploy your UTGB project to each Tomcat server.