(Last Updated On: July 29, 2018)

Dokku is an extensible, open source Platform as a Service that runs on a single server of your choice. If you ever used Heroku, then think of it as your hosted version of Heroku. You can have docker based Platform as a Service running on a single server. In this guide, we will cover the installation and usage of Dokku on Ubuntu 18.04 Bionic Beaver Linux.

Installation of Dokku on CentOS 7 is still experimental and not the recommended option, though it can run. As of v0.3.18, Dokku defaults to being installed via Debian package, and the same can be automated more using a bootstrap script.

Installing Dokku on Ubuntu 18.04 – Pre-requisites

  • Installed and updated Ubuntu 18.04 system
  • Docker Engine
  • At least 1GB of system memory
  • Server with FQDN set – Can be on DNS or /etc/hosts

There are two ways of installing Dokku on Ubuntu 18.04:

  1. Using bootstrap script
  2. Installing from Dokku apt repository

We will consider both methods to install Dokku on Ubuntu 18.04 Bionic Beaver Linux server. I recommend installing Dokku from the apt repository so that you can have a view of what’s happening.

Set system hostname using the hostnamectl command:

# hostamectl set-hostname dokku.computingforgeeks.com
# echo "192.168.10.20 dokku.computingforgeeks.com dokku" >> /etc/hosts

Method 1: Install Dokku on Ubuntu 18.04 from apt repository

Dokku packages are available on packagecloud.io dokku repository. Start by importing repository GPG key to trust packages:

# wget -nv -O - https://packagecloud.io/gpg.key | apt-key add -
2018-07-29 07:45:29 URL:https://packagecloud.io/gpg.key [3889/3889] -> "-" [1]
OK

Add the repo using the commands below:

echo "deb https://packagecloud.io/dokku/dokku/ubuntu/ bionic main" > /etc/apt/sources.list.d/dokku.list

Then update system package list:

$ sudo apt-get update

Step 1: Install Docker Engine on Ubuntu 18.04

You can install either stable release of Docker or edge release, both are supported by Dokku. For the installation of docker on Ubuntu 18.04 from the official apt repository, follow our guide:

How to install Docker CE on Ubuntu / Debian / Fedora / Arch / CentOS

If you would like to install Edge release, then run the commands:

# wget -nv -O - https://get.docker.com/ | sh

This is unattended installation, wait for it to complete then confirm docker engine version installed:

# docker version
Client:
 Version:           18.06.0-ce
 API version:       1.38
 Go version:        go1.10.3
 Git commit:        0ffa825
 Built:             Wed Jul 18 19:09:54 2018
 OS/Arch:           linux/amd64
 Experimental:      false

Server:
 Engine:
  Version:          18.06.0-ce
  API version:      1.38 (minimum version 1.12)
  Go version:       go1.10.3
  Git commit:       0ffa825
  Built:            Wed Jul 18 19:07:56 2018
  OS/Arch:          linux/amd64
  Experimental:     false

Step 2: Install Dokku on Ubuntu 18.04

Once docker has been installed, you can proceed to install Dokku on your Ubuntu 18.04 LTS system. This is done by updating system packages and installing dokku package:

$ sudo apt-get update && sudo apt-get upgrade
$ sudo apt-get install dokku

Dependencies installed through apt include:

  • herokuish
  • sshcommand
  • plugn

When asked whether to enable web configuration interface, answer yes

Installation of dokku will also configure nginx for you and create a systemd service unit for managing the service. Installation output summary is shown below:

....
Created symlink /etc/systemd/system/docker.service.wants/dokku-redeploy.service → /etc/systemd/system/dokku-redeploy.service.
-----> Migrating zero downtime env variables to 0.5.x. The following variables have been deprecated
=====> DOKKU_SKIP_ALL_CHECKS DOKKU_SKIP_DEFAULT_CHECKS
=====> Please use dokku checks:[disable|enable] <app> to control zero downtime functionality
=====> Migration complete
=====> 
-----> Migrating zero downtime env variables to 0.6.x. The following variables will be migrated
=====> DOKKU_CHECKS_ENABLED -> DOKKU_CHECKS_SKIPPED
=====> Migration complete
=====> 
Generating DH parameters, 2048 bit long safe prime, generator 2
This is going to take a long time
................+.+..............................................................+...............................................................................................................................................................................................................................+...................................................++*++*
Adding user dokku to group adm
-----> Migrating DOKKU_NGINX env variables. The following variables will be migrated
=====> DOKKU_NGINX_PORT -> DOKKU_PROXY_PORT
=====> DOKKU_NGINX_SSL_PORT -> DOKKU_PROXY_SSL_PORT
=====> Migration complete
[ ok ] Starting nginx (via systemctl): nginx.service.
-----> Priming bash-completion cache
Setting up dokku-installer
Enabling dokku-installer
Created symlink /etc/systemd/system/multi-user.target.wants/dokku-installer.service → /etc/systemd/system/dokku-installer.service.
Created symlink /etc/systemd/system/graphical.target.wants/dokku-installer.service → /etc/systemd/system/dokku-installer.service.
Starting dokku-installer
Setting up dokku-update (0.1.0) ...

