Zero to Hero: the path from zero to production¶
This route takes you from an empty directory to a production-ready Django application with a WebSocket chat, Docker Compose, authentication and CI.
Each step solves one specific problem and leaves behind a working application.
Route map¶
[0] Environment ──► [1] Hello Django ──► [2] First model ──► [3] CRUD + arch
│
▼
[9] Deployment ◄── [8] Celery ◄── [7] WebSocket ◄── [6] Tests ◄── [5] Auth ◄── [4] Forms + UI
Steps 1–4 are standalone learning projects. Steps 5–9 develop notes_chat_app (the final production application).
Route projects¶
hello_project ← Step 1 — one view, SQLite, no models
bootstrap_notes ← Step 2 — the first model, Django Admin
notes_project ← Step 3 — CRUD, selectors/services, PostgreSQL
crispy_notes ← Step 4 — ModelForm, Bootstrap 5, template inheritance
notes_chat_app ← Steps 5–9 — auth, testing, WebSocket, Celery, Docker, CI
Each standalone project is a separate repository, not a branch of notes_chat_app. It shows only the concept needed at that step.
Summary table of steps¶
| # | Name | Project | New concept | Knowledge | Completion criterion |
|---|---|---|---|---|---|
| 0 | Environment | — | Python, pyenv, Docker | — | python -c "import django; print(django.__version__)" |
| 1 | Hello Django | hello_project | MTV, URLconf, HttpResponse | I, II | curl http://127.0.0.1:8000/ → 200 |
| 2 | First model | bootstrap_notes | ORM, migration, Admin | III | a DB record through Admin |
| 3 | CRUD + arch | notes_project | selectors/services, PostgreSQL | VI | a unit TestCase passes |
| 4 | Forms + UI | crispy_notes | ModelForm, Bootstrap 5 | IV, V | a crispy form in the browser |
| 5 | Auth + security | notes_chat_app | IDOR, Q-filter, Groups | VII | the IDOR test fails without the fix and passes after it |
| 6 | Testing | notes_chat_app | TransactionTestCase, Selenium | VIII | 200+ tests green |
| 7 | WebSocket | notes_chat_app | Channels, Redis, ASGI | IX | the consumer test passes |
| 8 | Celery | notes_chat_app | Celery Worker, Beat, Redis broker, HTTP polling | IX | reminders arrive by email + toast in the browser |
| 9 | Deployment | notes_chat_app | Docker Compose, Nginx, CI | X | GitHub Actions: green |
Step 0. Environment¶
Problem: nothing runs.
What we install: Python (through pyenv), Git, Docker Desktop, VS Code + the Python extension.
Check:
python --version # 3.12.x
docker version # Engine: 24+
git --version # 2.x
python -c "import django; print(django.__version__)" # 5.2.x
New concepts: virtual environment, PATH, Docker daemon.
Step 1. Hello Django¶
Tutorial: 01: The first Django page · In detail: README_1
Problem: how do you make a browser get a response from Python?
What we build: hello_project, an empty Django project with one view.
Architecture at this step:
New concepts: MTV, URLconf, HttpResponse, DEBUG, INSTALLED_APPS.
Common mistakes:
- ModuleNotFoundError: No module named 'django': the virtual environment is not activated
- Error: That port is already in use: another runserver is running
Notes Chat App: a similar structure notes_project/urls.py → notes_app/views.py, but with 15+ views instead of one.
Step 2. The first model¶
Tutorial: 02: The first model · In detail: README_2
Problem: data disappears after the server restarts.
What we build: bootstrap_notes, a project with a Note model, migrations and Django Admin.
class Note(models.Model):
title = models.CharField(max_length=200)
content = models.TextField()
created = models.DateTimeField(auto_now_add=True)
Architectural change: stateless HTTP → data is stored in SQLite between requests.
New concepts: models.Model, migration graph, __str__, ForeignKey, on_delete, Django Admin, QuerySet.
Common mistakes:
- Forgetting makemigrations after changing a model
- IntegrityError: NOT NULL constraint: a required field without a default
Notes Chat App: notes_app/models.py has 10 models with ForeignKey, M2M and on_delete=CASCADE / SET_NULL. SQLite is replaced by PostgreSQL starting from Step 3.
Step 3. CRUD and architecture¶
Problem: the view gets fat: ORM queries, validation and HTTP logic are mixed in one function.
What we build: notes_project, CRUD with selectors.py and services.py, PostgreSQL.
Pedagogical evolution:
def note_list(request):
notes = Note.objects.filter(user=request.user) # ORM in the view
...
# Duplicated in 5 views → we extract it:
# selectors.py
def get_notes_for_user(user):
return Note.objects.filter(user=user) # read only
# services.py
def create_note(user, title, content):
return Note.objects.create(user=user, title=title, content=content) # mutation only
Moving from SQLite → PostgreSQL:
SQLite: no full FOREIGN KEY constraints, limited concurrent writes
PostgreSQL: transactions, indexes, ON DELETE CASCADE/SET NULL, UNIQUE constraints
New concepts: PRG (Post/Redirect/Get), thin view, selector (read-only), service (mutation), get_object_or_404.
Common mistakes:
- Returning a lazy QuerySet from a selector → SynchronousOnlyOperation in an async context
- A mutation in a selector (a layer violation)
- TypeError if the view and service parameters do not match
Step 4. Forms and Bootstrap¶
Tutorial: 04: Templates + Bootstrap · In detail: README_5
Problem: HTML forms look bad, and validation is duplicated in the view and the template.
What we build: crispy_notes: ModelForm, crispy-forms, Bootstrap 5, a SaaS dashboard.
class NoteForm(forms.ModelForm):
class Meta:
model = Note
fields = ['title', 'content', 'priority']
def clean_title(self):
title = self.cleaned_data['title']
if len(title) < 3:
raise ValidationError("Заголовок занадто короткий.")
return title
Template inheritance:
templates/base.html ← DOCTYPE, head, navbar
└── templates/layouts/dashboard.html ← sidebar, content block
└── notes_app/note_list.html ← a specific page
FBV vs CBV:
FBV: explicit if request.method == 'POST': more code, but more transparent
CBV: CreateView, UpdateView: less boilerplate, but harder to debug
→ notes_chat_app chooses FBV for explicitness and flexibility with permissions
New concepts: ModelForm, clean_<field>, CSRF, {{ form|crispy }}, {% extends %}, {% block %}, {% include %}.
Step 5. Authentication and security¶
Tutorial: 05: Auth and security · In detail: README_6
Problem: anyone can read and edit other people's notes (IDOR).
What we add to notes_chat_app:
@login_required: only authenticated users see notes- Object-level permissions:
Note.user == request.user OR group UserProfile(1:1 toUser)Groupsharing: several users have shared access- Password reset flow
The IDOR attack and the defense:
# VULNERABLE: only login is checked, not ownership
@login_required
def note_edit(request, pk):
note = get_object_or_404(Note, pk=pk) # any note at all!
...
# SAFE: Q-filter by owner and group
def get_note_for_user(pk, user):
user_groups = user.groups.all()
return get_object_or_404(
Note,
Q(pk=pk) & (Q(user=user) | Q(group__in=user_groups))
)
New concepts: request.user, login_required, sessions, UserProfile, Q objects, IDOR, AbstractBaseUser, password hashing, authenticate().
Common mistakes:
- @login_required ≠ an object-level permission → IDOR
- Checking note.user == request.user without accounting for group sharing
Step 6. Testing¶
Tutorial: 06: Testing · In detail: README_7
Problem: refactoring breaks things nobody notices.
Test suite architecture:
test_models.py — check constraints, __str__, on_delete behaviour
test_services.py — check the return value + persistence
test_forms.py — valid data, invalid data, custom clean_
test_views.py — Client + force_login, status codes, redirect targets
test_consumers.py — WebsocketCommunicator + TransactionTestCase (not TestCase!)
test_selenium.py — E2E in a real browser (StaticLiveServerTestCase)
Critical: TransactionTestCase for consumer tests:
TestCase wraps each test in a transaction → rollback after the test.
An async consumer reads the DB from a separate worker thread —
that transaction is invisible to it → the setUp objects "disappear".
ALWAYS use TransactionTestCase for consumer tests.
Running:
# Unit + integration + consumer
docker compose run --rm web python manage.py test \
notes_app.tests.test_models notes_app.tests.test_services \
notes_app.tests.test_forms notes_app.tests.test_views \
notes_app.tests.test_consumers -v 2
# Selenium E2E (requires the stack to be running)
docker compose up -d
docker compose exec web python manage.py test notes_app.tests.test_selenium -v 2
New concepts: AAA (Arrange/Act/Assert), setUp, force_login, WebsocketCommunicator, StaticLiveServerTestCase, CI YAML.
Step 7. Async and WebSocket¶
Tutorial: 07: Async and WebSocket · In detail: README_8 · README_9
Problem: HTTP request/response is not suitable for real time: 100 clients = 100 requests/sec with polling.
Pedagogical evolution:
HTTP polling
setInterval(() => fetch('/new-messages/'), 1000)
→ 100 clients = 100 requests/sec: inefficient
WebSocket
→ one long-lived connection
→ the server can push events without a request from the client
→ Django Channels: an ASGI handler for WS
→ Redis channel layer: broadcast to a group
The ASGI stack:
Browser WS connect
→ Nginx (proxy_pass ws://)
→ Daphne ASGI server
→ ProtocolTypeRouter (asgi.py)
→ AuthMiddlewareStack (reads the session cookie → scope["user"])
→ URLRouter (routing.py: /ws/groups/<pk>/chat/)
→ GroupChatConsumer
Critical implementation details:
# asgi.py: get_asgi_application() BEFORE importing notes_app
django.setup() → get_asgi_application() → from notes_app.consumers import ...
# consumers.py: never call the sync ORM directly
history = await database_sync_to_async(
lambda: list(ChatMessage.objects.filter(group=group_pk).values(...))
)() # list() materializes the QuerySet BEFORE leaving the worker
# RedisChannelLayer (settings.py):
CHANNEL_LAYERS = {
"default": {
"BACKEND": "channels_redis.core.RedisChannelLayer",
"CONFIG": {"hosts": [REDIS_URL], "socket_timeout": None},
# ^^^^^^^^^^^^^^^^^^^
# None = no timeout for idle WS
}
}
New concepts: asyncio, coroutine, await, ASGI vs WSGI, AsyncWebsocketConsumer, channel layer, group_send, database_sync_to_async.
Step 8. Celery and background tasks¶
Tutorial: 08: Celery and background tasks
Problem: Django cannot send an email at exactly the scheduled time: a view runs only in response to a request.
Two levels of reminders:
Email (Celery Worker)
Celery Beat → every 60 sec → @shared_task send_reminder_notifications()
→ Reminder.filter(remind_at__lte=now, is_sent=False)
→ send_mail() → reminder.is_sent = True
→ _schedule_next() → a new Reminder if repeat_pattern ≠ none
Browser Toast (HTTP polling)
reminders.js → every 60 sec → GET /reminders/check/
→ JsonResponse({reminders: [...]})
→ Bootstrap Toast for new ones (sessionStorage for deduplication)
Redis DB allocation:
Redis DB 0 — Django Channels channel layer (WebSocket)
Redis DB 1 — Celery broker and result backend
Docker Compose services:
celery-worker:
command: celery -A notes_project worker -l info --concurrency=2
celery-beat:
command: celery -A notes_project beat -l info # exactly 1 instance!
New concepts: @shared_task, Celery Beat, broker, CELERY_BEAT_SCHEDULE, relativedelta, HTTP polling, Bootstrap Toast API, sessionStorage, @override_settings(EMAIL_BACKEND=...), mail.outbox.
Step 9. Deployment and CI¶
Tutorial: 09: Deployment · In detail: README_9
Problem: the application only works locally.
The Docker Compose stack:
services:
db: # PostgreSQL + PostGIS
redis: # the channel layer for Channels
web: # Django (Daphne ASGI)
nginx: # reverse proxy, SSL termination, static files
ngrok: # a public HTTPS tunnel for development
selenium: # Selenium Grid for E2E tests
Production checklist:
✓ DEBUG=False
✓ SECRET_KEY — from env, not in the code
✓ DATABASE_URL — missing → Exception (no SQLite fallback!)
✓ ALLOWED_HOSTS — specific domains
✓ Static files — through Nginx, not Django
✓ DebugExceptionMiddleware — only if DEBUG=True
✓ HTTPS — CSRF_TRUSTED_ORIGINS, SESSION_COOKIE_SECURE
GitHub Actions CI:
New concepts: Dockerfile, multi-service docker-compose.yml, ENTRYPOINT, Nginx proxy_pass, collectstatic, the .env file, GitHub Actions workflow.
Architectural evolution across the whole route¶
| Step | DB | Auth | Forms | Tests | Deploy | Background process |
|---|---|---|---|---|---|---|
| 1 | SQLite (not used) | — | — | — | runserver | — |
| 2 | SQLite | — | Admin | — | runserver | — |
| 3 | PostgreSQL | — | raw HTML | TestCase | runserver | — |
| 4 | PostgreSQL | — | ModelForm + crispy | Form tests | runserver | — |
| 5 | PostgreSQL | login_required + Q-filter | ModelForm | IDOR test | runserver | — |
| 6 | PostgreSQL | ✓ | ✓ | 200+ tests | runserver | — |
| 7 | PostgreSQL | ✓ | ✓ | + consumer | Daphne ASGI | — |
| 8 | PostgreSQL | ✓ | ✓ | + test_tasks | Daphne ASGI | Celery Worker + Beat |
| 9 | PostgreSQL | ✓ | ✓ | + Selenium | Docker + Nginx + CI | Celery Worker + Beat |
What's next¶
After finishing the Zero to Hero route:
- Notes Chat App Deep Dive: a full architectural breakdown of the final application
- The Django book: the theoretical foundation for deepening your knowledge
- Labs: practice without step-by-step hints