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.

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”

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”

Tomcat6 on Ubuntu

In this post I’m going to talk about getting Tomcat version 6 up and running on Ubuntu. I’m going to be using Ubuntu 10.10. Installing Tomcat is quite simple, due to it being in the repositories. Simply run:

sudo apt-get install tomcat6 tomcat6-admin tomcat6-examples tomcat6-docs

And that’s it 🙂 You now have a working install of Tomcat version 6 on your machine. In order to see it working point your browser to http://localhost:8080/. You’ll see the Apache “It Works!” message as well as a message about where everything is and links to the docs, examples, manager and host-manager applications.

Now, in order to get access to the manager and host-manager applications you’re going to have to add a user. To do this, modify the file at /etc/tomcat6/tomcat-users.xml and add the following section:

<role rolename=”admin”/>
<role rolename=”manager”/>
<user username=”srdan” password=”password” roles=”admin,manager”/>

After editing the file and restarting the Tomcat server we should be able to log into the manager application by pointing our browser at http://localhost:8080/manager/html and we should be able to log into the host-manager by going to http://localhost:8080/host-manager/html. The manager will allow us to deploy, undeploy, start and stop our applications and the host-manager allows us to declare, remove, start and stop our virtual hosts.

NOTE: From Tomcat 6.0.3 onwards, there is no “manager” role that is recognised by the manager application, rather it has been split up into four roles for security purposes:

manager-gui – allows access to the HTML GUI and the status pages
manager-script – allows access to the text interface and the status pages
manager-jmx – allows access to the JMX proxy and the status pages
manager-status – allows access to the status pages only

To test out the deployment, we’re going to create a very simple web application. First, create a new directory and change into it:

mkdir HelloWorld
cd HelloWorld

Next we’re going to create a servlet with the following code:

import java.io.*;
import java.util.*;
import javax.servlet.*;
import javax.servlet.http.*;

public class HelloWorld extends HttpServlet {

public void doGet(HttpServletRequest request, HttpServletResponse response) throws IOException, ServletException {
response.setContentType(“text/html”);
PrintWriter out = response.getWriter();

out.println(“<html>”);
out.println(“<head>”);

out.println(“<title>Hello World!</title>”);
out.println(“</head>”);
out.println(“<body>”);

out.println(“<h1>Hello World!</h1>);

out.println(“</body>”);
out.println(“</html>”);
}
}
And put it into a file called HelloWorld.java. After this we need to create a WEB-INF and WEB-INF/classes directory. Once we’ve done this, we compile the above code with:

javac -classpath “/usr/share/tomcat6/lib/*” HelloWorld.java

This should result in a HelloWorld.class file in the same directory. We need to move this file to the WEB-INF/classes directory:

mv HelloWorld.class WEB-INF/classes/

Now we need to add a web.xml file, which is going to tell Tomcat about our application. For our purposes we need to create a file with the following contents:

<?xml version=”1.0″ encoding=”ISO-8859-1″?>

<web-app xmlns=”http://java.sun.com/xml/ns/javaee&#8221;
xmlns:xsi=”http://www.w3.org/2001/XMLSchema-instance&#8221;
xsi:schemaLocation=”http://java.sun.com/xml/ns/javaee http://java.sun.com/xml/ns/javaee/web-app_2_5.xsd&#8221;
version=”2.5″>

<description>
Simple Hello World Servlet.
</description>
<display-name>Simple Hello World Servlet</display-name>

<servlet>
<servlet-name>HelloWorld</servlet-name>
<servlet-class>HelloWorld</servlet-class>
</servlet>

<servlet-mapping>
<servlet-name>HelloWorld</servlet-name>
<url-pattern>/HelloWorld</url-pattern>
</servlet-mapping>
</web-app>

Once that’s done, make sure that the file is in the WEB-INF directory, and we can go ahead and create our war file with:

jar -cvf hello.war .

Now we should be able to go back to the manager application at http://localhost:8080/manager/html, go to the Deploy section, select our war file, upload it and have it deploy straight away.

Assuming everything went fine, we can now go to http://localhost:8080/hello/HelloWorld and see our servlet in action, printing out the famous “Hello World!” message in HTML.

That concludes this post. Hopefully now you know how to install Tomcat on Ubuntu, manage it using the manager and host-manager applications, as well as how to create and deploy a very simple web application to the server.