November 24, 2013

Beginner

How to Use the DigitalOcean Dokku Application

Tagged In: Ubuntu, Git, Dokku

An article from Dokku
Submitted by Jeff Lindsay

Introduction


Dokku makes it easy to deploy and manage web applications on your own server in a way that’s very similar to Heroku. Except on DigitalOcean, it’s faster, cheaper, and you have more control. Now DigitalOcean has a one-click application for creating a Dokku Droplet, making it even easier to have your own private application platform in a matter of minutes.

We’re going to show you how simple it is to get started with step-by-step instructions. By the end, you’ll have a Heroku-style application running on a DigitalOcean Droplet, deployed via Git, and a Dokku instance ready for more.

Before we get started, be sure you have a DigitalOcean account. If not, go ahead and sign up.

Step 1: Create a Dokku Droplet


In your DigitalOcean control panel, press the Create Droplet button, to be taken to the creation screen.

Droplet Hostname: The hostname identifies your Droplet. Feel free to call your hostname anything you like. I’m just going to call mine “dokku”.

Select Size: Depending on how many applications you’ll be deploying, you may want a larger size Droplet. However, for most purposes the 512MB size is enough to get started. You can always change it later.

Select Region: Choose the region closest to you, or the people that will be accessing your applications.

Select Image: This is the important part! Under 'Select Image' choose 'Applications' and then select 'Dokku on Ubuntu 13.04'.

DigitalOcean Dokku select image

Lastly, you will need to have an SSH key installed for Dokku to accept deployments via Git push. You can set up an SSH key for Dokku in a later step, but it’s easier to just pick one now for your Droplet. If you don’t have any SSH keys set up with DigitalOcean, here is a great tutorial.

Now click the 'Create Droplet' button, and we’ll wait while the Droplet boots up.

DigitalOcean Dokku creating droplet

Once your droplet is ready, you'll see a screen like this one:

DigitalOcean Dokku droplet ready

See the IP address on this screen? For the next step, you'll want to copy and paste that IP into your browser's address bar to load the Dokku setup page.

Step 2: Setting up Dokku


Browsing to the IP of your droplet, you should see a screen like this:

DigitalOcean Dokku setup page

Admin Access


If you used a DigitalOcean SSH key with your Droplet, it should already be filled in for your admin SSH public key. Anybody set up with this key can deploy and manage apps on your Dokku. You can add more later, but this one is for you. If there’s no key in that first box, you’ll have to create a keypair and paste in the public key. Remember, here’s a great article if you forgot how.

Hostname Configuration


Unfortunately, Dokku doesn’t know what domain you want to use for your apps. Without a domain, you have to access each app with a different port number like the example on the screen above. However, most people want their apps to run as subdomains of a custom domain. For example, myapp.progriumapps.com.

In order to have this setup, you need to do three things:

  1. Set up 2 DNS records for your domain that point to this IP

    a. First, a regular A record (progriumapps.com)
    b. Second, a wildcard A record (*.progriumapps.com)

  2. Change the Hostname field on the Dokku Setup screen to your domain

  3. Check the box that says Use virtualhost naming

For me, my Hostname Configuration now looks like this:

DigitalOcean Dokku hostname config

If you’re unsure how to achieve the DNS step, read this guide on how to set up a hostname with DigitalOcean.

That’s it! Click Finish Setup. If everything worked, it’ll take you to the Dokku README file on the next step which is to deploy an app.

Once you’re set up, the Dokku Setup page will no longer be available, so don’t worry if you don’t get anything when you browse to your IP again.

Step 3: Deploy an App!


Now for the fun part. Dokku supports many different languages and follows many standard application patterns. If you’ve never built an app that can run on Dokku, you can read documentation in our library about how to get your application to work with Dokku.

I’m going to deploy a sample application so that you can see how this works. Let’s go with a Node.js sample application. This is available on Github if you want to follow along with it.

After getting a fresh clone of this application using git, we need to add a git remote that points to the Dokku Droplet using the hostname we set up. If you were deploying your own app, you’d also add this remote. From the directory of your application on your computer, you’d run something like this:

git remote add dokku [email protected]:node-js-sample

If you weren’t able to set up a domain instead of an IP for the hostname, you’d use the IP instead of the domain. The name after the colon can be anything, but it will be the name used in the subdomain set it up with virtualhost naming.

