How to deploy a Django application with our quickstart repository

The Django Divio quickstart repository is a template that gives you the fastest possible way of launching a new Django project on Divio.

It uses a completely standard Django project as created by the Django startproject management command.

The only additions are a few lines of glue code in to handle configuration using environment variables, plus some additional files to take care of the Docker set-up.

Clone the repository


git clone

The project contains a module named quickstart, containing and other project-level configuration.

Renaming the quickstart project module (optional)

If you’d like this to be named something else, now is the time to change the directory name, along with the references to the quickstart module wherever it appears, which is in:

  • Dockerfile





Using MySQL or an alternative gateway server

By default, the project uses Postgres and uWSGI, but MySQL and other gateway server options are available.

You’ll need to change a few lines of configuration to achieve this across a few files. See the notes for each:

Run the project locally

This section assumes that you have Docker and the Divio CLI installed. You also need an account on Divio, and your account needs your SSH public key. See How to set up the Divio local development environment if required.

Build the Docker image


docker-compose build

Run database migrations and create a superuser

docker-compose run web python migrate

(Note that due to Docker behaviour, you may get an error the first time you run this - Docker can sometimes be too slow to start up the database in time. If this happens, simply run the command again.)


docker-compose run web python createsuperuser

Launch the local server

docker-compose up

Try accessing the site at (this will only work if a URL has been wired up to /).

The Django admin is available at

You now have a working, running project ready for further development. All the commands you might normally execute in development need to be run inside the Docker container - prefix them with docker-compose run web as in the examples above.

You can also use docker-compose run web bash to get a bash prompt for an interactive session inside the container.

Deployment to Divio

Create a new project on Divio

The first step is to create a project on the Divio Control Panel, with your application repository.

You have two ways of doing this:

'New project options'
  • New project, in which you will push your local Git code to Divio’s Git server

  • New project from Git repository (Beta), in which your Divio project will fetch the code from a Git host

In the Divio Control Panel, add a New project. Select the Build your own option.

Once the project has been created, copy the project’s Git URL from its Repository view. Add the project’s Git repository as a remote, for example:

git remote add divio

Commit and push your work.


If you’re using the master branch, you will need to force push to overwrite the initial commits in a Divio project with your own.

You can use divio project commands such as divio project dashboard to interact directly with the Divio project.

In the Divio Control Panel, add a New project from Git repository. Once you have supplied the Git repository URL, you will need to use the public key provided to create a Deploy Key on the repository.

Beta status limitations

Some limitations apply to the current version of this functionality. In order to import a repository, at the time of import:

  • you will need to enable write access on the repository’s deploy key

  • the repository will need a master branch

Once imported, you can remove the write access and can delete the master branch if you don’t need it.

You should also add a webhook, so that when new commits are pushed to the repository, it will send a signal to update the Divio Control Panel.

In the Environments view, configure each environment to use the appropriate branch.

Connect your local application to the cloud project

You can connect a local application to a Divio project on the cloud. This is very convenient, allowing you to interact with the cloud project from your command-line.


divio project configure

and provide the slug (this creates a new file in the project at .divio/config.json).

The cloud project has a slug, based on the name you gave it when you created it. Run divio project list -g to get your project’s slug.

You can also read the slug from the Control Panel:

'Project slug'

You can now use commands such as:

divio project dashboard
divio project pull db  # also push
divio project pull media  # also push
divio project deploy

See some usage examples.

Add database and media services

The new Divio application does not include any additional services. If your application requires a database or media store, they must be added manually using the Divio Control Panel as required. Use the Services menu to add the services your application needs.

Add release commands

If your application needs to perform operations each time it is deployed, for example start-up health tests or database migrations, these should be applied as release commands.

Add additional environment variables

Your application may require additional environment variables in production. Apply any enviroment variables using the Divio Control Panel or CLI.

Push local database/media content

If you have local database or media content, push them to the Test environment:

divio project push db
divio project push media

Deploy the Test server

Deploy with:

divio project deploy

(or use the Deploy button in the Control Panel).

Once deployed, your project will be accessible via the Test server URL shown in the Control Panel.

Deploy the Test server

Deploy with:

divio project deploy

(or use the Deploy button in the Control Panel).

Once deployed, your project will be accessible via the Test server URL shown in the Control Panel (append /admin), but note that you won’t be able to log in until you complete the next step.

Working with the database on the cloud

Your cloud project does not yet have any content in the database, so you can’t log in or do any other work there. You can push the local database with the superuser you created to the Test environment:

divio project push db

or, use the divio project ssh command to open a shell in the Test environment. There you can execute Django migrations and create a superuser in the usual way.

Optionally, but recommended, you can run migrations automatically on deployment by adding a release command in the Control Panel.

Additional notes

See Working with our recommended Django project configuration for further guidance.