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.comwhen you create it, which will tell Dokku to use that domain, or
- set up a CNAME DNS record at
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.
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
$ 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
.env to it. Then, add Dokku as a remote:
git remote add dokku firstname.lastname@example.org: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.
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.