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

Note: This article is a bit dated and slightly incomplete. If you're using cookiecutter-wagtail, redis, elasticsearch, and/or postgres it's still a great start, but if you just want to deploy a simple site you made with wagtail start mysite then check the new tutorial here.

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

Procfile

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.

requirements.txt

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

runtime.txt

The Python buildpack will default to Python 2 unless you have this. See the full list of supported runtimes and include the latest Python version for your project. For example:

python-3.7.0

It's possible this article is outdated, so please check the list. Usually you want one that starts with python-.

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 https://github.com/dokku/dokku-postgres.git 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/base.py. 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 https://github.com/dokku/dokku-elasticsearch.git elasticsearch
$ sudo dokku plugin:install https://github.com/dokku/dokku-redis.git 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.

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

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> \
  ALLOWED_HOSTS=mysite.example.com \
  DJANGO_SETTINGS_MODULE=mysite.settings.production \
  SECRET_KEY='GENERATE_ME'

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 manage.py migrate
$ dokku run <mysite> python manage.py createsuperuser

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

Now you can visit yoursite.com/admin 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.

Problems

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 alex@candlewaster.co

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