Deploying a Django App on Dokku

by Michael Herman on Jul 24, 2013.

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

What is Dokku?

A few days ago I was pointed towards the project Dokku. Dokku 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 money, it's hosted in the cloud and you may not want your application to leave the room just yet, it doesn't support websockets or long-polling, 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 recently hacked Dokku together in less than 100 lines of bash code.

Dokku ties Docker together with Gitrecieve and Buildstep into one package that is easily deployed, forked/hacked, and updated. 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 13.04 x64
  • SSH Capabilities, and
  • Jeff suggests having a domain name on hand so it's easy to point to your apps.

First, I signed up for an account on DigitalOcean. Next thing I did was add my publickey 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 13.04 x64" as your image. I initially picked the x32 version and Dokku wouldn't install (see Add your ssh publickey to the droplet so you can ssh into the machine without having to enter a password every time you log in. DigitalOcean 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 steps four in DigitalOcean'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 bash

Please note: Make sure you use sudo regardless of whether you are logged in as the Admin or not. For more info, see the "Wrapping Up" section. Installation could take anywhere from two to five minutes

Be sure to upload a publickey for your user:

$ cat ~/.ssh/ | ssh root@[MACHINEADDRESS] "gitreceive upload-key [username]"

Log out of your host machine and from your local machine run the above command replacing [MACHINEADDRESS] with the IP address or the domain name of your host machine and [username] with the name you'd like to push to.

$ cat ~/.ssh/ | ssh "sudo gitreceive upload-key [username]"

Gitrecieve explains the above command on their github page:

"The username argument is just an arbitrary name associated with the key, mostly for use in your system for auth, etc."

For example, I used:

$ cat ~/.ssh/ | ssh root@ "sudo gitreceive upload-key dokku"

Finally, PUSH to:

$ git push [whatever_name_you_choose] master

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. This 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:

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

Now we have to add Dokku on our host machine as a git remote:

$ git remote add dokku git@[MACHINEADDRESS]:hellodjango
$ git push dokku master

Again replace [HOSTADDRESS] with the address or domain name of your host machine. Next, go and visit http://[HOSTADDRESS]:49155 and you should see the "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- | 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 bash

Dokku isn't quite as far along as Heroku is. As far as I could tell it doesn't have an analog to

$ heroku run python syncdb

This made it difficult to set up a Django Applicaiton with a database. I ended up using a hosted postgres db and having my application connect over the web. You can always manually configure the local DB on your machine outside of Django. Jeff recently added support for Dokku Plugins so hopefully we'll get some more Heroku-style command line options soon.

Dokku does allow you to configure environment variables seperately for each application.

Simply create/edit:


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 opensource as well so if you want to contribute make a pull request or open an issue on github.

Learn and Earn!

Sign up for great tutorials, guides, rants, raves and opportunities to earn more money!