Overview

Play is a Web development framework, based on Scala and Java. This document describes how to set up and run Play’s development server, which will suffice for your course project and deployment to a limited user population. If you want to run Play in a real production setting, follow these instructions.

Setting Up

First, refresh your VM by running the following:
/opt/dbcourse/sync.sh

Pick a folder for your Play application, e.g., ~/shared/play-beers (feel free to use a different destination as you see fit; for example, if you have a remote VM, putting it under shared/ wouldn’t be as helpful). Hereafter we will refer to this folder as your “Play app folder.” To install Play on your VM and set up the example Play app, run the command:
/opt/dbcourse/install/setup-play.sh ~/shared/play-beers

Now, we need to make sure you can access the website served by your VM.

• If you can get to your VM’s GUI directly (e.g., if you run VirtualBox and have installed GUI for it), you can simply start a Web browser inside your VM, and access the Play website at http://localhost:9000/.
• If you have (or prefer having) only shell access to your VM, you can access the Play website from a browser running on your host as follows:
  • If you are running a local VM using Vagrant, follow the instructions at Creating and Running VM Using VirtualBox/Vagrant to set up forwarding between your guest port 9000 and your host port 9000. You should then be able to access the Play app at: http://localhost:9000/.
  • If you are running a Google Cloud VM, follow the instructions at Creating and Running VM on Google Cloud to find your VM’s external IP address (say it’s 123.45.67.89, for example), and to allow access to your VM’s port 9000. Then, you should be able to access the Play application at http://123.45.67.89:9000/ (replace 123.45.67.89 with your VM’s external IP).

Running the Website

To run the website, in your Play app directory on the VM, issue the following command:
sbt
This command will put you in sbt‘s interactive command-line environment, with the prompt
[play-beers] $
where play-beers is the name of your app. The first time you start sbt, it will automatically download and set up a lot of stuff for you. Give it enough time.

The first time you enter sbt, type
playUpdateSecret
at the [play-beers] $ prompt.

Inside sbt, type
run
to start your app. A Web server will start running. If you have set up your access to the VM correctly as instructed above, you should now be able to access the website from a browser running on your host. As you interact with the website, you will see various information and/or error messages in the VM shell. The first time you run and access the app, sbt will automatically compile the code, so give it enough time.

You can keep sbt running and edit your app code on the side. Your next visit to the website will (in most cases) trigger any necessary recompilation of modified code, and the changes will be automatically reflected. In some cases, however, you might need to explicitly stop your app and restart it for sbt to pick up the changes.

To stop your app, simply hit [RETURN]; that will take you back to the [play-beers] command-line prompt. Typing exit at the [play-beers] prompt will exit you from sbt and take you back to your VM’s shell.

A Play Primer

Play has following features that simplify Web development:

• A MVC (model-view-controller) architecture, which separates data, presentation, and control flow.
  • The model “wraps” data stored in the database as Java objects, which can be manipulated (created, queried, and updated) by the controller and presented through the views.
  • The controller defines a set of actions. Each action handles a Web request. It interacts with the database through the model, and feeds relevant data to a view to be shown on a Web page.
  • The views are coded in a Scala-based template language, which render data as output HTML. Templates can do some simple post-processing with the content to facilitate presentation (such as sorting and looping through a list of items). There is typically one template for each type of Web page. Play templates can be thought of functions, and you can define a “base” template to factor out common structures/elements on your pages so it can be reused by other templates.
• Mapping between URLs and actions. Play allows you to map URLs to actions defined by the controller, and reverse-map actions to URLs. With the latter, your template code can generate links to other pages from the Java method names of the associated actions, without worrying about the actual URLs used in a particular deployment.
• Automatic mapping of object models to database tables using Ebean. You can specify models using Java classes; Ebean automatically handles their storage, retrieval, and update in a relational database. You can do (almost) all data manipulation on your Java objects without being concerned about SQL. However, we will not use Ebean in our example app.

We now explain the relevant parts of a Play app directory:

• build.sbt: Here you specify your app name (beers for our example) and the list of libraries required by your app (we have already added the JDBC driver here).
• conf/application.conf: This configuration file stores (among other things) your database connection information. For this example, we connect to the PostgreSQL database named beers, which you used extensively in your assignments. You can change the connection information to work with other databases instead.
• conf/routes: This is plain-text file storing the the mapping of URLs to actions. It is a good practice for your templates to reverse-map actions to URLs instead of hardcoding specific URLs. Then, by editing this file alone you can control the URL structure of your site, without worrying about updating your templates.
• app/models/: This directory holds your models. This should be where you write code that interacts with the database.
• app/controllers/Application.java: This file contains the controller for our example app, which implements each action as a method.
• app/views/: This directory holds your templates, which presents Java objects they receive as inputs as HTML views. See documentation on the Play template engine to learn how to write templates. In this example app, main.scala.html serves as the “base” template that controls the overall style of the site.
• public/: This directory contains static files used by your site, such as images, JavaScripts, and stylesheets, organized into respective subdirectories. To refer to these files in your template, use @routes.Assets.at("path_relative_to_public").

Rolling Your Own App

You can just modify the example Play app directory (~/shared/play-beers). You can change the directory name to, for example, play-mycoolapp. Remember to modify the app name in build.bst, and database configuration in conf/application.conf. Then, when you modify your model, views, and controller, remember also to update conf/routes and put required static files in public/ as needed.