Getting started with Play 2.0, Heroku and Scala

This is another tutorial of the category ‘quick start for absolute beginners’. This time the topic is on Play 2.0, Heroku and Scala. The reason for this tutorial is that recent announcements indicate that the three topics will have a bright future together. A really nice overview of all three topics can be found in this presentation on slideshare (simply skip the Akka part. Or even better, read it as well!).

Play 2.0

As the time of writing Play 2.0 is still in beta status and according to the official homepage, APIs are likely to change a bit in the future. Nevertheless, I guess it is time to have a quick look into the new features of the framework and create a simple application.

Installing Play

As we would like to access all latest features, we are going to build Play from the source code ourselves. Therefore, you need to retrieve the sources from GitHub. If you haven’t installed git yet, do so now. Next, clone the play repository by calling git clone git://github.com/playframework/Play20.git

Once you have the source code on your local machine, switch to the ../play20/framework folder and type build. This will start up an embedded sbt shell, in which you have to execute the build-repository command. (Make sure that you have a solid internet connection, as this step will require to download some megabytes of data. I tried it in the train, which was very frustrating…)

To complete the installation, you need to add the ../play20/ folder to your systems PATH environment variable.

More detailed instructions on how to install Play 2.0 (either from source, or from pre-compiled binary packages) can be found in the Play 2.0 wiki.

Creating a Simple Application

Once Play 2.0 is setup on your machine, you can create a simple applicationby typing play new myFirstApp. Provide the name of your application and as we would like to use Scala as our main development language, select the according entry. And that is it! You have just created your first Play application.

Play 2.0 comes with a nifty little console, which supports many development task out of the box. The most common command for you to execute is likely to be run. Others might include, console, clean, compile and test. The commands are more or less self explanatory. Nevertheless, there is also a help goal (you may guess what this one does), and a little bit of documentation.

If you don’t want to open the Play Console just to execute a single command, you can also type play [your_command]. For now, this is what you should do, type play run to start the server in development mode.

After the server has been started, open a browser and go to http://localhost:9000 You should see something similar to the screenshot below.

Creating and running a Play application

Play 2.0 Application

Where to go from here

In the previous section we have successfully created a simple Play 2.0 application. The second part of this post will show you how to get this application running on Heroku. But before we go there, I would like to point you to some further resources to get familiar with Play 2.0.

Most defiantly you should have a closer look on the anatomy of a Play 2.0 application. Furthermore, there are three nice sample applications, which are provided within the Play 2.0 sources and documented adequately in the wiki. Last but not least you might also want to browse through Play’s scala api manual.

Heroku

I promised you, that this article will show you how to get your Play application running on Heroku. So let’s see how this is done.

Quickstarting Heroku

First of all, go to heroku signup page and enter your E-Mail address. After you have received a confirmation mail and provided a password, you are successfully signed up.

Next go to the quickstart guide and download the heroku toolbelt corresponding to your system and install it. After the installation is completed you can start to access heroku from the command line. Type heroku login to connect to the heroku platform servers. The first time you connect to heroku you need to provide your personal SSH key (or simply hit enter to automatically create a new one).

Now that you are logged in to Heroku, you are ready to deploy your Play application. Unfortunately, your app isn’t ready for that process yet, so let’s apply some minor changes.

Making your app ready for Heroku

The following section is based on the Deploying Play to Heroku tutorial, you might either read the original source or the summary given here.

Heroku needs to know how to start your add, therfore you should add a start script provided by the great folks at typesafe. Simply add the following line to your project/plugins.sbt file (Ensure that you also place a blank line before and after this line): addSbtPlugin(“com.typesafe.startscript” % “xsbt-start-script-plugin” % “0.5.0”)

Next, you need to create a plain text file in your application’s root directory called Procfile containing the following line: web: target/start

The next thing to do is create a local git repository for your application. In your application root folder, just type git init to create the repo, then type git add . to add all files and folder and finally make a commit by typing git commit -m “init”.

Last thing to do is creating your app at heroku, do this by typing heroku create –stack cedar. (Make sure you are still logged in to heroku!) You shoud note down the url where your application is going to be available. In my case that is http://blooming-dawn-3920.heokuapp.com/

Making your app ready for heroku

Deploying your app

By now, everything you need to deploy your Play 2.0 application to Heroku should be set up. The last thing you need to do is simply push your contents from your local git repository to the heroku server. To do so, type git push heroku master, after your sources are transferred to the remote repository an automatic execution of sbt clean compile stage is triggered. If everything went well, you should see something similar to the screen shot below. You should also be able to go to your url and see your application running there.

Successful Heroku Deployment

You are now ready to develop some nice features for your application. Whenever you want to deploy a new version of your app heroku, simply push your changes by executing git push heroku master again. Three more hints before I leave you alone with your app: You can tpye heroku ps to check the state of your application, call heroku logs to access your applications log files, and even start a remote REPL session by executing heroku run sbt play.

And now, happy coding!

Advertisements

Get rid of “unmappable character for encoding Cp1252” once and for all

Nowadays, many open source as well as commercially developed projects contain code that is UTF-8 encoded. More general it is very unlikely that you checkout some code from GIT, SVN or [insert arbitrary abbreviation here] that is actually encoded with Windows’ crappy default encoding. (In case of my western European system, that encoding would be Cp1252).

So, how many times have you seen the above error when compiling some Java code on a windows machine? And how many times have you wondered if there is a solution to set the file encoding in a global, system wide manner? Well, fortunately, there is a way to do that!

A quite simple procedure to globally set the file encoding for all JVMs is given in the answer by erickson in this stackoverflow question. All you need to do, is to specify a envirnoment variable called JAVA_TOOL_OPTIONS. If you set this variable to -Dfile.encoding=UTF8, everytime a JVM is started, it will pick up this information.

Obviously, you are able set other JVM parameters via JAVA_TOOL_OPTIONS as well. See the JVM documentation for more details. If you are interested in further details about character encodings in Java, check out this excellent article.