Deploying a Play! application on Tomcat with Apache as frontend, rsync setup

What this tutorial covers

In this tutorial, we will setup a simple site powered by the Play! framework. For that purpose, the Tomcat 6 server is used to host the application. Additionally, Apache is put ahead of Tomcat as a “bridge”, and will also be configured to serve static files. At last the rsync daemon-based upload will be shown and set up, allowing for faster uploads using differential instead of complete uploads.

Creating the Tomcat server configuration in Site Deploy

Switch to the servers tab and click “Add server...”.

Sites and upload settings

Add server dialog, sites and upload settings for Tomcat

Note that you must not use the directory /var/lib/tomcat6/webapps directly for uploads. Tomcat treats WAR filenames in that directory as URL context paths - for example, a web application packaged as “mysite.war” will be reachable on “/mysite”. As Site Deploy allows you to define any URL path, and has the concept of a separate directory for all files related to sites, it needs the WAR file somewhere else. Upon deployment, a XML configuration file is automatically created, telling Tomcat where the WAR file is, and on which URL path it should be mounted.

Configuration upload settings

Add server dialog, configuration upload settings for Tomcat

Just fill in the information as described in the server settings overview. It’s recommended to use tomcat6 as owning group.

Tomcat-specific settings

Add server dialog, Tomcat-specific settings

Tomcat can be configured in two ways:

  1. Auto-deploy

    Tomcat automatically deploys uploaded WAR files when it detects changes to WAR files in its configuration directory or, in the case of Site Deploy, to XML configuration files. The server must not be restarted after uploading a WAR file or else Tomcat is interrupted while unzipping it.

  2. Manual deployment / unzipping at restart

    This is recommended for production environments. Tomcat will only unzip WAR files on restart of the tomcat6 service.

Please have a look at your server.xml file to see which option applies. Site Deploy will decide whether to restart the Tomcat service depending on this setting.

Setting up Apache

We want Apache (on port 80) to bridge to Tomcat - which could then run on any closed port on localhost, and to serve static files.

Add Apache as a new server. You should be able to fill out the “General” tab yourself. Call the server something like “Bridge Apache -> Tomcat”.

Site upload settings

Add server dialog, site upload settings

We won’t upload any sites to Apache, so fill in dummy values as shown.

Configuration upload settings

Add server dialog, configuration upload settings

Nothing special here again, just upload the config files as superuser.

Specific settings

Add server dialog, specific settings

This is important now. As we want Apache to act as a bridge, we need some specific directives here. Apache’s proxy module allows us to forward HTTP requests to Tomcat (here on port 8080). We want to serve static files via Apache, so exclude that URL path (/public) from the forwarding. On the screenshot, it is already assumed that the application runs on the URL path /somewhere on both Apache and Tomcat.

The other settings are just for better caching of static files, just for the sake of completeness.

Creating the site configuration

In this example, we will deploy a Play!-powered site. Just create any working site to begin with. Take a look at the official samples if you don’t have a site.

Here, we will use the Play! Hello World test site provided with Site Deploy’s source code.

General settings

Add site dialog, general settings

If you read the site settings overview, again there is nothing special here, except that both absolute and relative URL path are the same (/somewhere/) because in both the Apache and Tomcat server, we want the site to be hosted on that URL.

Packaging settings

Add site dialog, packaging settings

Select the Tomcat server, the site directory and “Play! framework WAR” packaging. If we let Site Deploy remove the site before re-deployment, we lose that advantage of differential uploads - so untick that checkbox as shown.

Hint

Also open the packaging-specific options dialog. If you know the Play! framework, you will recognize what the options mean.

Static file serving

Leave this empty. This site will be uploaded to Tomcat, but we want to have static serving via Apache. We will cover later how to achieve static serving on Apache.

Play-specific settings

Usually, you can leave this unchanged if the Play! executable is on your PATH. Else you have to select it manually.

Static serving

The site created above will be deployed to Tomcat, as we selected. In order to setup Apache with the static file serving (without having to write that config ourself), we just create another site. Don’t worry, this one is very simple. Click “Add site...” - we will call it “Play! test site (static serving only)”. Select the site type “Dummy”.

Dummy site, packaging settings

Now select Apache (here called “Our Hello World Server (Apache -> Tomcat)”) for deployment, and no upload as this site will only cause the static serving config to be created.

Dummy site, static serving settings

The “public” directory shall be served. Our problem is that Apache doesn’t know about Tomcat, or where the web site is stored, so how does it know the file system directory from which it shall serve files? The answer is, it can’t - so we need to specify that ourselves. Add an entry with the absolute path. For Tomcat6, that would be /var/lib/tomcat6/webapps/play_hello_world/WEB-INF/application/public because our Play! site is mounted on the URL path /somewhere on Tomcat.

Hint

For sub-URL paths like /a/b/c, Tomcat creates the directory name with the scheme a#b#c.

Important

Note that even if it’s a dummy site, the URL paths in the “General” tab are significant because static serving URLs will get prefixed. So, did you keep in mind to set these to /somewhere/? If not, do that now! The URL will then become prefixed to /somewhere/public.

Setting up the rsync daemon

TODO

(As long as this is not documented, change the site upload type to SFTP with tomcat6 as owner.)

Deploying the site

Procedure

The good thing about our configuration is: As long as we don’t change the static serving or Apache configuration, we only need to deploy to Apache once.

Whenever the Play! site changes, you need to deploy only what we called “Play! test site” above. So we only deploy to Tomcat each time.

You should know already how to deploy a site. Follow these steps in any order:

  • Deploy “Play! test site (static serving only)”

    This will create the configuration for Apache, including static serving.

  • Deploy “Play! test site”

    This will use the Play! executable to create a WAR file, upload it to Tomcat and create the XML config for Tomcat. Note that it will take a few seconds or even more for Play! to package a WAR file, especially for bigger applications.

Result

You should see a page saying “Hello world!” in a non-serif font with a Play! favicon.

If not, there’s probably something wrong with the Tomcat configuration - check the next section about common problems.

Common problems

When trying to access the uploaded web site, you might get a 404 error from Tomcat, saying The requested resource (/your-url) is not available.

This happens when Tomcat is still unzipping the WAR file, or has problems in doing so. Also sometimes, you have to restart Tomcat because it runs into a “PermGen space” error (out of memory) after unzipping several WAR files. After restarting Tomcat, give it a bit time to “settle” and then try to call the web site again.