Wagtail CMS Multi-Site Setup Guide

I have set up Wagtail CMS Multi-site and I wanted to document what I have done so far, just in case I decide to do this again.

I set up a new installation and added it to GitHub. I used ChatGPT to help me write code when I knew it would save me time and to help me start the process.

ChatGPT Prompt:

“You are an expert Django and Wagtail CMS Multi-site tutor specialised in teaching the basics of creating Wagtail Multi-sites, focusing on set up and development procedures, databases, and data structures. You provide clear, concise explanations and practical examples, using images and/or code to illustrate complex concepts. You are beginner-friendly, maintaining a conversational and simplified tone. Write a full essay of 2,000 words or more on how to set up a wagtail multi-site project. Give exact step by step procedure.”

Despite asking for step by step instructions a couple of major things were missed that I picked up on later but this was a good way to start.

Edited Prompt:

Now that this is complete this is what I would have added to my original prompt for more accuracy:

I am using Windows 11

Although I have been using ChatPGT for months now and it knows that based on the number of questions I have asked!

Quick Side Track

As well as Wagtail multi-site there is an opportunity to use Django multi-tenant. As this is a project created for me to host all my websites in one place I went with multi-site.

Getting Started

Setting Up the Environment

I was given a list of the necessary tools to get started:

  • Python: Ensure Python 3.8+ is installed.
  • Pip: Python’s package installer.
  • Virtualenv: To create isolated Python environments.
  • PostgreSQL: Recommended database for Wagtail.

As I have Windows I use my command line prompt (CMD) to complete setup. I set up a virtual environment, install Wagtail, start a project, make migrations then set up a super user.

Once complete I open the project in Visual Studio Code to get started.

Install Virtualenv:

Here’s the complete list. Add the command:

pip install virtualenv

mkdir <project_name> - e.g. 'packages'
cd packages

virtualenv venv

venv\Scripts\activate

Start with pip install virtualenv, then make a new directory using mkdir and give your project a name. I will use the name packages to use as an example.

Next change directories (cd) so you are in that folder e.g. cd packages

Once in the packages folder type virtualenv venv – venv is the industry standard name given to virtual environments but you can call it anything you want. Sometimes I just use env.

Finally, activate the virtual environment using venv\Scripts\activate.

Activation error

The very first error from ChatGPT was the instructions to activate the virtual environment. I didn’t specify in my prompt that I was using Windows 11, which I should have so it gave me source venv/bin/activate – which caused an error. Luckily, I have set up environments before so I knew what was needed.

The image below shows the virtual environment setup.

windows virtual environment setup

you will know you are in your virtual environment because you will see the name you gave it in brackets (venv)

Once you log into visual studio code you can then activate your virtual environment in there before you start work. The image below is me activating the multi-site I eventually set up:

I have set up Wagtail CMS, Django and virtual environments a few times now so the next part is all me 🙂

I tend to stick to the same routine.

Install Wagtail CMS

pip install wagtail

A simple instruction added to the cmd that installs the latest version of Wagtail CMS. You can install an older version if you want to by specifying the version e.g. pip install wagtail==5.1.0

Create a Project

Now create a new project inside the project folder. As I called my original folder packages I will call my project that too. I tend to call my project whatever I have called my folder. That’s just me. You can name the project whatever you like.

The instruction is

wagtail start <project name>
install wagtail cms using wagtail start then project name

Migrate the project

So now I have Wagtail CMS installed and a new project I activate/set up a new database for my project by running the instruction:

python manage.py migrate
migrate wagtail cms using python manage.py migrate

Wagtail CMS is now LIVE!

You can use the command

python manage.py runserver

to visit the new site. I always do just to check it is there.

When you click on the link: 127.0.0.1:8000 you will see your brand new site

You won’t be able to log in though until you create your first user known as a superuser.

Use CTRL-C to break the connection and continue…

Create a Super User

Next you will need to create the main administrator of the site called a super user:

python manage.py createsuperuser

First add a username – I used admin here in this example but I never use admin. I always come up with a proper username. Then add an email address and password.

NOTE: The cursor does not move as you type your password!

Update Settings

At this point I open Visual Studio Code, activate my virtual environment and make some changes to the settings file.

activate venv

Django just has one file called settings.py but wagtail has three separate ones and the main one is base.py

wagtail cms settings base.py

Open base.py and add the following (I add them at the top but some people prefer to add anything new to the bottom)

DEFAULT_AUTO_FIELD = 'django.db.models.BigAutoField'


SITE_ID = 1


ALLOWED_HOSTS = ['localhost', 'site1.localhost', 'site2.localhost', 'site3.localhost', 'site4.localhost']

Default Auto Field

Configure the DEFAULT_AUTO_FIELD setting in your Django settings file (BASE.py) to specify the default primary key type for all models. It is considered  good practice to specify the primary key type explicitly to avoid any potential issues in the future.

DEFAULT_AUTO_FIELD = ‘django.db.models.BigAutoField’

Site ID

“The SITE_ID setting specifies the database ID of the Site object associated with that particular settings file.” – taken from the Django Documentation.

Allowed Hosts

Sometimes your browser may throw an error and not let you see the site. It will let you know you need to add the site name to your settings. You need ALLOWED_HOSTS for that reason. Start with localhost and once you set your sites up add them as well.

Include Wagtail Contrib Settings

ChatGPT did not include this in the instructions. In fact all it said was install wagtail and log in. No other instructions. Luckily for me I figured it out after hours of research and video watching.

"wagtail.contrib.settings",

You need to add this to your INSTALLED APPS section

The 'wagtail.contrib.settings', module is an optional Wagtail package that provides an interface for managing site-specific settings directly from the Wagtail admin.

This is useful in a multisite setup where different sites might need distinct configurations. This includes configurations like social media links, analytics codes, or any custom settings that might vary between sites.

I did update the quotes to be double like the others later…

wagtail contrib settings

Add Django Contrib Sites

Another important item you need in your settings file. ChatGPT missed it out and when I told it this is what it said

You’re right; including 'django.contrib.sites' in your INSTALLED_APPS is crucial for managing multiple sites in Django and Wagtail. The django.contrib.sites framework is an essential part of Django’s site management, especially in a multisite setup, as it allows you to associate objects (like models and settings) with specific sites.

Why 'django.contrib.sites' is Necessary

The django.contrib.sites framework helps you manage content for multiple sites from a single Django project. It provides the Site model, which stores domain names and site-specific settings.

Add it to your settings:

"django.contrib.sites",

Once you have saved the file you need to migrate the database.

Migrate Database: Run the migrations to create the necessary database tables for the Site model.

Including 'django.contrib.sites' in your INSTALLED_APPS is essential for effectively managing multiple sites within a single Django and Wagtail project. This framework allows you to differentiate content and settings between sites, making your multisite setup robust and manageable. Ensure that you have added this configuration to take full advantage of Wagtail’s multisite capabilities.

Wagtail Contrib Settings

Next include the 'wagtail.contrib.settings.context_processors.settings' context processor. It needs to be added under the TEMPLATES section in the base.py settings file.

wagtail contrib settings

This will make the custom Wagtail settings easily accessible in the templates. This context processor automatically adds the settings to the template context, so you can use them directly without needing to load them manually.

Amend URLS.py

I knew I needed to change the structure of the URLS based on the old multisite setup instructions I found from 2016 along with an article from Wagtail.

So I asked ChatGPT about it. The instructions it gave me where not what I expected. After some research I asked it about adding r’^’ to urls.

The r'^' in the URL patterns specifies that the string should be treated as a raw string, and the ^ indicates the beginning of the URL path. This is used to match and include specific sets of URL patterns based on the initial segments of the URL.

Yes, if you’re using Wagtail in a multisite setup, you would typically include these URL patterns in your main project’s URL configuration, regardless of whether you’re using a single-site or multisite configuration.

So, yes, you should include these URL patterns in your main project’s URL configuration, regardless of whether you’re using Wagtail in a single-site or multisite setup. This ensures that the Wagtail admin interface and document management system are accessible and functional across all sites within your Wagtail project.

Sure, let’s update the urls.py to include your existing URLs while ensuring the configurations needed for the multisite setup are properly incorporated.

ChatGPT missed out many of the instructions I needed. It also provided incorrect instructions on a number of occasions. This is why it is important to have some idea of what you are doing before accepting code.

What’s Next?

That is everything for this first stage. Wagtail CMS multi-site has been set up and the settings needed along with the correct urls structure has been added.

Next, I had to create my models by adding code to the models.py file and to the template. I only started with the homepage.

After that I logged into the admin area to create a few sites.

I will add that in another blog post.


Posted

in

by