Tomcat and Virtual Hosts

In this guide I’ll go through setting up some very simple virtual hosts on an Tomcat server. This guide assumes the steps gone through to setup Tomcat 6 on Ubuntu as per this previous post.

So, the first step is to define the host under /etc/tomcat6/server.xml:

Put the above line in the Catalina “Engine” section. The “name” attribute will be used as the hostname to match and the “appBase” will define where Tomcat will look for the applications to run off of this host. If you’d like to define some aliases for this virtual host, you can do so with a nested “Alias” directive as described in the Tomcat documentation.

Next, if we want to define the Context we simply create the directory for it under Catalina:

mkdir /etc/tomcat6/Catalina/example.org

And then for a simple application we can just copy the ROOT app from the default context:

cp /etc/tomcat6/Catalina/localhost/ROOT.xml /etc/tomcat6/example.org

This will define the Context for our application. Next, we will need to create the application directory to actually hold our applications for this virtual host and copy the relevant application files to this new directory. This is done with:

mkdir /var/lib/tomcat6/example.org
cp -r /var/lib/tomcat6/webapps/ROOT /var/lib/tomcat6/example.org

Then I modified the “index.html” file under “example.org/ROOT/” to display “example.org” instead of the default “It Works!” so that we would know when the Virtual Host was being accessed. Once this is done, we can go ahead and restart Tomcat in order to apply the changes:

sudo service tomcat6 restart

To test out that this configuration is working, I added a line to my hosts file (/etc/hosts under linux) on my desktop machine to point “example.org” to the IP address of the VM that I had installed Tomcat on. This allowed me to type in http://example.org:8080 and have the request go to the Tomcat server.

If everything worked out well, going to the virtual host at http://example.org:8080 should yield the modified page, where as going to http://%5BTomcat server IP]:8080 will result in the default page.

So, there you have it, that’s the short story on how to setup up virtual hosts on Apache Tomcat.

How to setup Apache as a Tomcat proxy

In this post we’re going to setup Apache to act as a proxy for the Tomcat application server on Ubuntu. First off we need to install the “tomcat6” package from the Ubuntu repositories, which is as simple as:

sudo apt-get install tomcat6

and answering “Y” to download Tomcat along with all of its dependencies. To make sure that the Tomcat server is running, try to open up port 8080 on the machine in your browser. If all is well you will see the Tomcat server Welcome page. If not, you may need to start up the server, which can be done with:

sudo service tomcat6 start

Next we need to install the Apache HTTP server, which “apt-get” also makes easy for us:

sudo apt-get install apache2

Again, just enter “Y” when asked whether to download the package and all of its dependencies.

In order to enable Apache to act as a proxy for Tomcat, we’re going to need to make use of the “proxy” and “proxy_http” modules. Unfortunately these two modules don’t come enabled by default, so we’re going to have to enable them and restart apache for the changes to take effect:

sudo a2enmod proxy
sudo a2enmod proxy_http
sudo service apache2 restart

Now we need to tell the proxy module how to proxy the requests and where to proxy them to. For this I’ve created a “tomcat-proxy” file under /etc/apache2/sites-available/, which we’re going to enable using Apache’s a2ensite command. The file itself looks like the following:

ProxyRequests Off
ProxyPreserveHost On
ProxyTimeout 1000
TimeOut 1000
#
# Configure the mod_proxy
#
ProxyPass / http://127.0.0.1:8080/
ProxyPassReverse / http://127.0.0.1:8080/

After editing the file we enable the site and reload Apache’s configuration:

sudo a2ensite tomcat-proxy
sudo service apache2 reload

And that’s it! If everything’s gone to plan we should be able to hit up port 80 on our server and get the Tomcat welcome page.

Note that this isn’t the only way to configure Apache as a proxy. A more sophisticated way is to make use of the AJP protocol/module, which is custom designed to work with Tomcat.

To get Apache proxying to Tomcat using the AJP protocol, we have to enable the Apache module and restart Apache for the changes to take effect:

sudo a2enmod proxy_ajp
sudo service apache2 restart

Next we have to enable the AJP connector in Tomcat. This is done in the /etc/tomcat6/server.xml file. If you edit this file you’ll need to uncomment a line, which looks like:

<connector port=”8009″ protocol=”AJP/1.3″ redirectport=”8443″></connector>

and restart Tomcat:

sudo service tomcat6 restart

