Getting Started With Django the Awesome Way

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: python3 --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: pipenv shell

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.

Install Django: 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): rm Pipfile

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

(IMPORTANT: replace <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: createdb <projectname>

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 createdb utility.

Run migrations: ./manage.py migrate

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: ./manage.py createsuperuser

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!: ./manage.py runserver

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!

Expert Mode

Here’s a list of just the steps, for those of you who are in “Expert mode”

1. python3 --version
2. pip install pipenv (if you don’t have it yet)
3. mkdir myproject; cd myproject
4. pipenv shell
5. pipenv install django~=2.2
6. rm Pipfile
7. 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 <projectname>)
8. vi projectname/settings.py
9. createdb <projectname>
10. pipenv install --dev
11. ./manage.py migrate
12. ./manage.py createsuperuser
13. ./manage.py runserver