Here’s what you’ll have after completing this guide:

  • a website running Django
  • a starting point to continue with the Django tutorial

This guide will help get you started. We'll take you through key steps, introduce you to important concept and point you to further documentation and other resources along the way. It's not intended to be a complete tutorial, and you will need to be prepared to look further into some topics on your own if necessary. 

A plain-text code editor to work on the code and configuration is required. Atom, Sublime and Visual Studio are all excellent choices.

About Django

Django is a framework based on the popular programming language Python. If you are a complete beginner to Python, we recommend learning some basics (the Learn Python the Hard Way course is recommended).

Before we begin

Before we create a project, please familiarise yourself with the basics of Divio Cloud. Some key topics and resources:

Some of these guides will make more sense and be most useful once you have already dived in and are working with Divio Cloud.

Create a new project

Create a new project with the following configuration:

  • Platform: Python 3.6.x
  • Type: Django
  • Boilerplate: Default

Then select a suitable subscription and create the project.

By default, Divio Cloud installs the latest Long Term Release (LTS) version of Django. You can change this by navigating to the Addons section and selecting Aldryn Django. Additional information about changing the addon version is available in our support section.

Set up the project locally

You will need to be aware of some key topics as we continue - refer to these articles if necessary as you go along:

Once you have installed and launched the Divio App on your computer, set up the the project you just created by clicking Setup:

This will take a few minutes to conclude. Once completed hit Start to launch your local server.

Now you can open your local website using the "eye" icon on the top right of the Local Server in the Divio App or open up in a browser. Once you have logged in, you should see the Django admin:

Not working? Retrace your steps, and pay close attention to any error messages, as they will contain important information about the problem. You will also find valuable guidance in the material recommended above.


About Docker

Divio Cloud uses Docker to run your projects locally. This allows you to use any programming language – be it Python, Node or PHP – locally, without configuring your operating system to support it. If you are experience issues, have a look at our troubleshooting section or our Docker guide.

Preparing for the Django tutorial

Before you can start the official Django tutorial, we need to do a few more things:

Code editor

Open the source folder in a code editor. You'll find it by selecting the "folder" icon in the Divio App and opening the whole directory in your editor:

Using a shell

You will need to run commands in a command line environment. The Divio App makes this easy for you - just click on the Divio Shell button on the lower left of the app. This will create a terminal shell with all the necessary environment variables in place.

Everything should show up with green checks - if not trace your steps back to resolve it.


About shell commands

You should be familiar with basic shell commands such as cd , open and cp as they are essential items in the developer's toolbox. The Learn Python the Hard Way tutorial has a very good appendix introducing these commands.

Entering commands

The tutorial will ask you to run specific commands such as:

  • django-admin startproject mysite 
  • python runserver 
  • python startapp polls 

You will need to run these inside the Docker container of your project, not in your own environment on your computer. To get into the container, run the following command in the Divio Shell:

  • docker-compose run --rm web bash 

Don't forget to cd to into the project folder first.

You can also issue commands in the shell to run in the container, by prefixing them with docker-compose run --rm web . For example:

  • docker-compose run --rm web django-admin startproject mysite  
  • docker-compose run --rm web python runserver` 
  • docker-compose run --rm web python startapp polls  

Divio Command Line Interface

It's very helpful to understand the basic commands for the Divio CLI (Command Line Interface). For example, you can use it to start and stop the server inside the shell far quicker then the Divio App. Some helpful commands:

  • divio project up   to start the local development server
  • divio project stop  to stop a project
  • divio project update  to update the local development server

Basic Docker commands

Docker also provides a number of helpful commands. See our documentation for more, but for now you should know about:

  • docker-compose up - starts the server (stop it with control-c)

Managing files

You can upload and download files from your local server to the test server easily using the Divio App. Simply use the corresponding Download and Upload controls and select what you want to transfer from the menu.

The underlying technology behind the file management is Git. If you type git status into an open shell inside the project you will get a report, perhaps something like:

The Divio App automatically commits these changes into your Git repository. Divio provides a Git server as part of the service.


About Git

Git is a version control system (VCS) and tracks the history of your changes as people and teams collaborate together on a project. It is very helpful to be familiar with Git and what it does. An excellent starting point is the very popular Git tutorial on GitHub.

Start the Django tutorial

Now head over to the Django tutorial and start your journey as a Django developer. 

You can skip ahead to Writing your first Django app, part 1 - Creating the polls app. From there your journey to learning Django begins.

Some remarks

  1. You can still read the first two chapters until Creating the polls app. They help you to understand what's necessary to set up Django. However, there are no actions needed as Divio Cloud optimises the setup automatically for you.
  2. You might encounter a slightly different file structure from the Django tutorial. This is fine - many developers have their own preferred style. Our setup uses an opinionated structure set in Aldryn Django. We describe the differences in more detail in our developers section.
  3. It is sometimes required to restart the server after a change; you can do this through the Divio App by clicking on Stop/Start. If the server still doesn't run try docker-compose logs to see what the issue is. It may be a simple typo or missing modules import.
  4. Instead of SQLite, Divio Cloud provides a Postgres database automatically for you. There's no additional configuration required.
Did this answer your question?