h1. Deployment options

Play applications can be deployed virtually anywhere: inside Servlet containers, as standalone servers, on Heroku, Google Application Engine, Stack, a Cloud, etc...

h2. <a name="standalone">Standalone Play applications</a>

The simplest and the most robust way is to simply run your Play application without any container. You can use a frontal HTTP server like Lighttpd or Apache if you need more advanced HTTP features like virtual hosting.

The built-in HTTP server can serve thousands of HTTP requests per second so it will never be the performance bottleneck. Moreover it uses a more efficient threading model (where a Servlet container uses 1 thread per request). Different "modules":http://playframework.com/modules allow you to use different servers (Grizzly, Netty, etc...) as well.

Those servers support long polling and allow to manage very long requests (waiting for a long task to complete), and direct streaming of File objects (and any InputStream if you specify the Content-Length), without blocking the execution thread.

You will have fewer problems running your application this way, as you will use the same environment that you used during the development process. A lot of bugs can be discovered only when you deploy to a JEE application server (different home dir, classloader issues, library conflicts, etc...).

Please refer to the "'Put your application in production' page":production for more information.

h2. <a name="appservers">Java EE application servers</a>

Your Play application can also run inside your favorite application server. Most application servers are supported out of the box.

h3. Supported application servers

The following application servers are known to work with Play. Please feel free to report any other working deployment.

* JBoss 4.2.x
* JBoss 5.x
* JBoss 6M2
* Glassfish v3
* IBM Websphere 6.1
* IBM Websphere 7
* Geronimo 2.x
* Tomcat 6.x
* Jetty 7.x
* Resin 4.0.5

h3. Deploying

You need to package your application as a WAR file. This is easily done with the following command:

bc. play war myapp -o myapp.war

It can be invoke with the following parameters:

* --output, or -o:
 The path where the WAR directory will be created. The contents of this directory will first be deleted.

* --zip:
 By default, the script creates an exploded WAR. If you want a zipped archive, specify the --zip option.

* --%fwk_id:
 Use this ID to run the application (override the default framework ID)

* --deps:
 Resolve and install dependencies before running the command.

* --exclude:
 Excludes a list of directories (separator is ':').
 Example: --exclude .svn:tmp:logs:target

p(note). Please note that your application server must support deployment of exploded WAR files.

You are now ready to deploy your application.

You are advised to ‘isolate’ your Play application from the other applications to avoid version mismatches between the application libraries. This step is not standardized by the JEE/Servlet specification, and is therefore vendor-specific.

We recommend you refer to your application server manual in order to ‘isolate’ your WAR. As an example below is how you isolate a war file in JBoss Application server. Note that this is an optional step:

Insert the following content (or create the file) in your application war directory at @myapp.war/WEB-INF/jboss-web.xml@:

bc. 
<jboss-web>
 <class-loading java2classloadingcompliance="false">
 <loader-repository>
 com.example:archive=unique-archive-name
 <loader-repository-config>java2ParentDelegation=false</loader-repository-config>
 </loader-repository>
</class-loading>
</jboss-web>

Replace com.example:archive=unique-archive-name with whatever you wish as long as it is unique.            


h3. Datasource

Play also supports Datasource and resource look-up. To use a JNDI Datasource, set the "database configuration":configuration#dbconf as shown below:

bc. db=java:comp/env/jdbc/mydb
jpa.dialect=org.hibernate.dialect.Oracle10gDialect
jpa.ddl=verify

The database plugin detects the pattern @db=java:@ and will de-activate the default JDBC system.


h3. Custom web.xml

Some application servers, such as IBM Websphere, require you to declare a datasource in a @resource-ref@ element in the Servlet API’s @web.xml@ configuration file. By default, @web.xml@ is a file that is generated by Play when you execute the @play war@ command. To customise the generated @web.xml@, generate the exploded WAR version, then copy the generated @web.xml@ file to the @war/WEB-INF@ folder in your application. The next time you will execute the @play war@ command, it will copy your custom @web.xml@ from to the generated folder.

For instance, to declare a datasource for IBM Websphere 7, we can declare a @resource-ref@ in our @war/WEB-INF/web.xml@ file:

