I wrote a shell script to control Play framework applications packaged using built-in command dist
. Applications packaged this way are zipped standalone distributions without any need to have Play framework installed on the machine that it’s supposed to run on. Everything needed is inside the package. Inside the zip, in the bin directory, there is an executable shell script named just like your application. You can start your application by running this script. That’s all it does, but I want more.
Script setup
Download the script from GitHub and make it executable:
chmod +x ./dist-play-app-initd
Before you run the script, you have to set values of NAME, PORT and APP_DIR variables.
- NAME – name of the application, must be the same as the name of shell script generated by Play framework to run the app
- PORT – port number at which the app should run
- APP_DIR – path to directory where you have unzipped the packaged app
Let’s take my side project Jugjane as an example. I ran “play dist
” and it has generated “jugjane-1.1-SNAPSHOT.zip” file. If I unzip it, I get single directory named “jugjane-1.1-SNAPSHOT” which I move to “/home/rado/bin/jugjane-1.1-SNAPSHOT“. The shell script generated by Play framework is “/home/rado/bin/jugjane-1.1-SNAPSHOT/bin/jugjane“. I would like to run the application on port 9000. My values would be:
NAME=jugjane
PORT=9000
APP_DIR=/home/rado/bin/jugjane-1.1-SNAPSHOT
Start, stop, restart and check status
Now I can conveniently run my Play application as a daemon. Let’s run it.
Start
To start my Jugjane application I simply run following:
$ ./dist-play-app-initd start
Starting jugjane at port 9000... OK [PID=6564]
Restart
$ ./dist-play-app-initd restart
Stopping jugjane... OK [PID=6564 stopped]
Starting jugjane at port 9000... OK [PID=6677]
Status
$ ./dist-play-app-initd status
Checking jugjane at port 9000... OK [PID=6677 running]
Stop
$ ./dist-play-app-initd stop
Stopping jugjane... OK [PID=6677 stopped]
Start your application when machine starts
This depends on your operating system, but typically you need to move this script to /etc/init.d directory.
Implementation details
The script uses RUNNING_PID file generated by Play framework which contains ID of the application server process.
Safe start
After starting the application the script checks whether the RUNNING_PID file has been created and whether the process is really running. After that it uses wget utility to issue an HTTP GET request for root document to do yet another check whether the server is alive. Of course this assumes that your application serves this document. If you don’t like (or have) wget I have provided curl version for your convenience as well.
Safe stop
Stop checks whether the process whose ID is in the RUNNING_PID file really belongs to your application. This is an important check so that we don’t kill an innocent process by accident. Then it sends termination signals to the process starting with the most gentle ones until the process dies.
Contribution
I thank my employer Dominion Marine Media allowing me to share this joy with you. Feel free to contribute.