zondag 21 augustus 2011

Run a Play framework application as a Windows Service with YAJSW

Hi all, this is my first blog post about the awesome Play framework , I hope that many may follow.

I needed an easy way to run Play! applications as a Windows Service.

By using the java application ‘Yet Another Java Service Wrapper' (YAJSW) and info from the Play! Google group I got it working.

In this post I will make the sample Play! application called yabe run as a Windows service.
Maybe there are other/ better ways to accomplish this, if so let me know.

Prerequisites
Before we start you need the following

Step 1: ‘PLAY_HOME’ environment variable
To be able to run Play anywhere on the command line, I created a ‘PLAY_HOME’ environment variable pointing to the play folder, in my case 'c:\play\play-1.2.2', and added ‘%PLAY_HOME%’ to the ‘PATH’ variable.

This ‘PLAY_HOME’ environment variable will also be used in the wrapper configuration file at step 5.

Step 2: Create the project (folder) structure
For this example we will create the following folder structure by following the steps below;
     c:\play-service
                    \logs
                    \temp
                    \wrapper
                    \yabe

  • Create a new folder for our example called ‘play-service’.
    For the purpose of this demo I created ‘c:\play-service’
  • Copy the yabe demo folder which can be found in the folder “play-1.2.2\samples-and-tests\” to the newly created folder.
  • Unzip the contents of ‘yajsw-beta-10.9.zip’ into the newly created folder and rename it to 'wrapper'.
  • Finally we need to create two new folders called ‘temp’ and ‘logs'.
    In the ‘\temp’ folder the Play application will store temporally files, e.g. for the Captcha image creation.
    In the ‘\logs’ folder the wrapper log files will be stored.

Step 3: Play dependencies
The yabe demo doesn’t make use of a dependencies.yml file in which the modules used are defined. So we can skip this step for this tutorial.

If your own application does make use of the dependencies file, you need to execute the command ‘play deps’.

Step 4: Start Yabe normal as Play application in production mode
Make sure that the Yabe application can be started as a normal Play application in production mode with the command ‘play run --%prod
If all goes according plan, the Yabe application is now up and running and available on port 9000.

Step 5: Create the YAJSW ‘Wrapper’ configuration
Now we are going to create the wrapper configuration to be able to start yabe as windows service.
Edit the empty file “c:\play-service\wrapper\conf\wrapper.conf”, and paste in the following lines;

# Example YAJSW configuration to run Play! application as service
wrapper.working.dir=c:/play-service
wrapper.java.app.mainclass = play.server.Server
wrapper.java.classpath.1 = ${wrapper.working.dir}/yabe/conf/*.*
wrapper.java.classpath.2 = ${PLAY_HOME}/play-1.2.2.jar
wrapper.java.classpath.3 = ${PLAY_HOME}/framework/lib/*.jar
wrapper.java.additional.1 = -Dfile.encoding=utf-8
wrapper.java.additional.2 = -Dapplication.path=${wrapper.working.dir}/yabe
wrapper.java.additional.3 = -Dplay.id=prod
wrapper.java.additional.4 = -Djava.io.tmpdir=temp
wrapper.logfile=${wrapper.working.dir}/logs/wrapper.log
wrapper.console.title = Play! YABE service demo
wrapper.ntservice.name = Play! YABE service demo
wrapper.ntservice.displayname = Play! YABE service demo
wrapper.ntservice.description = Running a Play! app as windows service

Make sure that the ‘wrapper.working.dir’ is pointing to the correct folder!

Step 6: Test the wrapper config
We will first test our configuration to make sure that it all works before we register it as windows service.
Execute the batch file ‘runConsole.bat’ which can be found in the folder ‘c:\play-service\wrapper\bat\’.
This will launch our app as ‘console application’ by using the newly created ‘wrapper.conf’ file.
If all goes according plan, your application starts without errors and becomes available on port 9000.

After you have tested the working of the app, you can stop it by pressing [CTRL+C] in the console window.

Step 7: Install the service
We are allmost there, if step 6 went according plan you can now install the service by executing ‘installService.bat’. Your service will now be registered as ‘Play! YABE service demo’, you can check this with help of the windows services manager.

Step 8: Start the service for the first time
During the installation of the service in step 7, the service startup type has been set to ‘automatic’, but it hasn’t been started yet. Execute ‘startService.bat’ or press the ‘start’ button in the windows service manager.

Making changes to the wrapper config
If you need to make changes to the config make sure you first stop the service ‘stopService.bat’ and uninstall it with ‘uninstallService.bat’. After making your changes you start with step 6 again to test your new config.

Conslusion
I was very pleased to discover how easy it is to get a Play application up and running as a Windows Service. To actually accomplish this I only used a small part of YAJSW. It has much more to offer, have a look on their website. Last but not least, don’t forget to checkout the awesome Play framework which makes writing Java Web apps easy, fast and fun!