Deploying a Django App on Dokku

By Michael Herman

Guest post written by Michael Herman, hacker at and co-founder of Real Python, about deploying a Django app on Dokku.

Updated 11/5/2014: Updated Dokku installation and deployment instructions.

What is Dokku?

A few days ago I was pointed towards the project Dokku, which is a "Docker powered mini-Heroku" that you can deploy on your own server to serve as your own private PaaS.

Why would you want your own mini-Heroku?

Well Heroku can cost A Lot of money, it's hosted in the cloud and you may not want your application to leave the room just yet; you don't have 100% control over all aspects of the platform and/or maybe you're just the DIY kind of person. Regardless, Jeff Lindsay hacked Dokku together in less than 100 lines of bash code!

Dokku ties Docker together with Gitreceive and Buildstep into one package that is easy to deploy, fork/hack, and update. If you haven't checked out Docker yet, I recommend that you do so. Docker is "an open-source engine which automates the deployment of applications as highly portable, self-sufficient containers which are independent of hardware, language, framework, packaging system and hosting provider".

What You Need To Get Started

You could use anything from AWS to a computer on your own private network. I decided to use DigitalOcean as my cloud hosting service for this little project.

The requirements for hosting Dokku are simple:

  • Ubuntu 14.10 x64
  • SSH Capabilities

Digital Ocean has a pre-configured Droplet that you can use that's already provisioned for a Dokku environment. Feel free to use this. We'll using a fresh server so you can recreate this process on any server.

First, I signed up for an account on DigitalOcean. Next thing I did was add my public-key to my DigitalOcean account. You can follow steps one to three in this guide to help get you set up if you need to create a new key. Step four will come in handy later.

Next, I created my first "droplet" (spun up a node) by clicking "Create Droplet". Make sure you pick "Ubuntu 14.10 x64" as your image. I initially picked the x32 version and Dokku wouldn't install (see Add your ssh public-key to the droplet so you can ssh into the machine without having to enter a password every time you log in. Digital Ocean takes about a minute to spin up your machine.

After it's ready DigitalOcean will either email you saying so and include the machine's IP address in the email or the machine will appear under your droplets panel. Use the IP address to SSH into the machine and follow step four in Digital Ocean's ssh guide.

Installing Dokku

Now that our host is all set up it's time to install and configure Dokku. SSH back into your host machine and run the following command:

$ wget -qO- | sudo DOKKU_TAG=v0.2.3 bash

Please note: Make sure you use sudo regardless of whether you are logged in as the root or not. For more info, see the "Wrapping Up" section.

Installation could take anywhere from two to five minutes. Log out of your host machine when done.

Be sure to upload a public-key for the user using the following format:

$ cat ~/.ssh/ | ssh root@<machine-address> "sudo sshcommand acl-add dokku <your-app-name> "

Make sure to replace <machine-address> with the IP address or the domain name of your host machine and <your-app-name> with the name of your Django Project.

For example, I used:

$ cat ~/.ssh/ | ssh root@ "sudo sshcommand acl-add dokku hellodjango"

Deploying a Django Application to Dokku

Dokku uses Buildstep which uses Heroku buildpacks to build your applications. It comes with the Heroku Python Buildpack built in, which is enough to run a Django or Flask application off of. However if you'd like to add a custom buildpack you can.

I followed the Getting Started with Django on Heroku tutorial to get my initial Django application set up.

First I created a Django Project and added a local Git repo:

$ mkdir hellodjango && cd hellodjango
$ virtualenv venv
$ source venv/bin/activate
$ pip install django-toolbelt
$ startproject hellodjango .
$ echo "web: gunicorn hellodjango.wsgi" > Procfile
$ pip freeze > requirements.txt
$ echo "venv" > .gitignore
$ git init
$ git add .
$ git commit -m "First Commit HelloDjango"

We have to add Dokku on our host machine as a Git remote:

$ git remote add production dokku@<machine-address>:hellodjango

Now we can PUSH our code:

$ git push production master

Again replace <machine-address> with the address or domain name of your host machine. If all went well, you should see an application deployed message in your terminal:

=====> Application deployed:

Next, go and visit http://<machine-address>:49153 and you should see the familiar "Welcome to Django" page. Now you can work on your application locally and then push it to your own mini-heroku!.

Wrapping Up

Initially I installed Dokku without the 'sudo':

$ wget -qO- | DOKKU_TAG=v0.2.3 bash

When I tried to push to Dokku the python build pack would fail trying to download/build python. The solution to this was to uninstall Dokku and then reinstall it the right way, using sudo:

$ wget -qO- | sudo DOKKU_TAG=v0.2.3 bash

Unfortunately, Dokku isn't quite as far along as Heroku is.

For example, all commands need to run directly on the host server since Dokku does not have a client-side app like Heroku.

So, in order to run a command like this-

$ heroku run python syncdb

-you need to first SSH into the server. The easiest way to achieve this is to create a dokku command:

alias dokku="ssh -t root@<machine-address> dokku"

Now you can run the following command to sync the database:

$ dokku run hellodjango python syncdb

Dokku does allow you to configure environment variables separately for each application. Simply create/edit /home/git/APP_NAME/ENV and fill it with things like:

export DATABASE_URL=somethinghere

Dokku is still a young platform so hopefully it keeps growing and becoming more useful. It's open source as well so if you want to contribute make a pull request or open an issue on Github.

See More Posts About:

App Development

Posted by Michael Herman

LinkedIn Website