Heroku Alternative: Deploy Apps with Dokku on DigitalOcean

When Heroku announced their (quite reasonable) new limits for free apps, I realized that I would have to find another source of hosting for all the small, low-traffic projects that I currently have running on Heroku. Way back in the day, Heroku was totally free for apps that only required one dyno, but after years of abuse from jerks like me, they dropped that to eventually allowing free apps to run for 18 out of 24 hours per day (which is ok for low-traffic prototypes) and as of June 1, granting a shared pool of free hours.

Since I have such an unreasonable number of apps running on Heroku, I thought it was high time to try out Dokku. Dokku is a Heroku-like tool that allows you to deploy complex apps by simply pushing with Git. It supports Heroku buildpacks directly, so you can transition existing apps without difficulty, and has a number of plugins for datastores and other components. And, thankfully, Digital Ocean provides a pre-installed Dokku image that will spare you the trouble of installing Dokku yourself; you can just spin up a server and start Dokku-ing right away! This article will walk you through setting up a Dokku server on DigitalOcean with your own root domain and deploying a simple static site to it.

Differences between Dokku and Heroku

• Dokku requires at least some comfort level with running your own servers; you may have to modify nginx configurations, manually configure some plugins, or turn to the system tools for debugging.
• Dokku utilizes Docker, which is a fine platform but can add an extra layer of complexity to a server install.
• Dokku requires root access to a VPS to install plugins, run commands, etc.

In short, you’re going to need to do a bit more command line setup on Dokku than Heroku — nothing you can’t pick up along the way, but you might need to do some light reading.

Creating a Dokku Server on DigitalOcean

First, log in to DigitalOcean and follow this link to create a new server on DigitalOcean using the preinstalled Dokku app. Dokku requires at least 1GB of RAM, but $10/mo to host all your stuff is a pretty small price.

For your hostname, enter the base domain you want to use to host your apps. Default Dokku apps will appear at <appname>.<hostname> (for example, myapp.example.com). Make sure you own this domain and register it if you need to!

Setting up the domain

You will want to associate a domain with your Dokku server. Just set up an A record for your domain pointing at your server’s IP.

The remainder of this article will assume that you’ve registered example.com for this purpose.

We’re going to set things up such that your apps will appear at <appname>.example.com. To accomplish this, you’ll need to add a few DNS records for your domain:

• create a blank A record pointing at your your server’s IP
• create a wildcard (*) A record pointing at the same IP.

After DNS is resolved, you can continue with the rest of this tutorial.

If you want to host an app on another domain, you can either:

• name the app as otherdomain.com when you create it, which will tell Dokku to use that domain, or
• set up a CNAME DNS record at www.otherdomain.com pointing at myapp.example.com.

Creating Your First App

SSH into your server and run the following:

$ dokku apps:create example.com

This will create an app called “example.com” on your server. This is the app that will appear at the root of your domain; since it has a . in it, Dokku interprets it as a domain name and configures itself accordingly. For future apps, you can simply dokku apps:create appname, and appname.example.com will be their host.

Something you might want to do is to host a static site on example.com. This will let you easily keep it up to date, especially if you use a static site builder like middleman or jekyll.

This capability is built into Dokku, via the handy buildpack-nginx. To set it up, at the root of the project, create an empty file called .static ($ touch .static). This is how the buildpack detects a static site. When you push this to Dokku, it should detect that you are creating a static site and proceed accordingly.

Your project can be as simple as an index.html file, containing whetever you want. Create a new git repo with git init, and add index.html, .static, and .env to it. Then, add Dokku as a remote:

git remote add dokku dokku@example.com:example.com

Now, you should be able to deploy via a simple git push:

git push dokku master

You should be able to see as Dokku configures a container for your app (detecting the static buildpack), and when you navigate to example.com you should see the index.html you created hosted there.

Next Steps

If you have any existing Heroku apps, you should be able to simply add the Dokku remote with Git and run git push dokku master.

You may need to set up a database of some sort. Luckily, the Dokku project currently supports a variety of datastore plugins, including Postgres, Mongo, and Mysql. They are all very easy to install and use.

If you have any trouble, the Dokku docs are very straightforward and comprehensive.

Frequently Asked Questions (FAQs) about Deploying Apps with Dokku on DigitalOcean