Working with Django addons (legacy)


Aldryn continues to be supported by Divio, but we do not recommend using Aldryn Django for new applications.

In Django projects, settings are handled via the settings module (usually, the file).

In Aldryn addons - those that include an file - many of these settings will be automatically managed by the addon itself. This takes place in

All key settings (i.e. settings required for the package to function correctly) as well as many optional settings will be configured. They are then applied to the settings module via the lines:

import aldryn_addons.settings

From this point in the settings module, those settings that were automatically configured by the addon will be available in the file.

For example, in a Django project, you will find a file:


This files adds items to the INSTALLED_APPS, MIDDLEWARE, and applies other settings.

These settings can be controlled and determined in a number of different ways.

Via addon settings in the Control Panel

An addon can expose options for configuration in the Control Panel interface. For example, Aldryn Django has a Remove URL language prefix for default language option. This will apply to all environments of the project.

The value is stored in JSON. You can find the JSON file in the project locally, for example addons/aldryn-django/settings.json.

Via environment variables

Environment variables are suitable for:

  • environment-specific settings (e.g. database settings, since each environment should have its own)

  • secret settings (e.g. keys for services and APIs)

Environment variables are better than the codebase for such settings. If committed as part of the codebase, they provide the same value in all environments, and they are vulnerable to being accidentally shared.

Via automatically applied environment variables

Some environment variables are provided automatically, and you don’t need to do anything about them at all.

Each project environment has its own variables provided for services such as the database (DEFAULT_DATABASE_DSN), media storage (DEFAULT_STORAGE_DSN) and so on. Locally, the variables are saved in the .env-local file and loaded into the environment via docker compose.

Via user-configured environment variables

Other environment variables can be provided by the user, via the Control Panel’s Env Variables view:

'Adding an environment variable'

If you need the variable in the local development environment as well, add (for example):

SECRET_API_KEY = "aaPfaH1oJ5pdqYBc"

to its .env-local.

Manually in

As mentioned above, all these settings will be applied to the settings file by the aldryn_addons.settings.load(locals()) function. If any of them were written into the file manually before this point, it will overwrite them. Any settings you wish to provide manually should be added after the function to avoid this.

Overwriting automatically-configured settings

Overwriting automatically-configured settings is almost always a bad idea. For example, multiple addons may have added their own requirements to the MIDDLEWARE setting. If you simply do:


you will obliterate the automatic configuration (or if you place your setting before aldryn_addons.settings.load(locals()), your own setting will be overwritten).

If for example you need to specify additional middleware, the safer and more sophisticated way to do it is by manipulating the list (see How to configure Django settings in Aldryn projects).

To understand which settings are provided automatically, you can:

You can list changed settings to see those that have been altered from Django’s own defaults.

Anatomy of a Divio addon


Aldryn continues to be supported by Divio, but we do not recommend using Aldryn Django for new applications.

Basic file structure

For an addon “Susan Example Application”:


All addons have an file that takes care of settings, which are then loaded into

This means that any settings you need to apply in a project can’t simply be applied in your if an addon also needs access to them.

For example, nearly every addon will add a package, or sometimes several, to INSTALLED_APPS. If you were to assign do INSTALLED_APPS = [...] in the usual way, you would overwrite the existing assignments and break the project. That’s why our uses:

    # add your project specific apps here

The same goes for middleware, and other settings. is loaded into the Django project at runtime, so any changes are picked up when and reloaded automatically when developing. is an ideal place to check for environment variables that should be converted into Django settings.

See Addon configuration with


A metadata file.

    "package-name": "susan-example-application",
    "installed-apps": [
} will be generated by the Control Panel on the basis of the information you provided when you first created it there. The lines highlighted below are those that will be specific to your addon:

# -*- coding: utf-8 -*-
from setuptools import setup, find_packages
from susan_example_application import __version__

    platforms=['OS Independent'],

Django addons and templates

Templates at the project level will override templates at the application level if they are on similar paths. This is standard Django behaviour, allowing application developers to provide templates that can easily be customised.

On initial project creation

For your convenience, when you first create a project, any templates in addons are copied to the project level so you have them right at hand (if the addon’s package name and inner application name match.)

For example, templates from Aldryn News & Blog will be copied to templates/aldryn_newsblog/ in your project.

If a template does not exist in the project’s templates directory, Django will simply fall back to the one in the addon itself.

Subsequent addon updates

After templates have been copied to the project’s templates directory, they will not be copied again, so as not to overwrite any changes the project developer may have made. However, this does mean that if an addon is subsequently updated and its templates change, those changes will not appear in your project.

In this case:

  • if you have made changes to the templates in your project, you will need to obtain any updated templates and merge them with your own versions

  • if you have not made any changes, you can simply delete your local versions and Django will use the updated application templates.