Creating a Personal PaaS with Dokku on HPCloud

Jun 21 2013

Would you like to build your own PaaS-like playground? It works like Heroku, runs on Ubuntu, and is entirely Open Source. What's it called? Dokku.

In this article, I explain how to install Dokku on an HP Cloud instance to build your own mini-PaaS with hardly any work. <!--break-->

Step 1: Create a VM

I created an extra-small VM. Since Ubuntu 13.04 hasn't made it through the image catalog on HP Cloud yet, I installed Ubuntu 12.10.

Since I have the hpcloud CLI installed on my Mac, getting this set up was as easy as running this command:

hpcloud servers:add dokku xsmall -k hpcompute -s Web -i 75839

The above…

  • Creates a server named dokku
  • With an xsmall extra small flavor
  • Using my hpcompute public key (which I'll use again later)
  • In the Web security group (which allows ports 22, 80, and 443)
  • Using the image 75839 (which, in region-a, az-1 is Ubuntu 12.10)

Step 2: Upgrade to Ubuntu 13.04

Upgrading from Ubuntu 12.10 to 13.04 is easy to do, though you do have to wait about 20 minutes. SSH into your new instance and start the upgrade process.

First, make sure all of the packages are updated to the latest version:

$ sudo apt-get update && sudo apt-get dist-upgrade

I suppose this isn't strictly necessary, but I feel like it's safer. You may need to reboot your VM after this (especially if there was a kernel update).

Next, we run the release upgrade tool:

$ sudo do-release-upgrade

Since we're upgrading over SSH, the tool will start up an extra SSH server. Read all of the directions that it displays. They will be helpful if anything goes wrong.

Because the package repository is inside of the same cloud that the VM runs in, I found that the installation was very, very fast.

Step 3: Install Dokku

Now we can install Dokku, which in turn will install several dependency packages, include

wget -qO- | sudo bash

This takes a few minutes, but doesn't involve anything from you.

Step 4: Tell Dokku Who You Are

Now we need to upload an SSH public key to the remote server so that we can authenticate to Git. I want to use the same SSH public key that I use to SSH in normally (mine's called hpcompute).

If you've got the hpcloud CLI installed, here's a cool trick for loading the key:

hpcloud keypairs:public_key hpcompute | ssh ubuntu@ "sudo gitreceive upload-key dokku"

The above dumps the public key from HP Cloud and loads it into Dokku. (Change the IP address to the public IP for your newly created server!)

Or you can just...

If the above won't work for you (or you don't have hpcloud installed), you can try copying your public key to the server, and then running this on the server:

cat | sudo gitreceive upload-key dokku

Among other things, this puts the public key in /home/git/authorized_keys. Sometimes the permissions on SSH files can cause a few headaches (the price of security).

Step 5: Tell Dokku Who It is

There's really only one additional configuration step to do for Dokku: Edit /home/git/DOMAIN and add a DNS name.

Since I don't want to go through the hassle of registering a domain name for a testing box, I just use and the public IP of the instance, so my DOMAIN file looks like this:

(Replace with your real IP address)

That's it!

How Do I Use This Crazy Thing?

Now the fun part. I'm on my local Mac, and I am going to create a simple PHP demo app:

$ mkdir DokkuPHP
$ cd DokkuPHP
$ git init
$ vi index.php # Create a simple hello world script. See below.
$ git add index.php
$ git commit -m "Initial commit"

Above, I just created a basic PHP project. index.php just looks like this:

print "Hello world";

So now I've got my project. Dokku is git-oriented. To deploy, we push to the main Git server running on our Dokku VM.

That means we have one extra setup step for our local git repo. We need to point it to our Dokku VM:

$ git remote add 

All that's left to do now is deploy an application, and it's as easy as doing a git push!

$ git push dokku master
Counting objects: 3, done.
Writing objects: 100% (3/3), 247 bytes, done.
Total 3 (delta 0), reused 0 (delta 0)
remote: -----> Building DokkuPHP ...
remote:        PHP app detected
remote: -----> Bundling Apache version 2.2.22
remote: -----> Bundling PHP version 5.3.10
remote: -----> Discovering process types
remote:        Default process types for PHP -> web
remote: -----> Build complete!
remote: -----> Deploying DokkuPHP ...
remote: -----> Application deployed:
 * [new branch]      master -> master

As you can see from the output above, my application was deployed, and I now have a URL:

Dokku detected that I have a PHP application, and deployed accordingly. To modify my app, all I need to do are commit new changes and re-push with git.

There are plenty of other sample packages for you to look at.