The next step is to simply go back to our configuration file under /etc/apache2/sites-available/tomcat-proxy and change the protocol and port of the URL’s we supplied the ProxyPass and ProxyPassReverse directives:

ProxyRequests Off
ProxyPreserveHost On
ProxyTimeout 1000
TimeOut 1000
#
# Configure the mod_proxy
#
ProxyPass / ajp://127.0.0.1:8009/
ProxyPassReverse / ajp://127.0.0.1:8009/

You’ll notice we’ve replaced “http” in the URL with the custom “ajp” protocol. Restart Apache and hitting port 80 on the server should redirect you to the Tomcat welcome page as before.

What’s the difference between the two approaches to proxing? Functionally there’s not really any difference that the user gets to see. However, the AJP is a binary protocol, compared to the regular HTTP proxy method that the first approach uses. This should mean less data passed between the proxy and application server as well as lower latencies. Look out for a future post benchmarking the two approaches to see what the real-world difference in performance between the two approaches is.

Installing APR based Tomcat Native library

After installing Tomcat I kept seeing the following message in the Catalina logs:

INFO: The APR based Apache Tomcat Native library which allows optimal performance in production environments was not found on the java.library.path: /usr/lib/jvm/java-6-openjdk/jre/lib/i386/client:/usr/lib/jvm/java-6-openjdk/jre/lib/i386:/usr/lib/jvm/java-6-openjdk/jre/../lib/i386:/usr/java/packages/lib/i386:/usr/lib/jni:/lib:/usr/lib

This got my curiosity up and after learning about APR and the benefits it supposedly offers, I decided I would try it out and see if I could notice any difference in performance. Luckily, there’s a package in Ubuntu for the Tomcat native libraries, making it easy to install:

sudo apt-get install libtcnative-1

This should install the library as well as all of the packages that it depends on. I restarted Tomcat after installing this package, but it still didn’t detect the library. I couldn’t get around this problem and didn’t manage to solve it. It turned out that the next time I started my laptop I didn’t get the warning in the logs, but instead I saw:

03/05/2011 3:39:15 PM org.apache.catalina.core.AprLifecycleListener init

INFO: Loaded APR based Apache Tomcat Native library 1.1.19.

03/05/2011 3:39:15 PM org.apache.catalina.core.AprLifecycleListener init

INFO: APR capabilities: IPv6 [true], sendfile [true], accept filters [false], random [true].

I think that some part of the Tomcat/JVM stack scans for the libraries when the computer starts and caches them from then on and this was what was causing Tomcat to not see the native library files straight away after install.

Now that Tomcat had detected and was using the libraries, I loaded up a few test projects as well as looking at the example projects included with the Tomcat install, but couldn’t notice any difference in performance. Hopefully in the next few weeks I can go ahead and test out Tomcat performance using JMeter, ab or something similar and compare the results with APR and without.

NOTE: Just as an update to this post, the process for installing Tomcat Native on CentOS is a lot more complicated as there is no ‘libtcnative’ package for CentOS and the best guide I’ve found for it so far involves compiling ‘libtcnative’ from source.

Grails part 3 – database and deployment

In this, part 3 of the series on Grails, I am going to talk about how to configure our web application to use the MySQL database as our default permanent store and then how to create a war file and deploy to Tomcat.

Firstly, we’re going to install MySQL. Luckily the state of Linux package management has advanced to the point where this is as simple as:

sudo apt-get install mysql-server

It should ask what you want to set the root user password to and then install the database. Once it has installed, the database server should be started. To check this, you can run the ps aux | grep mysql command. You should see a line in the output with:

mysql 1004 0.0 0.6 178908 27960 ? Ssl 21:50 0:00 /usr/sbin/mysqld

Then we need to create the database:

CREATE DATABASE Bookstore_dev;

Now that we have our database ready to go, we need to get the MySQL driver so that our grails application can connect to the database. Go to http://www.mysql.com/downloads/ and download the Connector/J package from the MySQL connectors section. Uncompress the package and copy and paste the mysql-connector-java-5.1.15-bin.jar file into the BookStore/lib folder.

Next we’ll need to modify our BookStore/grails-app/conf/DataSource.groovy file to specify that we want grails to use the MySQL database instead of the typical HSQLDB that is used. The DataSource.groovy file has three different sections “development”, “test” and “production”, corresponding to the three different stages of the development process and the three different environments that you can work with in grails. You can define a different database for each stage/environment. There is also a default “dataSource” section at the top, which is used unless the values are overwritten in each of the different sections. To start with, we’re going to specify that the development environment should use the MySQL database. We can do this by modifying the development section to look like:

development {
dataSource {
dbCreate = “create”
url = “jdbc:mysql://localhost/Bookstore_dev”
driverClassName = “com.mysql.jdbc.Driver”
username = “root”
password = “password”
}
}

Ofcourse you’ll need to change the username and password to whatever you’ve set them to. I’ll also point out that it’s not good practice to use the root user to access our database, because if our application gets hacked, our whole database would be compromised. It would be best from a security standpoint to create a new user with privileges limited to the “Bookstore_dev” database. However, since this is just our development database and we’re only making it available to our local computer network for the time being it should be ok.

If we now start up our application using the grails run-app command, and once it’s started browse to http://localhost:8080/BookStore, we should be able to see our application. We can then add some dummy data to check that it’s getting saved to the database. I’ve gone ahead and added the authors “Stephen King” and “Robert A. Heinlein” and the books “Pet Cemetery”, “Stranger in a Strange Land”, “The Moon is a Harsh Mistress” (associating them with their respective authors). If you log into the database and have a look at it’s contents you can see that the values have been added:

mysql> USE Bookstore_dev;
mysql> SHOW TABLES;
+————————-+
| Tables_in_Bookstore_dev |
+————————-+
| author |
| book |
+————————-+
2 rows in set (0.01 sec)

mysql> SELECT * FROM author;
+—-+———+——————–+
| id | version | name |
+—-+———+——————–+
| 1 | 0 | Stephen King |
| 2 | 0 | Robert A. Heinlein |
+—-+———+——————–+
2 rows in set (0.01 sec)

mysql> SELECT * FROM book;
+—-+———+———–+—————————-+
| id | version | author_id | title |
+—-+———+———–+—————————-+
| 1 | 0 | 1 | Pet Cemetery |
| 3 | 0 | 2 | Starship Troopers |
| 4 | 0 | 2 | Stranger in a Strange Land |
+—-+———+———–+—————————-+
3 rows in set (0.00 sec)
So, we can see that the data is being saved to the database and that the association between the Author and Book object is represented with the ‘author_id’ field in the Book table. It’s also worth noting the “version” field which is updated by grails every time any of the fields in the row are modified.

So now that we’ve got an application which uses a database it’s time to deploy it to our *production* server. We’re going to modify our DataSource.groovy file to ensure that the production environment (the one we’re going to deploy) also uses the MySQL database:

production {
dataSource {
dbCreate = “update”
url = “jdbc:mysql://localhost/Bookstore_dev”
driverClassName = “com.mysql.jdbc.Driver”
username = “root”
password = “password”
}
}

Make sure you’ve executed the run-app command with dbCreate set to “create” before deploying this production code as dbCreate = “update” expects the tables to already be created in the database.

Now we can create the war file which we’re going to upload to Tomcat through the manager web-app by running the command grails prod war. This generates a production environment war file. The production environment is optimized for code efficiency, while the development and testing environments are optimized for developer productivity. Once the command finishes executing we should have our war file under BookStore/target/BookStore-0.1.war. The 0.1 is the application version number and can be changed in the BookStore/application.properties file.

Now we can log into our Tomcat manager application (found at http://localhost:8080/manager/html if you’ve setup Tomcat according to the previous post), go to the Deploy section, select our WAR file and hit ‘Deploy’. Once the page refreshes we should see our BookStore app in the list of applications and the column “Running” should be set to “true”. We can now click on the link in the Path column to go to our web-app and start using it.

As an alternative way to deploy your application, you can also make use of the tomcat grails plugin. In order to do this you need to add a few variables to the BookStore/grails-app/conf/Config.groovy file, namely:

tomcat.deploy.username = “[tomcat manager user]”
tomcat.deploy.password = “[tomcat manager password]”
tomcat.deploy.url = “http://localhost:8080/manager&#8221;

Deploying the application is now achieved from the command line with:

grails prod tomcat deploy

This code essentially does the same thing that we did, makes a war file and deploys it, but might be preferable as it is only one step instead of two.

So there you have it, we’ve taken our simple web application, configured it to use a permanent datastore and deployed it to our Tomcat webserver.

NOTE: If you need to update your deployed application, the way to do it is to first “undeploy” the application from Tomcat, which can be done with “grails prod tomcat undeploy”