Setting up Dokku on Digital Ocean

In this tutorial, we will be creating a Dokku server using DigitalOcean's 1-Click App Marketplace.

Creating Your Dokku Droplet

If you do not have a DigitalOcean account already you can sign up for one at digitalocean.com. Alternatively you can sign up using this referral URL to get $100 in credit over the next 60 days (optional).

Once you have created an account and finished the onboarding you should be redirected to the dashboard. From here we will create a project by click the "+ New Project" button in the sidebar. Projects are DigitalOcean scheme of collecting and organizing related resources into a unified interface.

Figure: The sidebar of DigitalOcean

Follow the project creation steps in the prompt filling in whatever information you desire .

Figure: Step 1 in creating a new DigitalOcean project

Figure: Step 2 in creating a new DigitalOcean project

After creating a new project, the space will look pretty empty except for a large "Get Started with a Droplet" button. Let's click that to get started on creating our 1 Click App.

Figure: The view of an empty project after creation

You should be redirected to the Droplet builder where we need to specify configurations for our new server. Locate the tabs menu below the title "Choose an Image" and click the "Marketplace" option. Unfortunately, the "Recommend for You" does not show us the Dokku image so you'll have to click the "Select All Marketplace Apps" to load the directory of all the available apps.

Figure: Choosing an image for the Droplet

Find the Dokku app image by scrolling through or using the search bar. Once you find it click the tile to load the Dokku Image splash screen.

Figure: Dokku Droplet 1-Click App image splash screen

Click the "Create Dokku Droplet" button to select the Dokku image for your Droplet. You should be redirected back to the Droplet builder after selection.  Continue configuring the Droplet by scrolling to the "Choose a Plan" section and selecting "Starter" and $5/month option (it is all the way to the left on the plans section). This plan should be enough for MVP development purposes --- but allocate more resources if you please.

Figure: Choosing the $5/mo plan for the Droplet

With our plan in place, scroll to the "Authentication" section of Droplet builder, select the SSH Key option, and click the "New SSH" Key button.

Figure: Configuring authentication for the Droplet

We will need to create and add a new SSH key to our DigitalOcean account in order to access our resources. Generate an SSH key using the steps below (Mac OSX / Linux):

# In terminal

ssh-keygen

# Use id_your_domain
Enter file in which to save the key (/Users/USER/.ssh/id_rsa): ~/.ssh/id_your_domain

# Don't add a passphrase for now
Enter passphrase (empty for no passphrase): 
Enter same passphrase again:

# Mac OSX: Copy public key contents to pasteboard 
pbcopy < ~/.ssh/id_your_domain

# Linux:
# cat ~/.ssh/id_your_domain
# copy output to pasteboard manually

Figure: The SSH Key prompt for Droplet authentication

Once you have your public key contents paste them into the prompt and click the "Add SSH Key" button. DigitalOcean will add your SSH key to list of authorized_keys under ~/.ssh/authorized_keys when your Droplet is created. This will also be the SSH key our Deployer service will use to access the Dokku server. We should now be set to finish the builder by clicking the "Create Droplet" button at the bottom of the page.

Figure: Click Create Droplet to spin up your new Droplet

You should be redirected to your project page and see a progress bar indicating how long until your Droplet is ready. Go make yourself a drink, or just lay back and put our feet up while DigitalOcean chants the magic incantations into the cloud to allocate our Dokku server resources. Once your Droplet is ready, we have one additional configuration step to complete our Dokku server setup.

Figure: Our new Droplet created with an allocated IP address

Copy the newly minted IP address for your Droplet into your browser and you should see a form appear. The form is used to specify some configuration options for your Dokku server. Ignoring the Hostname input section for now., select the checkbox "Use virtual host naming for apps". This option will make Dokku create subdomains for each application deployed to the server. In other words, each app we deploy to the Dokku server will have their own URL like your-app.domain.com  - cool huh?

Figure: Configuring your Dokku Droplet for the first time - be sure to enable virtual hosts!

Click "Finish Setup" once you have double checked all settings are correct. Once finished, Dokku will complete your server set up, and you can try to SSHing into your Droplet.

ssh root@<DROPLET-IP-ADDRESS>

If everything has worked, you will have a root console at your fingertips.

Setting Up Dokku DNS

To be able to run the system end to end you will need to purchase a domain name for your Dokku server. You do this easily and inexpensively through any domain name registrar such as Google Domains, Host Gator, Go Daddy, etc.

The domain can be anything you want, feel free to use an inexpensive TLD like .xyz, .club or .info most registrars provide a way to search for these types of domains. If you are a student you can sign up for GitHub's Student Education pack and receive a Namecheap domain. If you are an educator you can sign up for the GitHub Educator's Toolbox and receive promotions for free domains.

I'll be using yourdomain.com domain for demonstration purposes. Once you have a domain name follow the Digital Ocean quickstart guide to add your domain name to your account using the free DNS tools. When you get to the "Create new record" step, you will need to add two A records as shown in the table below.

