Divio Shell Required

In this how-to, we'll create a new Django application, integrate it a into project running locally, and then deploy it to the Divio Cloud. This is the quick and easy way to do it. It's suitable for adding an application to a project on a one-off or ad-hoc basis.

Set up the Divio Local environment

The Divio App application will configure your local environment, and help you launch your project locally. If you haven't already done so, use Divio App to set up your local development environment.

In the shell that Divio App opens for you, find your local project, and cd into it. You'll see a number of familiar files, and some that are specific to Divio Cloud:

ls -l
-rw-r--r--  Dockerfile
-rw-r--r--  Procfile
drwxr-xr-x  addons
drwxr-xr-x  addons-dev
-rw-r--r--  bower.json
-rw-r--r--  browserslist
-rw-r--r--  docker-compose.yml
-rw-r--r--  gulpfile.js
-rwxr-xr-x  manage.py
-rwxr-xr-x  migrate.sh
-rw-r--r--  package.json
drwxr-xr-x  private
-rw-r--r--  requirements.in
-rw-r--r--  settings.py
drwxr-xr-x  static
drwxr-xr-x  templates
drwxr-xr-x  tools
-rw-r--r--  urls.py
-rw-r--r--  wsgi.py

Begin working locally

See Set up and launch a Divio Cloud project locally.

You can launch a local project at any time by running divio project up in its directory. This also opens your web browser so you can interact with it.

Add the application to your project

Place the application inside the project directory, thus putting it on the Python path.

Tip: If your projects has many such applications that might get a bit messy. It is easy to add an extra directory (e.g. src ) to the PYTHONPATH

# <DOCKER_FROM>  # Warning: text inside the DOCKER_FROM tags is auto-generated. Manual changes will be overwritten.
FROM aldryn/base-project:3.1.0

# add the "src" folder to the PYTHONPATH

# <DOCKER_BUILD>  # Warning: text inside the DOCKER_BUILD tags is auto-generated. Manual changes will be overwritten.

# node modules

After this change the docker image will need to be rebuilt:docker-compose build web

docker-compose build web

As required:

  • add the application's name to settings.py
  • add any URL patterns that the application requires to the project's urls.py

Important: please note the comments inside these files that tell you where the safe places to add your own entries are.

 Note: If your application includes static files, these won't be available until you restart the server, by running Divio Cloud project stop followed by divio project up.

Run any migrations as required, with:

docker-compose run --rm web python manage.py migrate

Now visit the locally running site, and check that the application works as expected.

Push the changes to your cloud project

Your project is a Git repository. Run:

git status

to see the new and changed files. Use:

git add

to stage them, then:

git commit

to commit them to the repository. Finally,

git push origin develop

to push them to the cloud.

If you visit the Control Panel once more, you'll notice that it reports the project has undeployed commits. Redeploy the project in the Control Panel, and after a few minutes, your application will be running on the cloud-hosted site.

How to install external project dependencies

External project specific requirements can be added to requirements.in. It is very similar to requirements.txt, but is preprocessed with the pip-compile command from pip-tools.

Each dependency listed should be a pip-installable resource, for example:


Make sure to place custom dependencies outside of the


tags, since that part of the file is maintained automatically and is overwritten automatically with the requirements that were chosen in the UI.

For changes in this file to be picked up, rebuild the docker image:

docker-compose build web

Installing from version control systems

You can also install libraries from version control systems. You may be familiar with pip install -e in conjunction with a version control URL. For example:

pip install git+git@github.com:divio/django-cms.git#egg=django-cms

You can do the same with Divio Cloud projects, but note:

  • you need to use a publicly-accessible URL - for example, use https://github.com, not a URL that requires an SSL key, like git@github.com:divio/django-cms.git 
  • reference the zipped version of the package - for example, https://github.com/divio/django-cms/archive/release/3.4.x.zip for a particular branch, or https://github.com/divio/django-cms/archive/6fe8ff3682f79243e1186750249bfd3e3f997b4a/3.4.x.zip for a particular commit

Don't forget to add the egg argument.


This is a convenient way to add new custom functionality to an Divio Cloud project. However, it's not the only way to do it, and while it's quick, it's not necessarily the best way.

The application you have added remains part of this project only, whereas you might well wish to make it available to other projects.

Also, only a reasonably experienced developer can be expected to use this method to add an application to a project - whereas other users of the system might wish to be able to add applications to a project.

To make an application easily available in other projects, you'll need to set it up as an Divio Addon.

See also

How to add, configure and share custom Divio Addons

Did this answer your question?