Installing and running Dokku on DigitalOcean

Build your own PaaS by installing Dokku on DigitalOcean.

Dokku runs on top of Docker and is described as a mini-Heroku. It's a Platform as a Service to help you run and manage web applications, reducing the complexity necessary to build and maintain the infrastructure that supports them.

Dokku runs on a single host (it doesn't distribute across a cluster) so it is meant for small projects.

We will be using Dokku v0.4.5 in this article and installation steps are for DigitalOcean. If you sign up to DigitalOcean using the previous link you will get $10 in credit and I will also benefit as a referral.

Here is what we will do in this tutorial:

  • Create SSH keys to connect to the server we will create
  • Create a new server in DigitalOcean with Dokku installed
  • Setup a Git repository for remote deployment
  • Deploy a new app to Dokku by pushing our repository

Create SSH key

The first thing to do is create an SSH key that will be used to connect to the host without having to use a password. You should do this before creating the host.

I will specify the instructions I used to setup this on Windows, since it is a little bit trickier and there isn't as much information.

Generate SSH key files

  • Install PuTTY.
  • Run PuTTYgen.
  • Press "Generate". The defaults should do fine.
  • Move your mouse in the blank area to add randomness to your key while the file is being generated.
  • Choose a passphrase for additional security (without a passphrase anyone with these files will be able to login to your server).
  • Save the public and private key.
  • Convert to OpenSSH in the top menu Conversions > Export OpenSSH key.

Add SSH key to DigitalOcean

Go to your DigitalOcean account settings. Add a new key under Security > SSH Keys.

Give it a name and place the contents of the public key.

You will select this key when creating the droplet and installing Dokku.

Any application that needs to access your remote server will need the private key to access it. For example if you want to connect using SFTP to your server you will need to provide the private key.

Install Dokku

I don't want to dwelve too depth on the basics steps to install Dokku on DigitalOcean since they are very straightforward:

  • Create a new droplet.
  • Choose a hostname (it helps to use a FQDN but it doesn't have to be).
  • Choose your size (start with the smallest one).
  • Choose your datacenter region.
  • Choose an image: select Dokku under "One-click Apps".
  • Select any additional options you might want (note: there seems to be some issues with IPv6; disable it or follow this guide).
  • Make sure to select the SSH key you created previously.

In the next screen you will see Dokku's setup page. It will show your public key, your hostname and if you entered a FQDN as your hostname you can use virtualhost naming for your apps.

It's not a big problem if you don't have a FQDN yet. You can change the hostname later.

Increase swap file

For VMs with less than 1GB, Dokku recommends increasing the swap file size. DigitalOcean also has a guide to configure the swap file on a VPS.

Changing hostname later

If you didn't specify a FQDN when you created the droplet you can change the hostname at a later time.

  • Go to your droplet page in the DigitalOcean site.
  • Go to Settings > Rename.
  • Type the new hostname.

Now update the /etc/hostname file in your droplet. The contents of that file should be your hostname.

You will also need to update the /etc/hosts file. Here is an example:

127.0.1.1 subdomain.domain.tld subdomain
127.0.0.1 localhost
111.1.1.1 subdomain.domain.tld subdomain

If you see a warning at the top of your /etc/hosts file saying the changes won't persist, ignore it.

Now restart the hostname service:

service hostname restart

Configure Git for remote deployments

This is the part where I had the most trouble in my local Windows environment. Making sure Git was using my keys when pushing to the remote server.

  • Install Git for Windows or similar.
  • Check for a .ssh folder in your user directory. Create the directory if it doesn't exist.
  • Place your SSH keys in the .ssh folder with the following naming: keyid_rsa (private key) and keyid_rsa.pub (public key).
  • Create or edit the config file on the same folder with the following format:
Host host_ip_or_domain
 IdentityFile ~/.ssh/keyid_rsa
  • To avoid having to start the SSH agent each time you start Git Bash create a .bashrc file in your user home directory (script from Set up SSH for Git):
SSH_ENV=$HOME/.ssh/environment
  
# start the ssh-agent
function start_agent {
    echo "Initializing new SSH agent..."
    # spawn ssh-agent
    /usr/bin/ssh-agent | sed 's/^echo/#echo/' > "${SSH_ENV}"
    echo succeeded
    chmod 600 "${SSH_ENV}"
    . "${SSH_ENV}" > /dev/null
    /usr/bin/ssh-add
}
  
if [ -f "${SSH_ENV}" ]; then
     . "${SSH_ENV}" > /dev/null
  ps -ef | grep ${SSH_AGENT_PID} | grep ssh-agent$ > /dev/null || {
     start_agent;
 }
else
    start_agent;
fi
  • Open Git Bash.
  • Test your connection with the command:
ssh root@host_ip_or_domain

You should be connected to your server.

For additional instructions see:

How to deploy apps

To deploy/create a new app in Dokku you can do a remote push from a local Git repository.

Depending on the contents of your repository Dokku will install the necessary infrastructure (Apache, PHP, etc.) using buildpacks. More on this in the next article.

In your local environment, in the repository you want to push, define the remote location for Doku:

git remote add dokku dokku@host_ip_or_fqdn:app_name

If you use the FQDN as your app name (e.g. my-domain.tld) Dokku will configure the domain automatically.

Now push to the remote:

git push dokku master

You will see Dokku running a buildpack or failing to find one. Buildpacks will be explained in more detail in the next article.

Stuck on deployment

I have had a couple of instances where the build got stuck installing a package. I couldn't cancel it and when I tried to deploy it again I saw a message saying that a deployment was underway.

After trying to restart/rebuild the app several times, the solution that I found was to delete the .build.lock file that is found in the app folder under /home/dokku/app_name/.

Afterwards I could deploy again.

Conclusion

We have looked into installing Dokku, setting SSH and Git and deploying apps.

In the next article we will explain buildpacks in more details, deploy a static HTML site and see how to configure the app's domains.

Nuno Freitas
Posted by Nuno Freitas on December 9, 2015

Related articles