bc. <?xml version="1.0" ?>
<web-app xmlns="http://java.sun.com/xml/ns/j2ee"
        xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
        xsi:schemaLocation="http://java.sun.com/xml/ns/j2ee http://java.sun.com/xml/ns/j2ee/web-app_2_4.xsd"
        version="2.4">
  <display-name>Play! (%APPLICATION_NAME%)</display-name>
  <context-param>
    <param-name>play.id</param-name>
    <param-value>%PLAY_ID%</param-value>
  </context-param>
  <listener>
      <listener-class>play.server.ServletWrapper</listener-class>
  </listener>
  <servlet>
    <servlet-name>play</servlet-name>
    <servlet-class>play.server.ServletWrapper</servlet-class>	
  </servlet>
  <servlet-mapping>
    <servlet-name>play</servlet-name>
    <url-pattern>/</url-pattern>
  </servlet-mapping>
  <resource-ref>
        <description>Play Datasource for testDatasource</description>
        <res-ref-name>jdbc/mydb</res-ref-name>
        <res-type>javax.sql.DataSource</res-type>
        <res-auth>Container</res-auth>
  </resource-ref>
</web-app>


h2. <a name="cloud">Cloud-based hosting</a>


h3. <a name="elasticbeanstalk">AWS Elastic Beanstalk</a>

"AWS Elastic Beanstalk":http://aws.amazon.com/en/elasticbeanstalk/ is Amazon’s Java hosting platform, based on their Amazon Web Services infrastructure. For more information about deploying a Play application, see "Java development 2.0: Play-ing with Amazon RDS":http://www.ibm.com/developerworks/java/library/j-javadev2-19/.


h3. <a name="cloudbees">CloudBees</a>

"CloudBees":http://www.cloudbees.com/ is a Java application hosting platform. For more information, see the "CloudBees module":https://www.playframework.com/modules/cloudbees.


h3. <a name="cloudfondry">Cloud Foundry</a>

"Cloud Foundry":http://www.cloudfoundry.com/ is VMware’s cloud provider. For more information, see "Running Play Framework Application on CloudFoundry":http://iambivas.blogspot.com/2011/08/running-play-framework-application-on.html and the "CloudFoundry module":https://www.playframework.com/modules/cloudfoundry.


h3. <a name="gae">Google App Engine (GAE)</a>

The "Google App Engine":http://code.google.com/appengine/ is one of the first cloud hosting platforms, which has different pros and cons compared to generic hosting solutions. In particular, GAE does not support JPA persistence. For more information, see the "GAE module":https://www.playframework.com/modules/gae.


h3. <a name="heroku">Heroku</a>

The "Heroku cloud application platform":http://www.heroku.com/ has Play-specific application hosting support. To deploy and run your Play application, use the following steps.

1. Install the Heroku command line client on "Linux":http://toolbelt.herokuapp.com/linux/readme, "Mac":http://toolbelt.herokuapp.com/osx/download, or "Windows":http://toolbelt.herokuapp.com/windows/download.
2. Install "git":http://git-scm.com/ and setup your SSH key.
3. Create an account on "Heroku.com":http://heroku.com/signup.
4. Log in to Heroku from the command line:

bc. heroku auth:login

5. Create a git repository:

bc. git init

6. Create a @.gitignore@ file containing the following content, to ignore files generated by Play:

bc. /tmp
/modules
/lib
/test-result
/logs

7. Add the files to the git repository and commit them:

bc. git add .
git commit -m init

8. Create a new application on Heroku:

bc. heroku create -s cedar

9. Push the application to Heroku:

bc. git push heroku master

10. Open the application in your browser:

bc. heroku open


To view the logs run:

bc. heroku logs

To scale the application to multiple ‘dynos’ run:

bc. heroku scale web=2

To use the "Heroku Shared Database":http://devcenter.heroku.com/articles/database in production add the following to your @conf/application.conf@ file:

bc. %prod.db=${DATABASE_URL}
%prod.jpa.dialect=org.hibernate.dialect.PostgreSQLDialect
%prod.jpa.ddl=update

For more information, see the "Heroku Dev Center":http://devcenter.heroku.com.




h3. <a name="upstart">VPS / Custom Server</a>

If you want to run play as a service on your own server you can start it with this simple upstart script
This upstart script works with ubuntu 10.04 and upwards (upstart 1.4)

bc.
description "Play Framework"
version "1.0"
env PLAY_BIN=/opt/playframework/play
env PROFILE=prod
start on runlevel [2345]
stop on runlevel [016]
respawn
respawn limit 10 5
umask 022
setuid youruser
setgid www-data
chdir /home/youruser/app/current
pre-start script
    test -x $PLAY_BIN || { stop; exit 0; }
    rm /home/youruser/app/current/server.pid || true
end script
exec $PLAY_BIN run $HOME -Xms1024M -Xmx1024M --%$PROFILE