A user and group named dokku is also added to the system, its home directory is /home/dokku. This user account is used when deploying applications to Dokku.

# id dokku
uid=1002(dokku) gid=1002(dokku) groups=1002(dokku),4(adm),997(docker)

# ls -la /home/dokku/
total 44
drwxr-xr-x 4 dokku dokku 4096 Jul 29 09:13 .
drwxr-xr-x 5 root  root  4096 Jul 29 09:13 ..
-rw-r--r-- 1 dokku dokku  220 Jul 29 09:13 .bash_logout
drwxr-xr-x 2 dokku dokku 4096 Jul 29 09:13 .basher
-rw-r--r-- 1 dokku dokku 3771 Jul 29 09:13 .bashrc
-rw-r--r-- 1 dokku dokku    0 Jul 29 09:13 .cloud-locale-test.skip
-rw-r--r-- 1 dokku dokku  807 Jul 29 09:13 .profile
drwxr-xr-x 2 dokku root  4096 Jul 29 09:13 .ssh
-rw-r--r-- 1 dokku root    15 Jul 29 09:13 .sshcommand
-rw-r--r-- 1 dokku dokku    8 Jul 29 09:13 HOSTNAME
-rw-r--r-- 1 root  root     8 Jul 29 09:13 VERSION
-rw-r--r-- 1 dokku dokku    8 Jul 29 09:13 VHOST

The service should be running by default after the installation. The name of the service is dokku-installer.service

# systemctl status dokku-installer.service
● dokku-installer.service - Dokku web-installer
Loaded: loaded (/etc/systemd/system/dokku-installer.service; enabled; vendor preset: enabled)
Active: active (running) since Sun 2018-07-29 09:13:58 UTC; 9min ago
Main PID: 13389 (python2.7)
Tasks: 1 (limit: 4704)
CGroup: /system.slice/dokku-installer.service
└─13389 python2.7 /usr/share/dokku/contrib/dokku-installer.py selfdestruct

Jul 29 09:13:58 erpnext systemd[1]: Started Dokku web-installer.
Jul 29 09:21:37 erpnext dokku-installer.py[13389]: 127.0.0.1 - - [29/Jul/2018 09:21:37] "GET / HTTP/1.0" 200 -

Confirm if the service is enabled to start on boot:

# systemctl is-enabled dokku-installer.service
enabled

Dokku version can be checked using:

# dokku version
0.12.10

Finish the installation by setting up core dependencies:

# dokku plugin:install-dependencies --core

Step 3: Configure Dokku on Ubuntu 18.04

When done with the installation, go to your server’s IP and follow the web installer to configure Dokku.

Confirm:

  •  SSH Public key that you’ll use to access Dokku apps.
  • Provide FQDN hostname for dokku to be used for apps URL
  • Check Use virtualhost naming to have your apps deployed on Dokku with hostnames

Then click “Finish Setup” button to finish Installation of Dokku on Ubuntu 18.04.

Note that Once you save your settings, the web admin will self-terminate and you should be able to run or deploy to the Dokku installation.

Upgrading Dokku on Ubuntu 18.04

To upgrade Dokku to the latest stable release, use dokku-update command:

# dokku-update

Upgrading Dokku with above command will not affect the running dokku and automates many of the upgrade instructions for you. If you would like to rebuild all applications after the upgrade, use:

# dokku ps:rebuildall

Installing Dokku Plugins

Dokku provides a handful of Plugins to manage other functionalities. All are available on Dokku has official plugins. Installation of these plugins is done on the Dokku host as a root user or using a user account with sudo privileges.

See examples below:

Install PostgreSQL  datastore service:

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

Install MariaDB datastore plugin:

sudo dokku plugin:install https://github.com/dokku/dokku-mariadb.git mariadb

Deploying Apps to Dokku

Now that you have a working Dokku installation on your Ubuntu 18.04 system, you can begin deployment of applications. You can read a comprehensive guide on deploying apps to Dokku,

Conclusion

Dokku is a free and open-source Docker-based PaaS that allows you to basically do the same things as Heroku on your own infrastructure (on-premises or cloud). It is easy to setup and use. If you have any challenges with the installation and configuration, let me know through the comment section.