How to deploy a new django CMS project using the Divio quickstart repository

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

It uses a standard, minimal django CMS project as modelled on that created by the django CMS installer.

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

The project includes some (clearly-indicated) options for popular components (such as Django Filer) and also a Bootstrap 4 frontend. These can quickly be removed if you prefer a more minimal project to work with.

Clone the repository

Run:

git clone git@github.com:divio/django-cms-divio-quickstart.git

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

Removing optional components

The settings.py and requirements.txt files contain sections that can be removed if you do not require the functionality they provide - in each case, the section is noted with a comment containing the word optional. You will need to make sure that you remove the corresponding sections from both files if you do.

The options include:

  • components typically used with django CMS (CKEditor, Django File, django CMS Admin Style)

  • some popular basic content plugins

  • components and templates required for a Bootstrap 4 frontend

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

  • manage.py

  • asgi.py

  • settings.py

  • wsgi.py

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

Run:

docker-compose build

Run database migrations and create a superuser

docker-compose run web python manage.py 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.)

then:

docker-compose run web python manage.py createsuperuser

Launch the local server

docker-compose up

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

The Django admin is available at http://127.0.0.1:8000/admin.

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.

Deploy the project to Divio

The project is ready for cloud deployment. This requires creating a project on the Divio platform.

Create a new project on Divio

In the Divio Control Panel add a new project, selecting the Build your own option. Accept all the defaults including the Git repository options.

Add database and media services

The new project does not include any additional services; they must be added manually. Use the Services menu to add a Postgres or MySQL database as appropriate, and an S3 object storage instance for media.

Connect the local project to the cloud project

Your Divio 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.

Run:

divio project configure

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

The command also returns the Git remote value for the project. You’ll use this in the next step.

Now the local project is connected to the cloud project, divio project dashboard will open the project in the Control Panel.

Configure the Git repository

Add the project’s Git repository as a remote, using the value obtained from the divio project configure command above. For example:

git remote add divio git@git.divio.com:my-divio-project.git

Commit (if required) and push

If you made any changes to the project files, you will need to commit them first. Otherwise you can simply push to the new remote:

git push divio main

Important

Check the Git branch for the Test environment in the Environments view of your project, and if necesssary, change it to main to match the local repository.

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.