Django Unraveled: A Practical Guide for Solo Developers and Project Hoarders

Overview

There’s a special kind of joy in picking up an “old boring” technology that has been battle-tested for decades. Django, now over 20 years old, is exactly that. Unlike the shiny new frameworks that change every six months, Django offers stability, a huge ecosystem, and solutions to nearly every problem you’ll encounter. For developers who work on side projects in bursts—abandoning them for months, then returning with fresh eyes—Django’s explicitness is a lifesaver. You don’t need to remember hidden conventions; everything is spelled out in a handful of core files. This guide will walk you through the essential steps to get a Django project off the ground, with a focus on the three features that make it stand out: its explicit architecture, built-in admin interface, and powerful ORM.

Prerequisites

Before diving in, ensure you have:

• Python 3.8+ installed on your system.
• A basic understanding of Python syntax and object-oriented programming.
• Familiarity with the command line (terminal or PowerShell).
• A code editor (VS Code, PyCharm, or any text editor).

Step-by-Step Instructions

1. Setting Up a Django Project

First, create a virtual environment to isolate your dependencies:

python -m venv venv
source venv/bin/activate  # On Windows: venv\Scripts\activate

Install Django:

pip install django

Create a new project and enter its directory:

django-admin startproject myproject
cd myproject

Now create an app—a reusable module within your project. For this guide, we’ll build a simple zine catalog:

python manage.py startapp zines

Add the app to your INSTALLED_APPS in myproject/settings.py:

INSTALLED_APPS = [
    ...
    'zines',
]

2. Defining Models with the ORM

Models define the structure of your database tables. Open zines/models.py and create a Zine model:

from django.db import models

class Zine(models.Model):
    name = models.CharField(max_length=200)
    publication_date = models.DateField()
    free = models.BooleanField(default=False)
    slug = models.SlugField(unique=True)
    
    def __str__(self):
        return self.name

Now create a related model, Product, and a many-to-many relationship through an intermediary table:

class Product(models.Model):
    name = models.CharField(max_length=200)
    # ... other fields

class ZineProduct(models.Model):
    zine = models.ForeignKey(Zine, on_delete=models.CASCADE)
    product = models.ForeignKey(Product, on_delete=models.CASCADE)

class Order(models.Model):
    products = models.ManyToManyField(Product, through='OrderProduct')
    email_hash = models.CharField(max_length=64)

Run migrations to create the database tables:

python manage.py makemigrations
python manage.py migrate

3. Harnessing the Built-in Admin Interface

Django’s admin is one of its killer features. Register your models in zines/admin.py. Here’s an example that customizes the list view, search, and ordering:

from django.contrib import admin
from .models import Zine

@admin.register(Zine)
class ZineAdmin(admin.ModelAdmin):
    list_display = ["name", "publication_date", "free", "slug", "image_preview"]
    search_fields = ["name", "slug"]
    readonly_fields = ["image_preview"]  # if you have a custom method
    ordering = ["-publication_date"]

To see the admin, create a superuser:

python manage.py createsuperuser

Then run the development server and log in at http://127.0.0.1:8000/admin/:

python manage.py runserver

4. Querying with Django’s ORM (The Double Underscore Magic)

Django’s ORM lets you write Python code instead of raw SQL. The double underscore (__) is used to follow relationships. Suppose you want to find all zines that have never been ordered by a specific email hash. The underlying query spans five tables: zines, zine_products, products, order_products, and orders. With Django, you simply write:

from .models import Zine

unpurchased_zines = Zine.objects.exclude(
    product__order__email_hash=email_hash
)

This works because you defined ManyToManyField and ForeignKey relationships. Django automatically joins the tables following the relationship path product__order__email_hash.

5. Understanding the Explicit File Structure

One reason Django is easy to return to after a long break is its clear file layout. Your main app will typically contain these files:

• urls.py – Maps URLs to views.
• models.py – Defines database models.
• views.py – Contains the logic that processes requests and returns responses.
• admin.py – Registers models for the admin interface.
• tests.py – For unit tests.

Templates (HTML files) are stored in a templates/ folder and are explicitly referenced from views. For example, a view might return render(request, 'zines/list.html', context). No magic guessing—everything is spelled out.

Common Mistakes

Forgetting to Run Migrations

After creating or modifying a model, always run makemigrations and migrate. Missing this step is the most frequent source of “no such table” errors.

Not Using a Virtual Environment

Installing Django globally can lead to version conflicts across projects. Always create and activate a virtual environment before installing dependencies.

Misconfiguring Static Files

When deploying, static files (CSS, JS) require special handling. For development, the built-in server serves them automatically, but for production you’ll need to run collectstatic and configure a static file server.

Forgetting to Create a Superuser

Without a superuser account, you cannot log into the admin. Run createsuperuser after your first migration.

Summary

Django is a mature, explicit web framework that rewards you with stability and a vast collection of built-in tools. By following this guide, you’ve set up a project, defined models with relationships, customized the admin interface, and written ORM queries that would otherwise require complex SQL joins. The explicit file structure—urls.py, models.py, views.py, admin.py, tests.py—makes it easy to pick up where you left off, even after months away. Whether you’re building a small side project or a production application, Django’s “less magic” philosophy and its powerful admin and ORM make it an excellent choice.