Tomcat_Apache_UIGU

Timothy Lethbridge edited this page Jun 14, 2016 · 3 revisions
Clone this wiki locally

Introduction

This version of UIGU is likely to be deleted, so this page is nearly obsolete.

(page under construction) This document explains the integration of Tomcat and Apache as required for running the JSF (Java Server Faces) version of UIGU (UI Generation from Umple) (JSF) in UmpleOnline. This document is for Umple developers who have set up a local version of UmpleOnline and want to take the extra step of setting up UIGU.

Background

Apache is a web server that is suitable to run web applications such as UmpleOnline. But to run Java Web Applications that involve server-side Java (such as UIGU) one needs an application server like Tomcat or JBoss.

If you’re running UmpleOnline on an Apache server, then unless you follow these directions you will not be able to see the generated JSF application using UmpleOnline – but you would still be able to download the generated WAR and run it independently on your own local Tomcat server. You can, however, take the steps described here to integrate Apache with Tomcat so requests to open the generated UI are redirected to a local Tomcat server to be taken care of.

There is a directory under umpleonline/scripts named JSFProvider. And there is a sample generated application named "TempProj" also under umpleonline/scripts. These instructions describe how to work with that sample application to get the Tomcat/Apache integration working. Once that is working, you can then arrange for the UmpleOnline web app to also generate apps properly.

We need to tell Tomcat to expect an application running from the umpleonline/scripts/TempProj directory, which is different than its default. We also need to tell Apache that requests from TempProj need to be redirected to Tomcat. The instructions in this document have been tested for Tomcat 6.0 but they may work for other versions as well.

Prerequisites

It is assumed you have Apache installed as well as a checked-out version of Umple with the TempProj directory. It is also assumed that you have followed the directions for setting up a local UmpleOnline web site either for Linux and Mac or for Windows.

Step 1. Verifying UmpleOnline Setup

Let’s begin by verifying a web application on your local installation of UmpleOnline. Enter the following address (where cruise.local may be something different if you have given your local server a different virtual domain name)

http://cruise.local/umpleonline/scripts/TempProj/index.jsp

or also try

http://cruise.local/TempProj/

If you see something like Figure 1, then your server is already capable of running web applications and you can jump to Step 6.

Obsolete Figure

Otherwise, you should see the listing of the contents of TempProj directory; even if you click on index.jsp something like Figure 2 will be displayed:

Obsolete Figure

Step 2. Setting up Tomcat

If you have Tomcat 6.0 or above already installed, then skip to step 3.

(Note that the instructions here were tested on Tomcat 6, and we had trouble with Tomcat 7, so Tomcat 6 is your best choice)

Here's how you set up Tomcat in Mac The resulting installation will be in /Library/Tomcat. If your computer is not setup for development purposes, this may not work due to permission problems. In that case, take a couple of steps to resolve the issue.

Here's how you set up Tomcat in Linux CentOS:

The suggested installation, assumed here, is /opt/tomcat (Alternative Approach)

And here's one way of setting up Tomcat in Windows. The Windows installation process is straightforward. It is possible to install Tomcat as a Windows startup service; or one can choose to simply start Tomcat by running startup from command prompt and stop it by running shutdown.

Hints

You might want to start Tomcat on a port other than 8080 (perhaps because you already have a server on port 8080 and want to use 8081 instead)

If you have many web servers running and are not sure which version is which, you can run the following command if you have ‘curl’:

curl -I http://localhost:8080 curl -I http://server:port

This will return Apache-Coyote for Tomcat. You can also use the following URL if the website is accessible from the Internet.

http://aruljohn.com/webserver.php

On the cruise server, Tomcat was installed under /opt/tomcat and the port used was 8081. This is not accessible outside the University of Ottawa.

Step 3. Test the Tomcat server with the TempProj directory

In this section we will test whether the TomCat server can directly run the TempProj web app.

On Mac/Linux machines

make a symbolic link so that the tomcat/webapps directory has a pointer to the TempProj directory. Go to the Tomcat directory (e.g. /Library/Tomcat/webapps on a Mac) and execute:

