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.
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:
- General overview of the Control Panel
More information about your account, project settings and more.
- How to create a new Divio Cloud project
Additional detail about project creation options.
- Frequently Asked Questions
You might find answers to your questions here.
- Developer tutorials
More experienced developers should be aware of the material in our Developer Handbook.
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:
- Managing project servers
Understand the difference between the test and live server.
- Project settings
Know what you can do with your project and its settings.
- How to use the Divio App
Install and configure the Divio App for local development.
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 http://127.0.0.1:8000 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.
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:
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
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.
The tutorial will ask you to run specific commands such as:
django-admin startproject mysite
python manage.py runserver
python manage.py 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 manage.py runserver`
docker-compose run --rm web python manage.py 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 upto start the local development server
divio project stopto stop a project
divio project updateto 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)
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.
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.
- 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.
- 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.
- 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 logsto see what the issue is. It may be a simple typo or missing modules import.
- Instead of SQLite, Divio Cloud provides a Postgres database automatically for you. There's no additional configuration required.