Now we can deploy our app by pushing to the dokku remote. Be sure to include the branch:

git push dokku master

This should result in logs showing your app being built and deployed, finally resulting in a URL you can browse to and see that your application deployed successfully. Yay!

Next Steps


Despite being used by many people, Dokku is still quite an early project. You can read more about using Dokku on the README and soon there will be more in-depth documentation. Until then, there is a great community willing to help out if you run into problems. You can submit an issue on Github or join us in IRC on Freenode in the #dokku channel.

DigitalOcean is a perfect host for running Dokku, so hopefully you’ll enjoy playing around with Dokku and using it to manage and deploy your web applications.

Share this Tutorial

Vote on Hacker News

Try this tutorial on an SSD cloud server.

Includes 512MB RAM, 20GB SSD Disk, and 1TB Transfer for $5/mo! Learn more

Create an account or login:

20 Comments

Write Tutorial
  • Gravatar pabloacuna88 5 months

    nice!! works perfect

  • Gravatar j.tangelder 5 months

    Is it possible to deploy to an other hostname? So instead of creating an subdomain, to an other .com address

  • Gravatar Kamal Nasser 5 months

    @j.tangelder: I don't think that's possible with Dokku, try looking here: https://github.com/progrium/dokku

  • Gravatar Alexandru Badiu 5 months

    @j.tangelder: it's possible, I did it like this: $ git remote add progrium [email protected]:progrium.com $ git push progrium master

  • Gravatar peter.a.jaros 4 months

    Is there a recommended way to run `dokku` commands? Should I be SSHing in as root to run them? Creating a user just for login?

  • Gravatar peter.a.jaros 4 months

    Ah, got it: https://github.com/progrium/dokku#remote-commands

  • Gravatar mathieu.poussin 3 months

    Also, it looks like you must not do a system update/upgrade via apt-get update/upgrade/dist-upgrade, it fetch newer versions of the kernel and Docker but it break everything (git push fail after the upgrade).

  • Gravatar jellingwood 3 months

    @mathieu.poussin: We're in the process of getting an updated Dokku image up that should prevent those issues. We're doing some final testing, but the newest version of Dokku is looking very nice! It should be available shortly.

  • Gravatar jellingwood 2 months

    The Dokku image has been updated to version 0.2.1. Please try again if you were having trouble with the old image.

  • Gravatar Tom Maiaroto 27 days

    Oops, I didn't check the use virtualhost naming for apps checkbox...It would be nice to update the first screenshot to show it checked if it's important to do. Following step by step led to me missing that one. Good tutorial though, thanks.

  • Gravatar Tom Maiaroto 26 days

    Also strange, after putting in my SSH key and setting up...I can't push apps or load anything from the server. I can only SSH in. Nothing else seems to work. As if some necessary port is closed.

  • Gravatar alexwhittemore 25 days

    I just tried to deploy this droplet and as Tom reports, nothing seems to work right per the guide. I couldn't SSH in as dokku@ either, despite setting up my SSH key, so I logged in as root and had a look at /home/dokku/.ssh/authorized_keys - it was totally messed up, with quotes and environment variables and things as if the install script is broken. Even after fixing the authorized_keys so I can automatically log in, I still can't push heroku master, so I'm pretty sure this droplet needs some love and attention.

  • Gravatar andy 17 days

    When I `git push dokku master` I'm prompted for a password: `[email protected]'s password:` Not sure what to use here besides my DO root password which does not work here.

  • Gravatar gmaclennan 9 days

    Since Ubuntu 13.04 is End of Life and given Heartbleed, this droplet should not be using 13.04. Dokku recommends 12.04 for now whilst issues remain with docker and 13.10. This droplet and this tutorial should be updated. https://github.com/progrium/dokku/issues/441

  • Gravatar Kamal Nasser 8 days

    @gmaclennan: We'll have the Dokku image updated soon. (12.04)

  • Gravatar Devin Young 4 days

    @Kamal - Any word on when this will be updated? I plan to use the dokku image to set up a private cloud. I'm not keen on using Ubuntu 13.04; I generally prefer to use LTS versions on servers. I've considered setting up a barebones 12.04 image and manually installing dokku, but it's hard to pass up an image that is already set up for you.

  • Gravatar Andrew SB 4 days

    For the record, the Dokku on Ubuntu 13.04 droplet is carrying a patch to fix the Heartbleed issue. So while 13.04 has reached end of life, the image isn't vulnerable to that issue.

  • Gravatar berinle 2 days

    @astarr > So while 13.04 has reached end of life, the image isn't vulnerable to that issue. Says who? Even after running the recommended patching of openssl, when I run openssl version -a, it reports OpenSSL 1.0.1c 10 May 2012, which is in the affected range. So not unless I am missing something, the droplet is affected and needs an urgent patch!

  • Gravatar Andrew SB 2 days

    @berine On a freshly spun up dokku image:

    root@dokku:~# openssl version -a
    OpenSSL 1.0.1c 10 May 2012
    built on: Fri Apr 11 22:57:07 UTC 2014
    platform: debian-amd64
    options:  bn(64,64) rc4(16x,int) des(idx,cisc,16,int) blowfish(idx) 
    compiler: cc -fPIC -DOPENSSL_PIC -DZLIB -DOPENSSL_THREADS -D_REENTRANT -DDSO_DLFCN -DHAVE_DLFCN_H -m64 -DL_ENDIAN -DTERMIO -g -O2 -fstack-protector --param=ssp-buffer-size=4 -Wformat -Werror=format-security -D_FORTIFY_SOURCE=2 -Wl,-Bsymbolic-functions -Wl,-z,relro -Wa,--noexecstack -Wall -DOPENSSL_NO_TLS1_2_CLIENT -DOPENSSL_MAX_TLS1_2_CIPHER_LENGTH=50 -DOPENSSL_NO_HEARTBEATS -DMD32_REG_T=int -DOPENSSL_IA32_SSE2 -DOPENSSL_BN_ASM_MONT -DOPENSSL_BN_ASM_MONT5 -DOPENSSL_BN_ASM_GF2m -DSHA1_ASM -DSHA256_ASM -DSHA512_ASM -DMD5_ASM -DAES_ASM -DVPAES_ASM -DBSAES_ASM -DWHIRLPOOL_ASM -DGHASH_ASM
    OPENSSLDIR: "/usr/lib/ssl"
    
    Note that it was compiled without heartbeat support: "-DOPENSSL_NO_HEARTBEATS"

  • Gravatar berinle 2 days

    @astarr - thanks. I'll spin off a new image and migrate to that then. On my end, an instance which I created just 4 days ago reports a different build date and it is definitely compiled with headbeats enabled. OpenSSL 1.0.1c 10 May 2012 built on: Wed Jan 8 20:51:55 UTC 2014 platform: debian-amd64 options: bn(64,64) rc4(16x,int) des(idx,cisc,16,int) blowfish(idx) compiler: cc -fPIC -DOPENSSL_PIC -DZLIB -DOPENSSL_THREADS - D_REENTRANT -DDSO_DLFCN -DHAVE_DLFCN_H -m64 -DL_ENDIAN -DTERMIO -g -O2 -fstack-protector --param=ssp-buffer-size=4 -Wformat -Werror=format-security -D_FORTIFY_SOURCE=2 -Wl,-Bsymbolic-functions -Wl,-z,relro -Wa,--noexecstack -Wall -DOPENSSL_NO_TLS1_2_CLIENT -DOPENSSL_MAX_TLS1_2_CIPHER_LENGTH=50 -DMD32_REG_T=int -DOPENSSL_IA32_SSE2 -DOPENSSL_BN_ASM_MONT -DOPENSSL_BN_ASM_MONT5 -DOPENSSL_BN_ASM_GF2m -DSHA1_ASM -DSHA256_ASM -DSHA512_ASM -DMD5_ASM -DAES_ASM -DVPAES_ASM -DBSAES_ASM -DWHIRLPOOL_ASM -DGHASH_ASM OPENSSLDIR: "/usr/lib/ssl" Notice the build date of Jan 8, 2014? I was about to bite the bullet and drop down to 12.04 x64 and install dokku manually, since 13.0.4 is EOL anyway. It didn't seem that much of a painful experience. Got a 12.04x64 instance going in about 30mins top to bottom.

Leave a Comment

Create an account or login:
Ajax-loader