Migrating Node.js apps from Heroku to Dokku

Heroku (and Dokku) make for an awesome development environment- the most well-known feature being the use of “git push” to deploy changes to a server. For simple projects, I’ve found that the deployment time is as fast as compilation times on JVM based projects, except that at the end you have a working environment.

Knowing you can deploy an environment at any time during a project means you can spin up as many environments as you want later, and it forces you to think through migrations in your checkins.

The downside of Heroku is that you are somewhat locked in, and if you want to build many small applications as a hobbyist, it adds up ($7/mo to keep one app running – the free ones shut down all the time). On the other hand, you could just set up a VM to run several apps, which guarantees many wasted hours on dependency hell problems (every time you update a shared library, you risk breaking what you have previously built).

Conceptually this setup is not that complex, but there are a lot of moving parts to get right, and it isn’t that satisfying to work on vs. actually building things.

To build a system like Heroku where you can push from git, you’d start by checking a script into the repository that runs when code is pushed to one of the remote repositories (a post-commit hook). This would kick off the deployment.

Heroku also has you check in a script to the root of your repository that defines what you want to run (a bash script with something like “node index.js” and any arguments). This lets them control the deployment, and lets the developer control what actually runs.

Virtualization at the operating system-level saves you from dependency issues (called “Linux Containers” or “LXC”), without having to build and secure a VM for every app. Linux containers seem pretty complex and I would assume there are some good ways to screw this up from a security perspective. It is new enough that tools and best practices aren’t as mature and clear as the older generation, so it’s easy to get mired in all the options (the few hours I spent trying to get Docker working have yet to pay off)

There is an open-source script called Dokku (a Star Wars reference, perhaps?), which ties all these pieces together for you, and tries to act as much like Heroku as possible. Consequently you can use a cheap virtual machine, and then upgrade it when you need real infrastructure. The marketing materials for Dokku seem quite slick, so I suspect that one or more companies is sponsoring it (probably someone like Digital Ocean), although I haven’t been able to find evidence of this.

Digital Ocean has a pre-built Dokku image you can use at $5/mo. While they’ve had some growing pains, they typically give out credits when they have issues. If you follow them on Facebook and subscribe to their give out a lot of coupons as well, which has made the $5 VMs basically free – clearly a loss leader for them (feel free to use my referral link – you get $10 off to start, and I get another $25)

Regardless of who you use, if you set up a Dokku image, there is a page where you upload your SSH public key:

This lets it accepts your “git push.”

If you want to use subdomains for each app like Heroku does, you’ll need to add them to your DNS manually. I put Cloudflare on any site I can, if only because it has the best DNS management UI I’ve ever seen (and they don’t do referral links, unfortunately!):


Once you set these two things up, ssh into the VM.

You can run create commands for each app you want to configure:

 dokku apps:create editor
 dokku apps:create meeting
 dokku apps:create gmail-search
 dokku apps:create document-search

This will let your VM receive pushes.

Then, to push changes, you need to set up the remote:

git remote add dokku dokku@apps.garysieling.com:generic-search-ui

If you add this to an existing app, you can push to both Heroku and Dokku simultaneously by doing this:

git push heroku master
git push dokku master

You will see the same sort of commit log on the remote that you see with Heroku:

gary@gary-PC MINGW64 /d/projects/heroku/editor (master)
$ git push dokku master
Counting objects: 451, done.
Delta compression using up to 8 threads.
Compressing objects: 100% (350/350), done.
Writing objects: 100% (451/451), 47.84 KiB | 0 bytes/s, done.
Total 451 (delta 305), reused 138 (delta 91)
-----> Cleaning up...
-----> Building editor from herokuish...
-----> Setting config vars
-----> Setting config vars
       CURL_TIMEOUT: 30
-----> Adding BUILD_ENV to build environment...
-----> Node.js app detected

-----> Creating runtime environment


-----> Installing binaries
       engines.node (package.json):  5.5.0
       engines.npm (package.json):   unspecified (use default)

       Downloading and installing node 5.5.0...
       Using default npm version: 3.3.12

