New Wagtail Course! 🥳 The Ultimate Wagtail Developers Course

Tutorial Wagtail Version: 2.x

How to Install Wagtail with Docker

In this article we're going to learn how to get a Wagtail website setup and running with Docker.

Installing Wagtail is SUPER easy. In about 7 lines of (actual) code you can get up and running. Those instructions are found directly on's website.

But that assumes you're using virtualenv or pipenv. For some developers we prefer to use Docker. And the setup is a bit trickier, but still quite easy.

Pipenv & Virtualenv
``` pip3 install wagtail wagtail start mysite cd mysite pip3 install -r requirements.txt python3 migrate python3 createsuperuser python3 runserver ```

Above is the exact install guide found on Wagtails website. But alas, it doesn't mention Docker. So let's dig into this a little bit in a step-by-step manner.

If you're not interested in installing Wagtail using Docker, this article is not for you and I'd suggest heading over to Wagtails Getting Started docs.

Installing with Docker

So this part is relatively simple. And it's honestly quite similar to the pipenv or virtualenv way of setting up a website, but this time the site is using Docker. A little later in this article I'll mention some of the benefits to using Docker instead of pipenv.

But first, let's get this site installed. Run the following code from your command line. Oh, this also assumes you have Docker installed. If your on Windows Home edition, I have bad news.. this might not work for you and you might need to use pipenv (but hopefully that changes in the future).

``` pip install wagtail wagtail start mysite cd mysite docker build -t mysite . docker run -p 8000:8000 mysite ```

The above code does the following:

  1. Installs wagtail on your system. So you'll need Python 3.5+ and pip installed already.
  2. Creates a boiler plate website with a bunch of Wagtail goodies already installed
  3. Change Directory into your new website
  4. Build the Docker Container
  5. Run the Docker Container

It's at this point most devs are thinking "WOW this is so complicated just to install a website." If you're thinking that, you're not wrong. It is a few more steps, but the benefits outweigh the few extra setup steps. I'll talk more about the benefits later in this article.

Next, we'll need to create a super user. In pipenv/virtualenv we activate the environment, and run python3 runserver

But because our website is inside a "Docker Container", we can't just run that. We need to first get inside the container to run commands. This is the equivalent of the pipenv shell command.

So run the following commands in your terminal:

``` docker container ls ```

That will create a list of all your running containers. This is like listing out all your activated pipenvs. Amongst the jibberish it spits out in your terminal, you'll find Container ID that looks like a hashed value similar to this: 3e2fdcbac6f7

Find that value in your terminal and copy it. That's the ID of the container we want to get into.

The run the following command in your terminal: (remember to replace my testing ID with your real Container ID)

docker exec -it 3e2fdcbac6f7 /bin/bash

If you had Docker running, the container was built, and everything went well.. You should now be inside your Docker Container. Your terminal colors probably changed, too.

Lastly, we need to make a new super user. This is straight Django at this point and has nothing to do with Docker. Create a new super user using the following command (this needs to run inside your Docker Container; it's a different environment from your local computer).

./ createsuperuser

Lastly, run your server. Again, this is just a django command. From inside your container, run this command:

./ runserver

And now open http://localhost:8000/ and VOILA you have Wagtail running inside a Docker Container. And to access your admin interface simply navigate your browser to http://localhost:8000/admin/.

Exiting Your Docker Container

Once you're inside of a Docker Container, you're basically inside a different operating system. And you'll want to exit that operating system and access your own operating system again. To do that, use cmd+d or ctrl+d to exit the container. That's it!

Benefits to Using Docker; Why Use Docker?

You are probably thinking, "Wow Kalob this is SO MUCH WORK just to get a website installed on my computer." To that I would argue it's only a lot of work because you're new to the process. There are several benefits to using Docker over Pipenv and Virtualenv. And there's one down side which I'll explain in the next section.

The benefits to containerizing (that's the term for putting your website inside of a Docker Container) are:

  • Every dev on your team is now using the exact same environment. No more "it works on my computer" issues.
  • You're one BIG step closer to having a copy of your production server on your computer. No more "it works locally but not on the server" issues.
  • With Dockerfiles you can easily upgrade Python. Using Python 3.5 but want 3.7? You can change that in a Dockerfile; it's a single line of code. In fact, you change ONE character (change the 5 to a 7), rebuild your container, and you're running the latest version of Python.
  • No more fighting with local dependencies. If you've ever worked with other Python devs sometimes we forget to add a requirement to the requirements.txt file. But because that dependency is already on the other developers computer, they don't get the error. But you will. And your server might. Docker Containers are basically virtualized operating systems; when you run a project with a missing package, you'll know about it as soon as you run the server. No more guessing.
  • You can experiment with everything. Worst case scenario you remove the Docker Container and rebuild it the way it was before. So if you're trying to work with the OS, for example using FFMpeg to transcode uploaded files and you install a few packages that break something. You can uninstall the packages in your container, OR tear down the container and rebuild it from scratch. No harm done.

There are other benefits, too, but this article is about installing Wagtail CMS using Docker, not why we should all be using Docker (but can we? ;)

The Downside to Using Docker

There is one really big downside to using Docker. Actually, it's not that big to be honest.

Docker Containers use a lot of hard drive space. Each project you use with Docker will create an image (not a picture), a volume and a container for your packages (pip packages). Docker tries to leverage caching so you don't need to have the exact same OS Image downloaded twice. But it's still a mini-version of an operating system so it takes space.

Personally, I have about 50 containers running about 12 different OS Images. It does eat up some space.

Luckily there's a command to clear out all the junk images, volumes and containers in case you need to free up some space.

docker system prune -a

That will free up a tonne of space. It's freed up over 80gb for me once. In my opinion, it's minor maintenance for the benefits and amount of time we'll save debugging issues from one computer to the next.

Related tutorials

How to Install Wagtail Using Pipenv (in less than 6 minutes)

Posted on

Lots of Python developers use Pipenv to setup projects and separate their dependencies from their local machine. In this video we'll install Wagtail from scratch. (Step by step instructions are inside

View lesson, How to Install Wagtail Using Pipenv (in less than 6 minutes)

How to Deploy Wagtail to Heroku

Posted on

Learn how to deploy a brand new Wagtail site to a free Heroku instance.

View lesson, How to Deploy Wagtail to Heroku

How to Subclass Wagtail Pages

Posted on

Subclassing is having a class (in this case it's a Wagtail Page) that can be used for other classes (Wagtail Page's). The parent class has all the common attributes for the child pages, and every child page will inherit everything from it's parent. In this lesson we'll explore that by creating a subclassed Article and Video Blog Page that share a common parent, and then we'll extend the functionality of both subclassed pages by adding new fields.

View lesson, How to Subclass Wagtail Pages

How to Paginate Your Wagtail Pages

Posted on

Pagination is the ability to click through "pages". You most commonly see this on a Blog Listing Page, where you have "page 1 of 4" for example. In this lesson we're going to use Django Paginator right out of the box to add pagination to our Wagtail Blog Listing Page. No 3rd party packages, no craziness, and minimal maintenance. Just beautiful Wagtail and Django working together in 11 lines of code in our Wagtail Page Pagination.

View lesson, How to Paginate Your Wagtail Pages

The Ultimate Wagtail Developers Course

This course covers everything from basic installation to advanced features like custom blocks and API integration, it's perfect for developers looking to enhance their skills with this powerful CMS.

Ultimate Wagtail Developers Course Logo