Updated original article published on 2017-10-12 for Django 2.2
Have you ever wanted to get a user interface with a cloud database up before lunch? If so, Django is a great web framework for you.
But getting that far that quickly means you need to know what you’re doing.
There are many tutorials for starting a Django project, but I always find that most omit a few key steps that they assume you already know how to do. As a developer getting Django projects up and running, I often wind up cross-referencing different tutorials to make sure I don’t miss a step.
So here it is, the master Django tutorial. Now you can have only one Chrome tab open instead of five while you start your next Django project. You’re welcome!
This is for a new Django project in Python 3 for deployment on Heroku. (Skip to the bottom if you already know all this stuff and just want a handy cheat sheet).
Thirteen Steps To Django Bliss
Check your python version:
You should have at least 3.4 but it’s a good idea to go ahead and get the latest version (at the time of this writing 3.7.4).
If you find you don’t have python 3 you can download the latest here. Installing a new version of python does not replace your existing python version. You can safely have several versions installed on the same system.
Check out what’s new in Python 3.7 in this blog from Heroku.
Install Pipenv if you don’t have it:
pip install pipenv
Pipenv combines virtual environment management and dependency management. It’s effectively a replacement for the
requirements.txt file that
pip freeze generates.
Create a project directory where you want to build your project:
mkdir projectname && cd projectname
Create and enter virtual environment with Pipenv:
This command will both create an environment for you and activate it. Before Pipenv we would do something like
python3 -m venv env or use
virtualenv for Python 2 and then activate with
source env/bin/activate. Using a virtual environment helps keep are dependency versions separate from project to project and enables us to reliably deploy them.
pipenv install django~=2.2
Anytime you call
pipenv install it will add the package to the project’s
Pipfile and install it and any sub-dependencies into the virtual environment it created. Django 2.2 is a Long Term Support (LTS) edition which means it should get security updates through at least April 2022. If you’re still reading this after that May 2021 then you may need to tweak these instructions for version 3.2.
Remove the Pipfile (temporarily):
The following step will copy a new
Pipfile with all the dependencies you need to get started but won’t replace any existing files so we have to delete the current one first.
Create a new Django project from the Heroku starter template:
django-admin.py startproject --template=https://github.com/RadialDevGroup/heroku-django-template/archive/Django-2.2.zip --name=Procfile --name settings.yml --name settings.yml.example <projectname> .
<projectname> with your project’s name)
This will install our forked version of Heroku’s starter template into the current directory (that’s the dot). It provides a common set of settings for a typical project. Our version imports settings from settings.yml which you can exclude from your repository to securely store secret tokens and local settings.
Verify settings: Open
projectname/settings.py in your favorite editor
Before getting started you should always review the project settings to make sure they are appropriate for your project. You will also want to create a settings.yml with any keys you need. If you want to override a setting in settings.yml you can do something like
env.get('TIME_ZONE', 'UTC'). This will use the TIME_ZONE key in your settings.yml and fall back to UTC if it is not defined
Install other packages:
pipenv install --dev
This will install all of the packages listed in the
Pipfile including things needed for Heroku such as the whitenoise static asset system. As you add dependencies to your project continue to use the
pipenv install command to keep your dependencies in sync.
Create database in Postgres:
By default, the project name you selected is provided as the database name in
settings.py but you can change it if you wish. If you don’t have Postgres, install it here. Make sure it’s running before you use the
Django comes with a couple of models to manage future migrations and support user logins for the admin site. This is a command you will need to run every time you make a change to the models. To generate the migrations after changing your model files run
pipenv run manage.py makemigrations.
Create a superuser for the admin site:
Follow the prompts to set up a user on your local machine that will be able to log into the admin site.
Start the server!:
Hooray! You’ve done it! The server should start up on
localhost:8000 by default.
Next steps: if you are not familiar with Django, checkout the Writing Your First Django App tutorial. Pat yourself on the back, you’ve already done the first few commands!
Here’s a list of just the steps, for those of you who are in “Expert mode”
pip install pipenv(if you don’t have it yet)
mkdir myproject; cd myproject
pipenv install django~=2.2
django-admin.py startproject --template=https://github.com/RadialDevGroup/heroku-django-template/archive/Django-2.2.zip --name=Procfile --name settings.yml --name settings.yml.example <projectname> .(remember to replace
pipenv install --dev