WAR Plugin for Play framework 2.0

Current version: 0.8

Project-status: BETA

This project is a module for Play framework 2 to package your apps into standard WAR packages. It can be used with Servlet 3.0 and 2.5 containers (Tomcat 6/7, Jetty 7/8/9, JBoss 5/6/7, ...)

Why choosing WAR packaging when native Play 2 is a better deployment model (features and performances) ?

• Ops don't want to change their deployment model and still want to use WAR in your company
• SSL is available, easy to configure and well documented on JBoss, Tomcat, ... when SSL will be only available on Play 2.1
• You need to add extra Servlet filters specific to your company (to handle SSO, ...)

Live demo: JBoss7@Cloudbees : http://servlet30.play-war.cloudbees.net/

Other references built with Play 2 and Play2War:

• Factile (Survey platform)

Known limitations

• Play2War is only compatible with Java 6 JRE (most of the application servers aren't compatible with too)
• Your WAR must be deployed at root context (sub-context deployment will be available with Play 2.1)

Compatibiity with Play2

• Play 2.0.0 : Play2War 0.3, 0.4
• Play 2.0.1 : Play2War 0.5
• Play 2.0.2 : Play2War 0.6, 0.7.x, 0.8.x
• Play 2.0.3 : Play2War 0.7.x, 0.8.x
• Play 2.0.4 : Play2War 0.7.x, 0.8.x

What's new ?

See Changelog.

Features

Features		Native Play 2	Servlet engine
			3.1	3.0	2.4/2.5
Availability			TBD
Performances		++	?	+	-
HTTP	Asynchronous request processing
	Web Socket
Container	Data sources	Built-in (Bone CP)	Built-in (Bone CP) External DS support : TBD
	Non root context path Eg: http://local/myAppContext	2.0.x : 2.1.x (alpha) :	TBD for Play 2.1

Server compatibility

Servlet engine	Server	In your company	PaaS
Servlet 3.0	Tomcat 7
	Jetty 8
	Jetty 9	TBD	TBD
	JBoss 7.0		Demo @Cloudbees Need extra configuration when deploying
	JBoss 7.1		TBD (Openshift)
Glassfish 3	TBD	TBD
Servlet 2.5	Tomcat 6		TBD (Cloudbees)
	Jetty 7		TBD

The plugin may work on others containers, such as Weblogic or Websphere (not tested yet).

Usage

In the next descriptions, APP_HOME is the root of your Play 2.0 application you want to package as a WAR file.

Add play2war plugin

In APP_HOME/project/plugins.sbt, add:

resolvers += "Play2war plugins release" at "http://repository-play-war.forge.cloudbees.com/release/"

addSbtPlugin("com.github.play2war" % "play2-war-plugin" % "0.8")

Import Play2War SBT settings

In APP_HOME/project/Build.scala, add:

...
import PlayProject._
import com.github.play2war.plugin._

Configure servlet container version and add all Play2war settings in your project configuration

val appVersion      = "1.0-SNAPSHOT"
...
val main = PlayProject(appName, appVersion, appDependencies, mainLang = JAVA).settings(
  // ... Your own settings here
  Play2WarKeys.servletVersion := "3.0"
  // Or Play2WarKeys.servletVersion := "2.5"
).settings(Play2WarPlugin.play2WarSettings: _*)

Configure logging

You probably need to override default Play 2.0 logging configuration because:

• An external file will be written in $USER_HOME/logs/...

• STDOUT appender pattern can be improved

Create a file APP_HOME/conf/logger.xml with the following content :

<configuration>
    
  <conversionRule conversionWord="coloredLevel" converterClass="play.api.Logger$ColoredLevel" />

  <appender name="STDOUT" class="ch.qos.logback.core.ConsoleAppender">
    <encoder>
      <pattern>%date - [%level] - from %logger in %thread %n%message%n%xException%n</pattern>
    </encoder>
  </appender>
  
  <logger name="play" level="INFO" />
  <logger name="application" level="INFO" />
  
  <!-- Off these ones as they are annoying, and anyway we manage configuration ourself -->
  <logger name="com.avaje.ebean.config.PropertyMapLoader" level="OFF" />
  <logger name="com.avaje.ebeaninternal.server.core.XmlConfigLoader" level="OFF" />
  <logger name="com.avaje.ebeaninternal.server.lib.BackgroundThread" level="OFF" />

  <root level="ERROR">
    <appender-ref ref="STDOUT" />
  </root>

Embed custom WAR configuration files

You can embed custom WAR configuration files, such as MANIFEST.MF, web.xml, ... For this, copy then in your APP_HOME/war folder. Don't forget to add subfolders !

Samples:

• APP_HOME/war/myfile.txt will result in app_home.war!/myfile
• APP_HOME/war/META-INF/MANIFEST.MF will result in app_home.war!/META-INF/MANIFEST.MF
• APP_HOME/war/WEB-INF/web.xml will result in app_home.war!/WEB-INF/web.xml

Packaging

Package with:

play package

or with

sbt package

Your WAR package will be available in APP_HOME/target/<MY_PROJECT>_<YOUR_VERSION>.war

How to deploy in my favorite application server ?

Play framework 2.0.x applications must be deployed at root context. Deployment in a sub-context is a known limitation which is fixed for Play 2.1 (still in development).

The best way to deploy at root context is to include a configuration file into the WAR file to indicate to your application server where to deploy the application. But Play2War doesn't support file inclusion yet (see #4).

Tomcat 7 : how to deploy at root context ?

Rename the generated war ROOT.war before deployment.

Jetty 8/9 : how to deploy at root context ?

Rename the generated war ROOT.war before deployment.

JBoss 7.0.x

Extra configuration

If you plan to use Java and EBean persistence model (not JPA), you must add extra configuration below to integrate Play runtime with JBoss VFS (Virtual File Sytem).

In your APP_HOME/project/Build.scala file, add:

val appDependencies = Seq(
  // ... Actual dependencies
  "com.dlecan.reflections" % "jboss7-vfs-integration" % "1.0.1" // add this after your others dependencies
)

How to deploy at root context ?

In standalone/configuration/standalone.xml, comment the subsystem named urn:jboss:domain:pojo:1.0.

Then follow explanations for JBoss 7.1.x below.

JBoss 7.1.x : how to deploy at root context ?

First, disable default welcome page in standalone/configuration/standalone.xml by changing enable-welcome-root="true" to enable-welcome-root="false":

<subsystem xmlns="urn:jboss:domain:web:1.0" default-virtual-server="default-host">
  <connector name="http" scheme="http" protocol="HTTP/1.1" socket-binding="http"/>
  <virtual-server name="default-host" enable-welcome-root="true">
    <alias name="localhost" />
    <alias name="example.com" />
  </virtual-server>
</subsystem>

Then rename the generated war ROOT.war before deployment.

Upload or deploy your WAR file

Upload or deploy your WAR file to your favorite Application Server if compatible (see Compatibility matrix above).

WAR publishing (Artifactory, Nexus, ...)

Play2war follows SBT rules, so built WAR can be published in a standard way (see SBT Publish).

FAQ

See FAQ.

Issues

Please file issues here: https://github.com/dlecan/play2-war-plugin/issues.

Continous integration

Watch it in action here : https://play-war.ci.cloudbees.com/.

How to help ?

Discover how you can help the project.

Licence

This software is licensed under the Apache 2 license, quoted below.

Copyright 2012 Damien Lecan (http://www.dlecan.com).

Licensed under the Apache License, Version 2.0 (the "License"); you may not use this project except in compliance with the License. You may obtain a copy of the License at

http://www.apache.org/licenses/LICENSE-2.0.

Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License.

Built by CloudBees