Package an addon (installation)

This tutorial assumes your project uses Django 1.11

At the time of writing, version 1.11 is Django’s Long-Term Support release, and is guaranteed support until at least April 2020.

If you use a different version, you will need to modify some of the code examples and version numbers of packages mentioned.

So far we have added applications by adding a module into the project directory or installing via pip.

In each case, the applications had to be configured. However, this configuration can be automated, making it possible to create self-configuring applications, that take care of applying the necessary settings when they are added to a project - so you can install them without having to touch your at all.

This is done by providing an application with an file, in which the application will check the project and ensure that INSTALLED_APPS, and other key configuration settings are correct.

The Divio Cloud also allows applications to be installed into projects from the Control Panel, selecting the version to be installed and configuring the application - i.e. applying some settings - using a web form. This is also handled by the same file.

In this section of the tutorial, we’ll start packaging Django Debug Toolbar as a Divio Cloud addon, so that it can install itself into a project.


In the examples below, pay particular attention to the use of dashes - and underscores _ in the names of files and directories.

In Python naming conventions, a package name will use dashes, as in tutorial-django-debug-toolbar. The application name within the package will use underscores: tutorial_django_debug_toolbar.

This is significant, because although underscores are theoretically allowed in package names, various tools, including pip, will silently convert them to dashes, with predictably confusing results.

Register the addon

Before your addon can be uploaded, the Divio Cloud must be ready to receive it (just as GitHub requires you to create the repository on the platform before you can push a local repository)

Go to your addons in the Divio Control Panel and Add custom addon.

The Package Name field is the most important, and must be unique on the system. Call it <your name>-django-debug-toolbar.


From this point onwards for convenience we will refer to this as tutorial-django-debug-toolbar in examples - but you need to substitute <your name>-django-debug-toolbar, that you registered the addon with.

Every time you see “tutorial”, remember to use your own name instead.

The other fields:

<your name> Django Debug Toolbar
Select a license for your addon
You can leave this blank
'Add custom addon'

When you hit Create addon, the addon tutorial-django-debug-toolbar will be registered on the system. On the next page, supply a Description for the addon:

Tutorial Django Debug Toolbar

A Divio Cloud addon to install and configure Django Debug Toolbar into
Divio Cloud projects. Created as part of the Divio Cloud developer

and hit Save once more.

Add the packaging files

We need to work in the project’s addons-dev directory. Create a new tutorial-django-debug-toolbar directory in there.

Select Package Information from your addon’s menu. From here, you’ll be able to download system-created versions of the required packaging files. Of course you can also create them yourself, but this will save you the trouble.


In the current set-up, we install the Django Debug Toolbar package manually. We still want it to be installed, but we need the addon to take care of the installation for us instead.

Remove django-debug-toolbar==1.8 from

If you now rebuild the project and try to run it, you’ll get an error:

➜ docker-compose build web
Building web
Successfully built 9317b86c7745
➜ docker-compose up
web_1  | ImportError: No module named debug_toolbar

Instead, move the file you downloaded to tutorial-django-debug-toolbar to handle installation. You’ll need to make one change in it:

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

    author='Django Developer',
    platforms=['OS Independent'],


You’ll see from the that it expects to find a version number at tutorial_django_debug_toolbar.__version__:

from tutorial_django_debug_toolbar import __version__


Create a new directory inside the addon, named tutorial_django_debug_toolbar. Download and move the file provided by the Control Panel to the new directory.

By default it declares the version number as 0.0.1, but we recommend tracking the version number of the application that it installs (in this case, 1.8) so change it to:

__version__ = ""

(If you create another version of the addon to install django-debug-toolbar==1.8, that would be version For version 1.9, you’d start at and so on.)

Add README.rst

The setup() of expects to find a README file:


Download and add the README.rst file. If you haven’t already provided a Description via the Control Panel, it will be empty, otherwise, it will contain the description.

Build the project with the new addon

We’re now ready to build the project. Check that the addon file structure looks like this:


and run:

divio project develop tutorial-django-debug-toolbar
➜  divio project develop tutorial-django-debug-toolbar
Building web
The package tutorial-django-debug-toolbar has been added to your local development project!

See the divio project develop reference for more.

You can test that it works by starting the project again (docker-compose up).

Once divio project develop <addon> has been run, it doesn’t need to be executed again. From this point onward any changes you make to the addon, other than in its, can be picked up automatically, even while the project is still running.

Note that:

  • Adding new files may require you to restart the server.
  • Changes to will require running docker-compose build web.

We now have mechanism for a self-installing addon package. The next step is configuration.