We hope you find this tutorial helpful. In addition to guides like this one, we provide simple cloud infrastructure for developers. Learn more →

How To Use the Dokku One-Click DigitalOcean Image to Run a Play! App

PostedNovember 25, 2013 19.6k views Dokku One-Click Install Apps DigitalOcean

Note: The Dokku project has changed significantly since this guide was written. The instructions below may not reflect the current state of the Dokku project.

Introduction


A significant hurdle in developing an application is providing a sane and easy way to deploy your finished product. Dokku is a Platform as a Service solution that enables you to quickly deploy and configure an application to a production environment on a separate server.

Dokku is similar to Heroku in that you can deploy to a remote server. The difference is that Dokku is built to deploy to a single, personal server and is extremely lightweight. Dokku uses Docker, a Linux container system, to easily manage its deployments.

In this guide, we will cover how to deploy a Java Play! app with Dokku using the DigitalOcean Dokku one-click installation image.

Step One –– Create the Dokku Droplet


The first thing we need to do is create the VPS instance that contains our Dokku installation. This is simple to set up using the DigitalOcean Dokku application.

Click on the "Create" button to create a new droplet:

DigitalOcean create droplet

Name your droplet, and select the size and region that you would like to use:

DigitalOcean configure droplet 1

Scroll down and click on the "Applications" tab. Select the Dokku application image:

DigitalOcean Dokku image

Select your SSH keys if you have them available. If you do not already have them configured, now is a great time to create SSH keys to use with your DigitalOcean droplets. This step will help you later.

Click "Create Droplet". Your Dokku VPS instance will be created.

DigitalOcean final create

Once your droplet is created, you should set up your domain name to point to your new Dokku droplet. You can learn how to configure domain names with DigitalOcean here.

Step Two –– Access the Droplet To Complete Configuration


You can complete your Dokku configuration by accessing your VPS from a web browser.

If you configured a domain name to point to your Dokku installation, you should visit your domain name with your favorite web browser. If you do not have a domain name configured, you can use your droplet's IP address.

You will be given a simple configuration page. There are a few parts that you need to configure here.

DigitalOcean Dokku ssh keys

First, check that the Public Key matches the computer that you will be deploying from. This means that if your project is on your home computer, you should use the public key that corresponds to that set up.

If you selected multiple SSH keys to embed during droplet creation, only the first will be available here. Modify it as necessary.

DigitalOcean Dokku hostname configuration

Next, modify the Hostname field to match your domain name. Leave this as your IP address if you do not have a domain name configured.

Choose the way that you want your applications to be referenced. By default, the application will be served like this:

http://your_domain.com:app_specific_port_number

If you select the "Use virtualhost naming for apps" check box, your apps will be accessible using a virtualhost instead:

http://app_name.your_domain.com

Click the "Finish Setup" button to complete the configuration.

Step Three –– Deploy a Sample Java Play! Application to your Dokku Droplet


Now that we have Dokku configured, we can begin to work on the application that we want to deploy. In general, Java Play! applications should work well without a lot of Dokku-specific tweaking.

Install the Play! Environment on your Development Computer


Before we can deploy a Java Play application on Dokku, we need to configure our development environment. For the purposes of this guide, the development environment refers to the computer with the SSH key pair that matches the one you inputted during the Dokku setup.

We will assume that your development machine is an Ubuntu 12.04 VPS instance, but it could be anything. The installation steps listed here might be different depending on your development operating system. Check here for the Play! installation steps on other platforms.

On your Ubuntu 12.04 development droplet, you will need to install OpenJDK before installing the Play! framework. We will also take this opportunity to install git for version control and unzip to extract the Play! files:

sudo apt-get install openjdk-6-jdk git unzip

Now that we have the Java Development Kit installed, we can install the Play! framework. This is not in Ubuntu's default repositories, so we can acquire it from the project's website. As of this writing, the newest version is 2.2.1, but you will want to check to see if there is a newer version available:

cd ~
wget http://downloads.typesafe.com/play/2.2.1/play-2.2.1.zip

Extract the framework files into the current directory:

unzip play-*

The directory where the files are extracted is where the actual Play! executable will reside. Change to this directory so that we can make the command executable for all users:

cd play-*
chmod a+x play

We need to add this directory to our command path though so that we can run it easily.

Run this command and replace the part in red with the path to your play directory. This will depend on your username and your play version:

export PATH=$PATH:/home/user_name/play-play_version

This will set the path to the play executable for this session. To do this automatically every time you log in, add the line to the bottom of your .bashrc file:

nano ~/.bashrc
export PATH=$PATH:/home/user_name/play-play_version

You should now have the play framework installed. You are ready for a Play! project to deploy to Dokku.

Build a Simple Play! Application


The point of a web framework is to have access to a structured method of building applications. Like other frameworks, Play! provides ways to quickly get an application environment up and running.

Change to the directory where you'd like your new application and type the play new command to create a new project:

cd ~
play new app_name

You will be asked what the name of your application is and whether your app will be a Java or a Scala app. We will be deploying a very, very simple Java app in this example:

       _
 _ __ | | __ _ _  _
| '_ \| |/ _' | || |
|  __/|_|\____|\__ /
|_|            |__/

play 2.2.1 built with Scala 2.10.2 (running Java 1.6.0_27), http://www.playframework.com

The new application will be created in /home/justin/app_name

What is the application name? [app_name]
> app_name

Which template do you want to use for this new application? 

  1             - Create a simple Scala application
  2             - Create a simple Java application

> 2
OK, application app_name is created.

Have fun!

Now, change into the application directory that was created to begin tweaking the project:

cd app_name

For the sake of brevity, we are going to forgo some of the more complex MVC (Model, view, controller) interactions and create a simple "Hello world" application.

The controller that will render our default web page is located within the application's directory at app/controllers/Application.java. Let's open that file so that we can modify it now:

nano app/controllers/Application.java

The function within this file that renders the default page is the index() function. Replace the contents of this function with this:

. . .
    public static Result index() {
        return ok("Hello World!");
    }
}

This will return the string "Hello World" when the root of the application is requested.

Initiate Version Control for the Project through Git


In order to deploy our application on Dokku, our project needs to be controlled through a git repository. It is trivial to create a git repo for our project.

Before we do that, if this is your first time using git on this computer, initiate your user details so that git will operate correctly:

git config --global user.email "your_email"
git config --global user.name "your_name"

Now, change directories to your project root and initiate a git repository:

cd ~/app_name
git init

Now, add all of the project files into git and commit the changes:

git add .
git commit -m 'Initial Commit'

Deploy your Play! Application Using Dokku


Now, our project is completely within git. We can deploy it from here to Dokku by simply adding our Dokku droplet as a remote for this repository.

In this command, the remote_name can be anything because it is just a label on the local machine. In most cases, it makes sense to name it something like "dokku" or "production". The app_name is the name that you will use to access your application on Dokku and from the web browser if you set up virtual hosts during the Dokku configuration.

git remote add remote_name dokku@your_domain.com:app_name

To deploy the application, just push it to the remote repository we just defined:

git push remote_name master

You will see the build messages in your terminal as Dokku configures the application environment and deploys your application within it. You will be given the web address that you can use to reach your application:

. . .
-----> Discovering process types
       Default process types for Play 2.x - Java -> web
-----> Releasing roar ...
-----> Deploying roar ...
-----> Cleaning up ...
=====> Application deployed:
       http://app_name.your_domain.com

To dokku@your_domain.com:app_name
   11f13b1..bf21e58  master -> master

If you visit the address, you should see something that looks like this:

Hello World!

Conclusion


You now should have a decent idea of how to deploy a Play! app using Dokku. This process gets more complicated the more complex your application is.

For instance, databases are handled within Dokku through a plugin system. If your application relies on a database, you will need to install the plugin on the Dokku droplet. The precess could look something like this:

dokku plugin:install https://github.com/dokku/dokku-postgres.git
dokku postgres:create app_name

Then, you would have to reference the variable $DATABASE_URL from within your project. Dokku will automatically link the two together and populate the $DATABASE_URL environmental variable with the correct connection information.

Complex Play! applications are outside of the scope of this article, but they should be trivial to deploy once you have successfully run it locally.

By Justin Ellingwood

21 Comments

Creative Commons License