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 Node.js App

PostedNovember 24, 2013 44k views Dokku One-Click Install Apps Node.js Git Ubuntu

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.


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 Node.js 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:


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


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

Step Three –– Deploy a Sample Node.js Application to your Dokku Droplet

At this point, your Dokku droplet is configured and ready to start receiving git repositories, which it will deploy automatically.

This process is as simple as pushing a local git repository to your Dokku droplet.

What Requirements do Dokku Apps Have?

In order for Dokku to recognize a repository as housing a Node.js application, a file called package.json must be present at the document root. This describes the application details and supplies the dependency and versioning information that will help Dokku deploy.

In order for the application to be correctly deployed on Dokku, a file called Procfile must be present as well. This file contains the actual command that must be run to start the web process to serve your app.

  • Procfile: A file called "Procfile" is required to be in the root application directory. The purpose of this file is to specify how the application should be run once deployed.

Basically, it specifies the commands necessary to start the web process for your project.

For many Node.js projects, this can be as simple as:

web: node app_name.js
  • package.json: In order for Dokku to recognize a repository as housing a Node.js application, this file must be present at the document root. This describes the application details and supplies the dependency and versioning information that will help Dokku deploy.

If you do not already have a package.json file, you can generate one by issuing this command in your application root directory:

npm init

This will ask you quite a few questions and create a package.json file for you. You will have to go back and manually add some dependency information for your application and an engine that describes the engines you're using. This could look like this:

. . .
"version": "0.2.3",
"dependencies": {
    "express": "3.1.x"
"engines": {
    "node": "0.10.x",
    "npm": "1.2.x"
"description": "a sample application for Dokku"
. . .

These are the two segments that tell Dokku what it needs to install and configure for your application environment.

Deploy a Database for Your Node.js App

Dokku and Heroku handle databases and other resources as entities that should remain separate from the core application. This allows you to easily switch the backend if another database will suit your needs better.

Dokku handles this through a plugin system. We will install and configure this plugin system here. If your application does not rely on a database, you can skip this section.

Our application will use a PostgreSQL database for its storage. You can learn about the available Dokku plugins here, if your requirements are different.

To install the plugin, log into your Dokku droplet, and run:

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

Now, we have the PostgreSQL libraries for Dokku installed. Let's create a database for our application. Dokku links an application with an associated database at deployment by looking for a database with a matching name.

We will have to decide what to name our application (which will have implications on the URL we will access it from if using virtual hosts), here. Deploy a database with the following command:

dokku postgres:create app_name

You will receive a message of confirmation that looks like this:

-----> Starting container
       Waiting for container to be ready
       Creating container database
=====> Postgres container created: app_name
       DSN: postgres://postgres:1f61e96c987fc06cc5e71e70baeee776@

This tells you the connection details that are needed to use this database. We can get this information at any time by typing:

dokku postgres:info app_name

This information is used to create an environmental variable called DATABASE_URL that is assigned upon deployment.

Deploy a Sample Node.js App

Now, we can deploy a sample Node.js app to our Dokku server. We will choose a simple Node.js Monitoring library that will help us demonstrate some concepts.

On your development computer (the computer with the SSH key that matches the one you inputted in the Dokku setup), clone the repository with this command:

git clone https://github.com/tkalfigo/pigimon.git

Enter the directory to begin modifying its content:

cd pigimon

This project is in alpha stage, and is not built for deployment on Heroku or Dokku, so there are a few things that we need to modify. First of all, there is no "master" branch, only a "develop" branch. Dokku requires a master branch to deploy. Let's make one and switch to it:

git checkout -b master

We can see that there is already a "package.json" file that was mentioned above. This is a good start. However, the author forgot one dependency that will cause our build to fail currently. Let's add it:

nano package.json

In the "dependencies" section of the config file, we need to add a line to tell Dokku that any version of the "jsdom" module is also required. You can insert it anywhere in the dependencies section, as long as you pay attention to the commas:

. . .
  "optimist": "~0.5.0",
  "pg": "~1.1.2",
  "jsdom": "*",
  "underscore": "~1.4.4"
. . .

Save and close the file.

The next thing we need to do is add the "Procfile" that we mentioned as a requirement. Our Procfile will be very simple, and will just tell Dokku to start at the app.js file to run the application:

nano Procfile

web: node app.js

Save and close the file.

Finally, we will need to make a slight modification to how the application connects to the database. As we mentioned, the app currently is not configured for Heroku or Dokku deployments, so it doesn't use the standard variables that these two pieces of software have created. We need to have the app connect using the DATABASE_URL our PostgreSQL database will create.

Open the app.js file.

nano app.js

Search for the PostgreSQL connection command that specifies how to connect to the database. It should look like this:

pg.connect(CONFIG.CONNECTION_STRING, function(err, client, done) {

Currently, the app is connecting using a configuration value in the config.json file. This is represented by the CONFIG.CONNECTION_STRING value that is being passed to the pg.connect command.

Modify this value to use the DATABASE_URL variable. Since this is an environmental variable, we refer to it as process.env.DATABASE_URL:

pg.connect(process.env.DATABASE_URL, function(err, client, done) {

Save and close the file.

Now, our application is modified and should have all of the values needed to run successfully. We need to commit our changes to git so that it is up-to-date:

git add Procfile
git add .
git commit -m "Configure for Dokku"

Now, our application is created and we can push it to the Dokku server. We just need to add the Dokku server as a remote on this project. You can name the "remotename" anything you would like, but "dokku" is a good choice. The "appname" must match the name you chose for your database:

git remote add remote_name dokku@dokku_server_domain:app_name

Now, to deploy, we simply push our code to the Dokku server:

git push remote_name master

You should see quite a bit of output as Dokku builds the dependencies and environment and then deploys your app. At the end, you should see see something like this:

-----> Releasing app_name ...

-----> app_name linked to postgres/app_name database
-----> Deploying app_name ...
-----> Cleaning up ...
=====> Application deployed:

To dokku@domain_name.com:app_name

If you go to the URL that is given, you should be able to see the sample application that we deployed:

Dokku Node.js sample app

If you ever need to remove an application that you have deployed, you can do so by issuing this command on the Dokku server:

dokku delete app_name

To delete an associated PostgreSQL database, you can type:

dokku postgres:delete app_name


At this point, you should have your first Node.js application up and running on your Dokku server. Dokku is under heavy development, and undergoes changes from one release to the next. We recommend that you regularly check the Dokku page on GitHub if you plan on deploying production application.

By Justin Ellingwood


Creative Commons License