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 mysitethen 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:
The Procfile tells Dokku what command to run to start your application server.
web: uwsgi --http :$PORT --module <myproject>.wsgi --master --offload-threads 1
web: must be a valid Linux command that can run inside of the application container.
Make sure you specify your project's WSGI module and that it's configured correctly.
Generate it with the following command.
$ pip freeze > requirements.txt
It's possible this article is outdated, so please check the list. Usually you want one that starts with
2. Configure the server
Shell into the server, and create a Dokku app.
$ dokku apps:create <mysite>
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
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>
$ 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
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.
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
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.
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.
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"?
- Your app container is not linked to a postgres database, or
- You have not properly configured
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
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 firstname.lastname@example.org
This article is licensed under CC-BY-SA 4.0. Please attribute "Candlewaster".