A Record Name Directs To TTL Value
@ Your Dokku Droplet 3600
* Your Dokku Droplet 3600

Recall that an A Record (A standing for Address) is a concept in DNS where a record maps a domain to an IPv4 address of a computer hosting the domain. An A Record is composed of a name, usually called the "subdomain", and a TTL (Time To Live) value which is the length of time to cache for a resolver. If you wanted to create a subdomain such as app-name.yourdomain.com you would need to create an A Record with the name "app-name" and a TTL value (usually 3600) in your DNS provider. So what's with the "@" and wildcard (*) A records we created? Glad you asked!

The "@" A Record maps the root or "no subdomain" domain, i.e yourdomain.com, to our Dokku Droplet. The second wildcard (*) A Record maps any valid url pattern as a subdomain (i.e. app-name.yourdomain.com, app-name.yourdomain.com, app-name.yourdomain.com, etc) to our Droplet.

Figure: Adding a new domain to DigitalOcean DNS tools

Figure: DigitalOcean DNS section after adding the A Records

With our A Records  created, the final step to finish off our DNS you will need to delegate your domain name by pointing it towards Digital Ocean's name servers. Digital Ocean provides a comprehensive guide for how to do this using several  major domain name providers.

With your domain name added to your account, delegated and pointing towards your Droplet, we need to make one small tweak to our Dokku server. SSH into your Dokku Droplet and change Dokku's global name setting. Depending on how quickly the name server propagates changes you might be able to use your domain name, but, if that fails use your Droplet's IP address to SSH into the server:

# This would be your domain or Droplet IP address
ssh root@yourdomain.com

If you get a "public key denied" error try to add your SSH key again by using:

# or whatever you named your SSH key
ssh-add ~/.ssh/id_your_domain

With console access to the Dokku server, we are going to clear, and add our new domain:

dokku domains:clear-global 

# Use your domain instead of "yourdomain.com"
dokku domains:add-global yourdomain.com
dokku domains:report --global

The dokku domains:report ---global command should display results similar to the ones below

=====> Global domains information
       Domains global enabled:        true
       Domains global vhosts:         [yourdomain.com](http://yourdomain.com)

Awesome, we have successfully hooked up a domain name to our Droplet. In the next section we will test out a deployment to Dokku to verify things are working as expected!

A Test Deployment

Let's do a test deployment to our Dokku server to confirm things are working correctly. First we will need to SSH into in the server and create our application:

# Use your domain or IP
ssh root@your_domain.com

# With dokku server console
dokku apps:create ruby-getting-started

# ------> Creating ruby-getting-started... done

# Exit the Dokku server
exit

Once your app is created, clone the ruby-getting-started repository and cd into it.

git clone https://github.com/heroku/ruby-getting-started
cd ruby-getting-started

Dokku enables git deployments via git push by using build packs (or Dockerfiles where desired). . To see this in action, let's add a remote to the ruby-getting-started repository perform a git deployment. Note: the name of the user must be dokku and the host is your host name.

git remote add dokku dokku@yourdomain.com:ruby-getting-started
git push dokku master
#... output
# ------> Cleaning up...
# ------> Building ruby-getting-started from herokuish...
# ------> Setting config vars
       CURL_CONNECT_TIMEOUT:  90
#... more output
=====> Application deployed:
       <http://ruby-getting-started.yourdomain.com>

Using your browser navigate to the URL provided at the end of the deployment http://ruby-getting-started.yourdomain.com and you should see the ruby-getting-started page and the lovable Bootstrap styling that goes with it.

Figure: ruby-getting-started page

Looks great, and we've validated our Dokku server is up and running! The last step here is to tragically delete our new app as we will no longer need it. All we need to do is SSH back into the server and run the destroy command:

# Remember to use your domain / ip
ssh root@yourdomain.com

# With dokku server console - list the apps available
dokku apps:list

# =====> My Apps 
# ruby-getting-started

# the --force prevents dokku from prompting us to confirm the name again
dokku apps:destroy ruby-getting-started --force

# Check the apps again
dokku apps:list

# =====> My Apps 
# None!

Nice! We've reached the end of this section and our Dokku server is ready for service. No changes to commit here as our server is running on DigitalOcean's cloud.

Using Dokku Without a VPC

You can set up Dokku locally without using a cloud hosting company like DigitalOcean. However, it's a bit trickier and you can get things working locally by using a combination of Vagrant, DNSMasq, VirtualBox and tuning some system parameters. The essential idea being to use DNSMasq to map a dokku.me domain name to your Dokku Vagrant machine running locally. This will allow you to push to deploy from the host machine into a Dokku server running as a virtualized guest machine. Just be aware that you will treading into different waters if you take this direction.

Helpful Links

Playing With Dokku on Vagrant - Alexander Beletsky
Using Dnsmasq for local development on OS X - Thomas Sutton
Vagrant DNS
Vagrant Land Rush
DNSmasq for custom development domain name - Jan Grzegoroswki