Will McGugan: Serving a Customized Site with Moya

This SO post prompted me to think about how you would go about customizing a entire Django site (not just an app). Particularly if it is a third party project, still in development.

Forking the site repository is a solution, but the more customizations you make, the more awkward it becomes to merge upstream fixes and features. The problem is compounded if you have multiple deploys, with custom templates, assets, and settings.

I wanted to do a quick write-up of how this would be done in Moya, where customization is more of a first-class concept.

I'll briefly go over how you would serve a Moya site with a custom template, without modifying any of the original files. The project I'll be customizing is Moya Techblog which power this blog.

Install Moya

If you want to follow along, then first install Moya + dependencies and Techblog with the following:

pip install moya requests_oauthlib -U
git clone https://github.com/moyaproject/moya-techblog.git

Make a custom project

Next we want to create a new directory along side the Techblog checkout, which will contain two files; moya and settings.ini. The former is an empty file that tells Moya this is a project directory and the latter contains the following settings:

[customize]
location = ../moya-techblog/site

This settings file tells Moya to load the project from an alternative location. The [customize] section acts like a symbolic link of sorts, but there is more going on that that, which we will see below.

The directory structure should now resemble the following:

├── moya-techblog
│   ╰── LOTS OF FILES
╰── mysite
    ├── moya
    ╰── settings.ini

We can initialize and serve the custom site in usual way:

cd mysite
moya init
moya runserver

This will serve a basic Techblog site. If we want to customize a template from the original project, we can add it to mysite, and as long as it has the same path, Moya will load that file in preference to the original.

Replace a Template

The file we want to customize is templates/willmcgugan.techblog/base.html, which is the base template for the blog pages. We can copy that from the original to the same location within mysite, so our directory structure becomes:

├── moya-techblog
│   ╰── LOTS OF FILES
╰── mysite
    ├── moya
    ├── settings.ini
    ╰── templates
        ╰── willmcgugan.techblog
            ╰── base.html

Now we can edit base.html and the changes will be visible when we serve the project.

The same technique will work with any file from the project, including CSS, JS and even code. You can also add new files that don't exist in the original. For instance, if you have new assets, you can add them to the static folder and they will be served alongside the original files.

Any settings in settings.ini are merged with the equivalent file from the original project, allowing you to configure custom database details / file locations / smtp servers etc. See Building a Project for details.

If you are interested, the magic behind this is achieved with a virtual filesystem.