ln -s ~/umple/umpleonline/scripts/TempProj .

where ~/umple is the pointer to your local version of UmpleOnline. On a Mac you do not normally need to restart Tomcat. But if you do need to do this execute the shutdown.sh and startup.sh scripts in Tomcat’s bin directory.

On Windows

Simply copy/paste the same directory under your tomcat/webapps. (Re)start your tomcat. To restart tomcat, you need to first shut it down by running shutdown from command prompt or by stopping the service. Then, run startup from command prompt or start the service. You can start/stop a Windows service by accessing the Services panel under Administrative Tools in Control Panel.

Browsing TempProj

Now browse the TempProj directory through the Tomcat web server; the default port for Tomcat is usually 8080: http://127.0.0.1:8080/TempProj/. You should see Figure 1. If not, either your Tomcat installation is not correct or you’re running a Tomcat version that can’t run UIGU. Note that your localhost address and/or port number might be different.

Step 4 Adding required modules to Apache

It’s important to know that Apache and Tomcat cannot directly talk as one is written in C and the other is Java. Instead, Tomcat provides specific modules named connectors, which Apache can communicate with – through tomcat workers - if certain modules are added to it. This module for Apache is named mod_jk, or formally called Tomcat Connectors.

Downloading or building

Download the one matching your system. If possible obtain the binary release, which is typically a compressed file. If you there isn’t a binary release for your platform (e.g. Linux/Mac) then you will have to obtain a source release and build it. Building is described in native/Building.txt. On the Mac you go to the native directory and execute:

./configure --with-apxs=/usr/sbin/apxs

Note that you need to have C compiler on your machine if you’re building from the source files. If the configuration failed because of lack of a C compiler, On the Mac, go to connect.apple.com, register for a developer account and download Command Line Tools for Xcode. Installing this should resolve the issue. then run:

make

The result will be a file named native/apache-2.0/mod_jk.so Put this in your apache modules directory.

Installing mod_jk.so

Unpack the mod_jk.so if it is compressed. A downloaded binary version of the file might have a long name containing version number and target platform specifications. Rename it to mod_jk.so for simplicity. Copy the mod_jk.so into your apache modules directory. On Mac Os this should be in /usr/libexec/apache2/ On Windows C:\apache\modules\ but you might have Apache installed on a different drive or directory.

Configuring httpd.conf

Now, open the httpd.conf (or httpd.config) file under your Apache conf directory. On a Mac this would be at /etc/Apache2 for example. Add the following lines at the bottom of this file (shutdown your Apache before doing so): Note that {modulesdir} will be directory where you put the mod_jk.so file And {tomcatconfdir} will be the conf subdirectory of the Tomcat directory you installed Tomcat earlier.

