Notes on deploying a Play Framework application to a production server

Lately I’ve been deploying a Play Framework 2.1.x application to a production Linux server once a day, and I’ve kept a few notes as I’ve been going along. My notes may be a little cryptic, but here they are.

Step 1) Packaging the application

To package my Play application, I follow these steps.

First, I update the appVersion in project/Build.scala. For instance, if your first release was 0.1, you’ll want to increment this to 0.2. (Update: With Play 2.2, update the version setting in the build.scala file in your project’s root directory.)

Next, I build a Zip file that I can deploy to the production server with the Play dist command:

$ play clean compile dist

That command creates a file named something like target/scala-2.10/kbhr-1.1-SNAPSHOT.zip. (I call my app KBHR, and deploy it to kbhr.co.) I then use the scp command to copy that Zip file to my Linux server.

Step 2) Deploying and running the Play 2.1 app on the production server

To run the app on the production server, I follow these steps:

1. Copy the Zip file to a deployment directory, like /opt/kbhr.
2. Unzip the Zip file. This creates a new directory named kbhr-1.1-SNAPSHOT
3. I cd into that directory, and copy my startup script to that directory. (More on this in a moment.)
4. I shut down the previous version of the application, then start this version. You can find the PID of the previous version with the ps command, like ps auxw | grep java.

I’ve written a little script I use to start/run my Play application. It’s a wrapper script that invokes the start script that Play generates. Including the comments I leave in there for myself, it looks like this:

# Copy this file to the Play application folder (where the 'start' script is), then use it to run the app.

# default Xmx is 64M (http://docs.oracle.com/javase/1.4.2/docs/tooldocs/linux/java.html).
# 'port 9000' is the default, but i specify it in case i want/need to change it.
# memory options: -Xms512M -Xmx1G

chmod +x start
nohup ./start -server -Dconfig.resource=application-prod.conf -Dhttp.port=9000 &

(I don’t know if the -server option is necessary ... I need to spend a little more time looking that up. I used to use it with Java applications, because once upon a time I think the JVM used to default to the client JIT.)

I name this file al-start.sh, so I just copy it to my Play Framework application directory, and run it like this:

$ ./al-start.sh

A few notes about this script:

1. I created this script so I don’t have to edit the Play start script.
2. It uses a Play configuration file named application-prod.conf. That file just needs to be on the classpath, so having it in the Play application conf folder is all you need.
3. It runs the server on port 9000. You don’t need to specify that on the command line, but I have a bad memory, so if I want to change this later, it’s easiest to specify it now.

Another note about the production environment: Port 80 on the kbhr.co website is served by Nginx, and it does a proxy to serve the Play application.

There are more Play Framework startup options, and I identify those in my Play Framework Recipes booklet.

Play 2.2 changes

The startup process changed in Play 2.2. The new startup script is in your zip file’s bin directory, and is named after your application, which is kbhr in my case. The command line options have also changed. As a result, my new al-start script looks like this:

# Copy this file to the KBHR folder, then use it to run the app.

# default Xmx is 64M (http://docs.oracle.com/javase/1.4.2/docs/tooldocs/linux/java.html).
# 'port 9000' is the default, but i put this here as a note to self in case i need to change it.
# start -Dhttp.port=8080 -Xms512M -Xmx1G (this was a play 2.1 command)

# play 2.2 has changed; see http://www.playframework.com/documentation/2.2.x/ProductionConfiguration

# play 2.2 command:
nohup bin/kbhr -J-server -Dconfig.resource=application-prod.conf -Dhttp.port=9000 &

To help control the memory on a small Play application, I just added the Xmx and Xms command line parameters, and so my command looks like this:

nohup bin/myapp -J-server -J-Xms32M -J-Xmx64M -Dconfig.resource=application-prod.conf -Dhttp.port=9000 &

More information

For more information on deploying Play Framework applications to production servers, see these URLs:

• http://www.playframework.com/documentation/2.1.x/Production
• http://www.playframework.com/documentation/2.1.x/ProductionConfiguration
• My Play Framework Recipes booklet

In summary, if you’re deploying a Play application to a production server, I hope this has been helpful.