Divio Shell Required

Adding a new application to your Divio Cloud project - the quick and easy way describes the simplest way to deploy a custom application on an Divio Cloud site.

However, as noted in that article, it does have some limitations: you can't share the application with other projects or users.

In this article we'll go through a workflow that's more complex, but produces an easily re-usable Addon by creating a package that you upload to Divio Cloud.

We'll go through the steps for a hypothetical application called Django Example. Substitute the name of your actual application where appropriate. 

Create a new custom Addon on divio.com

Go to your own Addons list, and hit Add custom Addon. You'll need to provide some information about the new Addon, for example:

  • Name: Django Example 
  • Package name: django-example 
  • Licence: Select a licence from the list, or leave it blank if you want to provide your own
  • Organisation: Select the organisation you want the Addon to belong to, or leave it blank if you want it to belong to you personally.

The Divio Cloud now has some basic information about the Addon you're going to upload.

You'll see that your Addon has a Package information menu. This lists a number of files that you will need to download to use locally to create the Addon package:

  • addon.json 
  • setup.py
  • MANIFEST.in 
  • LICENSE
  • README.rst 
  • django_example/__init__.py 

We'll make use of them in a moment.

Set up a project for your development work

You'll need a Divio Cloud project to work in, running locally. Set up one of your Divio Cloud projects locally, using the Divio app. Check that your project runs locally as expected.

Create the Addon package

Work in addons-dev

In this local project, we'll use the addons-dev directory (which you will find in your project) for developing the addon. For convenience, anything in addons-dev gets added automatically to the Python path (so it will be importable by your project).

Create the package directory 

The next step depends on the application you want to make available as an addon. There are two different approaches you can adopt:

  • If the application is installable via pip, all the package needs to do is list it as a dependency, and optionally configure it. This is most suitable for a publicly-available reusuable application. In this case we will build a brand new package as our addon, so create a new directory in addons-dev  called django-example.
  • If the application is not installable via pip, the package you upload also needs to include the application code, install it, and optionally configure it. This is most suitable for a private application of your own. In this case the package we create will be based on the existing application, so copy your application package to addons-dev.

A note on Python package structure

A Python package typically includes one or more modules, and the structure looks like this:

django-example/      # the package directory
    setup.py    
    ...              # and other packaging files
    django_example/  # the module or application directory
        __init.py__  
        ...          # files containing actual application code files

Your Addon is going to have the same structure. 

If you are working with an existing application and doesn't already have a package directory, now is the time to create it, and put your application inside it! (Note the package django-example, with a hyphen, and the module django_example, with an underscore.)

Set up the packaging files

Into your django-example package directory, add the following files (as supplied above, if your package doesn't already include them):

addon.json Contains a dictionary describing your package. The package-name must match your package directory's name, of course. The installed-apps list must contain the names of any Django applications that the package includes (including any dependencies it also installs). They will ultimately be included in the site's INSTALLED_APPS setting.

setup.py Contains key installation information. If your Addon needs to install any dependencies (which it definitely will if its purpose is to install a reusable application via pip) then they must be listed in the install_requires argument of setup().

MANIFEST.in Contains paths to static files that will be added.

LICENSE The licence for the application. Note that this is the licence for the Addon application itself. If your Addon installs other applications, they have their own licences, which you don't need to mention.

README.rst A description, again of the Addon application itself, not of any application that it will install as a dependency.

django_example/__init__.py Unlike all the other files, this one needs to go into the module  directory. An existing application will have one already, which is fine, as long as it provides a valid version number, such as: __version__ = "0.0.1". For your own sanity, if the principal purpose of your Addon is to install some other application, have its version number track that of the other application, adding a further decimal to manage multiple versions of your Addon.

Advanced configuration

The addon.json contains the minimum required configuration for an application. However, the application may need much more configuration, including:

  • settings
  • insertion of its URL patterns into the project
  • complex logic-dependent configuration based on user-supplied data
  • ... and more.

This is all achieved via the optional aldryn_config.py file. Please see Addon configuration for developers for more details of this.

Test your Addon package

You're now in a position to check that the Addon actually works. For the first test, we will do some manual configuration.

INSTALLED_APPS

 For a quick test, make sure that the items in its installed-apps list are added to the project's settings.py:

INSTALLED_APPS.extend([
    # add your project specific apps here
    'home',
])

URL patterns

Your application may also require that its URL patterns are included into the projects. The project's urls.py shows you where to insert them:

urlpatterns = [
    # add your own patterns here
    ] + aldryn_addons.urls.patterns() + i18n_patterns(
    # add your own i18n patterns here
    *aldryn_addons.urls.i18n_patterns()  # MUST be the last entry!
)

Environment variables

Possibly your application requires some environment variables. You can provide these in the .env-local file in the project (note that this may be a hidden file on your system).

Run migrations

Then run migrations: docker-compose run --rm web python manage.py migrate  and run divio project up. Check that the project now includes whatever new functionality you expected to see.

Test your Python packaging

Run python setup.py sdist. This will process the setup.py and give you useful feedback about what it is doing. Check for any errors.

Test that your Addon builds correctly

Finally, you can check that your Addon not only runs and has been correctly packaged as a Python application, but that it has also been packaged correctly as a Divio Cloud Addon.

Rebuild the project

You should now remove any applications that you added to INSTALLED_APPS in the settings above, because a properly packaged Divio Cloud Addon will use the addon.json file to do the job behind the scenes. 

Similarly, remove any URL patterns you added manually. 

Run divio project develop django-example. This will rebuild your project, running the routines that will install the new Addon and its dependencies in the project.

Test it once more with divio project up.

Run the validation check

Check that the addon.json is valid:

$ divio addon validate
Addon is valid!

You're finally ready to upload the Addon to the Divio Cloud

Upload the Addon

Run:

divio addon upload

to upload it.

If you visit your Addon's page once more in the Control Panel, you'll see that it shows a new version of it on the site.

Versions

Addons exist in versions, which can be assigned to different Release channels. This allows different projects not just to use different versions of the Addon, but to receive updates only to versions in the release channels they subscribe to.

Install the Addon in the Cloud

In a project in the Control Panel, select Manage Addons. You'll see a list of all available Addons, including the one you've just uploaded.

Select Install, then redeploy your project, and enjoy your new software in the cloud. Your application is now an Divio Addon.

You can install your Addon in any project. If you opt to share the Addon more widely, or publish it on the Marketplace, other people will also have access to your Addon for their own projects.

Did this answer your question?