LoadModule jk_module "{modulesdir}mod_jk.so"
JkWorkersFile "{tomcatconfdir}workers.properties"
JkLogFile "{tomcatconfdir}mod_jk.log"
JkLogLevel debug
# Select the log format
JkLogStampFormat "[%a %b %d %H:%M:%S %Y] "
# JkOptions indicate to send SSL KEY SIZE,
JkOptions +ForwardKeySize +ForwardURICompat -ForwardDirectories
# JkRequestLogFormat set the request format
JkRequestLogFormat "%w %V %T"
# Send servlet for context /TempProj to worker named ajp13
JkMount /TempProj ajp13
JkMount /TempProj/* ajp13

Note that if you have configured your local umple online as a virtual host (which you most likely would have done when setting up UmpleOnline), then you need to add those two last lines (JkMount instructions) within your virtual host tag right before it closes.

Configuring workers.properties

You may notice we are providing specific files from Tomcat here. You shouldn’t worry about mod_jk.log as it will be created automatically. But you need to provide a workers.properties file. A sample is found in the TempProj directory, which should be enough for most cases. Copy this into the Tomcat configuration directory.

You will need to change the following paths in this file

workers.tomcat_home= {the directory where you installed Tomcat}
workers.java_home= {directory where Java installed}
ps= {slash direction for your operating system}

Hint

To find the directory where Java is installed on a Mac, execute /usr/libexec/java_home You will note that the file contains three workers but we only need one in this example.

Configuring server.xml

In tomcat/conf, open the server.xml file and add the following within the Host tag:

<Listener className="org.apache.jk.config.ApacheConfig" modJk="{modulesdir}mod_jk.so" />
<Context path="/TempProj" docBase="{umpleonlinedirectory}scripts/TempProj" debug="0" reloadable="true" crossContext="false"></Context>

The first adds a listener for our mod_jk and the second is like adding a virtual host kept outside Tomcat. Path indicates the name of the external web site and docBase is the directory, where the content is. By adding this line, we avoid having to have the generated content by UmpleOnline being physically copied to Tomcat webapps directory. Add the first line – Listener – to the tag Server as well.

One More Thing

It is also important to ensure tomcat and its workers follow the same policies. One important one is the connection timeout. For example, if you're allowing a 300 seconds timeout to your workers (in workers.properties):

worker.ajp13.connection_pool_timeout=300

you should assign 300000 milliseconds in your server.xml to connectionTimeout attribute of the pertinent Connector tag, i.e. the one connecting to your AJP worker:

 <Connector port="8009" protocol="AJP/1.3" redirectPort="8443" connectionTimeout="300000"/>

Note that port numbers may be different on your server.

Step 5 Starting the servers

Start your Tomcat, wait a few seconds, start your Apache, wait a few seconds, browse http://127.0.0.1:80/TempProj/ and you should see Figure 1 now.

Step 6 Adding required directories on UmpleOnline

Stop the servers again. In order to set up umpleonline to generate UIGU code, we need to complete three more tasks:

  1. Add uigu directories under umpleonline/ump. Create a directory named uigu in umpleonline/ump. Copy the uigudirectories.php script from TempProj directory to uigu directory. Create empty uigu directories by running uigudirectories.php (type php uigudirectories.php). You should have directories named uigu0000 to uigu0099 under umpleonline/ump folder. Make sure you then get rid of the uigudirectories.php script from the uigu directory, as it is important for correct functioning that this only contain subdirectories starting with uigu
  2. Run the server_xml_entry_writer.jar file found in the TempProj directory. This will prompt you for your umpleonline directory (to which you should add /ump/uigu/, and then create a file called server_xml_entries.txt. Copy/paste the contents of server_xml_entries.txt under where you previously added the line defining TempProj in your Tomcat server.xml file (i.e. just before the final closing host tag). This defines the context for uigu directories in Tomcat.
  3. Add the following two lines to your httpd.conf, under where you previously added the lines containg TempProj context in Step 4:
   JkMount /uigu* ajp13
   JkMount /uigu*/* ajp13
  1. Tomcat needs more memory to be able to handle this number of applications. You need to increase the memory required by Tomcat by adding the following to the JAVA_OPTS in bin/catalina.sh (for unix/Max/Linux) or bin/catalina.bat (for Windows)
-Xms128m -Xmx1024m -XX:MaxPermSize=1024m
1. More details: Open the _catalina_ file corrsponding to your OS. Search for _JAVA\_OPTS_. You should see something like:
if [ -z "$LOGGING_MANAGER" ]; then
  JAVA_OPTS="$JAVA_OPTS -Djava.util.logging.manager=org.apache.juli.ClassLoaderLogManager"
else
  JAVA_OPTS="$JAVA_OPTS $LOGGING_MANAGER"
fi
1. Simply, add the memory arguments add the end of both lines with _JAVA\_OPTS_ to make them look like:
if [ -z "$LOGGING_MANAGER" ]; then
  JAVA_OPTS="$JAVA_OPTS -Djava.util.logging.manager=org.apache.juli.ClassLoaderLogManager -Xms128m -Xmx1024m -XX:MaxPermSize=1024m"
else
  JAVA_OPTS="$JAVA_OPTS $LOGGING_MANAGER -Xms128m -Xmx1024m -XX:MaxPermSize=1024m"
fi
  1. Restart the servers beginning with Tomcat. Note that it may now take Tomcat a few minutes to start.