How to run your own PaaS using Dokku on Ubuntu 16.04

Written by
Written on
Tutorial Category DevOps
Experience level Intermediate

Introduction

Dokku is a Bash-powered, self hosted, mini Heroku that uses Docker to host and sandbox your apps. It allows you to create an environment that can run your web application with just a simple push from Git, dramatically simplifying your workflow, especially when it comes to showing work to other colleagues or clients. You don’t have to worry about configuring web, application or even database servers. Dokku does it all for you, that’s why I refer to it as a PaaS (Platform as a Service) solution.

Let’s see how to configure it on a DigitalOcean Ubuntu box. You could also run it on Amazon Web Services or Azure Cloud if you wanted to.


Prepare the server

Before you begin, it’d be a good idea to familiarise yourself with this basic Linux server setup guide. It’ll help you create a non root user (which is super important, especially in production), as well as securing your new server with a firewall.

Anyway, let’s get started. Log in with your new non-root administrative user.

$ ssh [email protected]

Replace 111.222.333.444 with your server’s IP address, and remember to use the name of your user if you chose something other than ubuntu.

Now, if your virtual machine has less than 1GB of RAM, I’d recommend setting up swap space so that Docker can build your projects properly.


Prepare your DNS entries (optional)

You have two options when you’re setting up your Dokku server:

  1. Host the Dokku server on the bare IP address, which will leave your App URLs looking like this:
    http://111.222.333.444:<app-port>
  2. Use Virtual Host naming on your Dokku server, which would give you the following URL format:
    http://<app-name>.my-domain-name.com

If you choose option one, you don’t need to do anything. Everything’s all ready to go. Skip to the next step!

If you choose option two however, you need to do a couple of extra things:

First, you’ll need to update your name servers to include a Wildcard DNS Record. This basically responds to non-existent subdomains and routes them to an IP address of your choosing, where Dokku will be waiting to service their requests.

If you’re using DigitalOcean DNS, your new record should look like the screenshot below:

In this instance, I’ve said “everything that goes to *.cloudtutorials.co should go to my Dokku instance”. So for example, example.cloudtutorials.co, would actually resolve to 46.101.8.47, which is the IP address assigned to my server.

Check with your Domain/DNS provider for specific instructions on how to do this on their platform. I’ve included links that relate to a couple of providers below:

Let me know in the comments if you are unsure of how to do this using your provider. Once you’ve done this, move on to Step Three!


Install Dokku

Now, you need to install Dokku. This is where it gets fun! And easy!

The kind people who make Dokku have made it very easy for beginners to get all the prerequisites installed and running. Switch back to your terminal window where you logged in during Step One.

Enter the following lines:

$ wget https://raw.githubusercontent.com/dokku/dokku/v0.8.0/bootstrap.sh
$ sudo DOKKU_TAG=v0.8.0 bash bootstrap.sh

Note: at the time of writing, the latest version of Dokku was 0.8.0. You will want to check the Dokku docs to make sure that you’re installing the correct version, as it is likely to have changed again by the time you come to read this.

Another note: it’s generally considered bad practice to blindly execute scripts that you download from the internet without understanding what they’re doing. Obviously, the people behind Dokku are reputable and are trustworthy, but I would invite you to read the script and begin to question what the commands you’re copying and pasting are actually doing.

Your terminal is going to fill up with a bunch of informational lines saying that things are downloading and installing. Now’s a good time to go and grab a coffee, as this whole process is going to take about ten minutes.


Enable Dokku

When everything is installed and you’re enjoying your coffee, it’s time to enable Dokku. Open your machine’s external IP address in your web browser. You should see a screen that looks like this:

If you used an SSH key like we suggested in the Ubuntu Server Basics tutorial, it should already be pre-filled in the “Public Key” box. If not, you’ll need to Generate an SSH key and paste the Public Key part in there. Github has a great guide when it comes to generating your first SSH key. It’s important that you fill this key out, as it’s your admin SSH key and you’ll use it to push apps up to your new server!

Now, if you chose option one in the Configure DNS step in this guide, leave the “Hostname” field as the IP address and click “Finish Setup”. You’re all done!

If you chose option two, you should enter the domain name that you set up your Wildcard DNS Record on. For example if your wildcard domain was *.cloudtutorials.co, you would enter cloudtutorials.co in this box. Click “Finish Setup”, you’re done!


Next Steps

Now you’ve installed Dokku on your server, I’d reccomend you have a look at the following sections of the Dokku documentation to get your sites uploaded and running:

  • Deploying an Application runs you through the steps required to get an example project running on your shiny new server
  • The Dokku plugin list shows you the currently supported plugins for Dokku that extend your installation. This is important for installing databases, queues, etc.

I will write another tutorial regarding application deployment to Dokku in more depth, but in the meantime, the Dokku docs have you covered.

Enjoy!


Talk to us!

If you’d like to discuss the content of this tutorial, visit our forum topic!

%d bloggers like this: