How to deploy a Wagtail site to Dokku

This tutorial assumes that you have a working Wagtail website and a working installation of Dokku.

You should also have a preliminary understanding of Wagtail and Dokku.

This tutorial is best suited for projects generated with wagtail-cookiecutter.

1. Add Dokku files to your project

You will need some files in your project to make it work properly on Dokku.

Important: Please use the wagtail-cookiecutter template to scaffold your Wagtail projects, and the majority of this will will be done for you.

All of these files should exist in the project's root directory:

  • Procfile
  • requirements.txt
  • runtime.txt


The Procfile tells Dokku what command to run to start your application server.

web: uwsgi --http :$PORT --module <myproject>.wsgi --master --offload-threads 1  

Everything after web: must be a valid Linux command that can run inside of the application container.

uWSGI and Gunicorn are both fine choices for application servers. We have chosen uWSGI here.

Make sure you specify your project's WSGI module and that it's configured correctly.


Dependencies for your project are listed in requirements.txt. Dokku needs this to install your project's dependencies, and it also triggers the Python buildpack with its presence.

Generate it with the following command.

$ pip freeze > requirements.txt


The Python buildpack will default to Python 2 unless you have this. It should only contain the desired Python version.


A list of all supported runtimes is available.

2. Configure the server

Shell into the server, and create a Dokku app.

$ dokku apps:create <mysite>

Install postgres

Install the postgres plugin if you don't already have it.

$ sudo dokku plugin:install postgres

Create a postgres database, then link it to your Wagtail app.

$ dokku postgres:create <mydb>
$ dokku postgres:link <mydb> <mysite>

Install Elasticsearch and Redis

You must either install these, or remove them from settings/ If you don't, the site will crash due to connection errors. You can remove the CACHES and WAGTAILSEARCH_BACKENDS settings to get rid of them.

To get started, install the necessary plugins.

$ sudo dokku plugin:install elasticsearch
$ sudo dokku plugin:install redis

Create the images.

$ dokku elasticsearch:create <mysearch>
$ dokku redis:create <mycache>

Link them.

$ dokku elasticsearch:link <mysearch> <mysite>
$ dokku redis:link <mycache> <mysite>

Set max upload size

By default, nginx only allows file uploads of 1MB or less. We can set this by creating a file inside of /home/dokku/<mysite>/nginx.conf.d/. Here I am setting the max upload size to 100MB, but feel free to set it as whatever you'd like.

$ echo 'client_max_body_size 100M;' > /home/dokku/<mysite>/nginx.conf.d/upload.conf
$ chown dokku:dokku /home/dokku/<mysite>/nginx.conf.d/upload.conf

That's it!

If all is well, it's now time to configure the app.

Configure your app

This section relies on your site settings being structured as they are in wagtail-cookiecutter.

$ dokku config:set <mysite> \ \
  DJANGO_SETTINGS_MODULE=mysite.settings.production \

It is imperative that you define these values, otherwise the site will not work.

  • ALLOWED_HOSTS - Set this to the domain name of the website. For multiple domain names, separate them with commas.
  • DJANGO_SETTINGS_MODULE - This is the name of the settings module used in production. It's in the form of a Python module name.
  • SECRET_KEY - Your site must have a unique secret key. You can generate one using tools found online.

Mount /media/

If you don't do this, all your file uploads will be lost every time the app restarts. We need to mount Wagtail's media directory somewhere on the host machine so it will be retained.

$ dokku storage:mount <mysite> /<mydatalocation>:/app/media

3. Deploy

It's time to deploy your project. From inside of your project directory, run:

$ git remote add dokku dokku@<mydomain>:<mysite>
$ git push dokku master

This will take some time, but your application should be successfully deployed at this step.

Migrate database

Shell back into the server. We need to initialize the database and create a super user.

$ dokku run <mysite> python migrate
$ dokku run <mysite> python createsuperuser

You will have to run python migrate after each deploy if new migrations have been made.

Now you can visit to log in and get started.

Hopefully this all worked for you. If so, congrats! You've deployed a Wagtail site to Dokku. If not, see below.


Here are some solutions to common problems.

Postgres wont connect

django.db.utils.OperationalError: could not connect to server: No such file or directory  
    Is the server running locally and accepting
    connections on Unix domain socket "/var/run/postgresql/.s.PGSQL.5432"?
  1. Your app container is not linked to a postgres database, or
  2. You have not properly configured DJANGO_SETTINGS_MODULE.

In the latter case, the app may be using your development settings instead of your production ones. This is especially difficult to catch when a dokku run command is failing, but the app itself connects fine due to the Procfile's specific settings module.

Can't upload files, 413 error

Make sure you set a client_max_body_size in your nginx.conf.sigil and that it's working, and that the files you're uploading don't exceed the value defined for it.

Blank white screen

Ensure that ALLOWED_HOSTS is in your app's environment and configured properly.

Errno 111, pages/images don't save properly

Make sure you've installed or deactivated Elasticsearch and Redis as described above.

Help! Something else

Please send an email to

This article is licensed under CC-BY-SA 4.0. Please attribute "Candlewaster".