-----> Restoring cache
       Skipping cache restore (new runtime signature)

-----> Building dependencies
       Pruning any extraneous modules
       Installing node modules (package.json)
       editor@1.0.0 /tmp/build
       +-- body-parser@1.14.2

-----> Caching build
       Clearing previous node cache
       Saving 2 cacheDirectories (default):
       - node_modules
       - bower_components (nothing to cache)

-----> Build succeeded!
       +-- body-parser@1.14.2
       +-- cookie-parser@1.4.1
       +-- ejs@2.3.4
       +-- errorhandler@1.4.3
       +-- express@4.13.4
       +-- express-session@1.13.0
       +-- foreman@1.4.1
       +-- http@0.0.0
       +-- lodash@4.0.0
       `-- morgan@1.6.1

-----> Discovering process types
       Procfile declares types -> web
-----> Releasing editor (dokku/editor:latest)...
-----> Deploying editor (dokku/editor:latest)...
-----> DOKKU_SCALE file not found in app image. Generating one based on Procfile...
-----> New DOKKU_SCALE file generated
=====> web=1
-----> Running pre-flight checks
       For more efficient zero downtime deployments, create a file CHECKS.
       See http://dokku.viewdocs.io/dokku/checks-examples.md for examples
       CHECKS file not found in container: Running simple container check...
-----> Waiting for 10 seconds ...
-----> Default container check successful!
=====> editor container output:
       Node app is running on port 5000
=====> end editor container output
-----> Running post-deploy
=====> renaming container (3735de61fe0a) suspicious_euclid to editor.web.1
-----> Creating new /home/dokku/editor/VHOST...
-----> Setting config vars
-----> Configuring editor.garysieling.com...
       (using /var/lib/dokku/plugins/available/
-----> Creating http nginx.conf
-----> Running nginx-pre-reload
       Reloading nginx
-----> Setting config vars
=====> Application deployed:

To dokku@apps.garysieling.com:editor
 * [new branch]      master -> master

Then, if you need a database, you can install this as well:

sudo dokku plugin:install https://github.com/dokku/dokku-postgres.git
dokku postgres:link editor editor

I name my database and my apps the same, which makes the above command a little unclear.

Dokku supports the same concept of environment configuration variables that Heroku does (i.e. your database connection string, API keys, etc should never be checked in). When you run the above commands, you will get log entries like this:

no config vars for generic-search-ui
-----> Setting config vars
       DATABASE_URL: postgres://postgres:baf4@dokku-editor:5432/editor
-----> Restarting app generic-search-ui
App generic-search-ui has not been deployed

If you are migrating an application and change the DNS, you will need to update any references in external services – e.g. typekit, the twitter developer API, Google Developer keys, etc.

Once you’ve set this up, there are some useful troubleshooting commands. E.g. list installed apps:

dokku apps
root@ubuntu-512mb-nyc2-01:~# dokku apps
=====> My Apps

Viewing logs is a little more complex – you need to list the running processes, and get them using docker:

root@ubuntu-512mb-nyc2-01:~# docker ps
CONTAINER ID        IMAGE                            COMMAND                  CREATED              STATUS              PORTS               NAMES
fcc5604164c9        dokku/generic-search-ui:latest   "/start web"             About a minute ago   Up About a minute                       generic-search-ui.web.1
e4e42ace32f2        postgres:9.5.0                   "/docker-entrypoint.s"   About an hour ago    Up About an hour    5432/tcp            dokku.postgres.generic-search-ui
697e11c55807        dokku/editor:latest              "/start web"             2 days ago           Up 2 days                               editor.web.1
docker attach fcc5604164c9

And there you have it- your own PaaS, with limited dependencies on external companies for hosting.

Interested in JavaScript? I send out weekly, personalized emails with articles and conference talks. Click here to see an example and subscribe.

0 replies

Leave a Reply

Want to join the discussion?
Feel free to contribute!

Leave a Reply

Your email address will not be published. Required fields are marked *