Українська · English
Навчальний Django-репозиторій, який веде студента від web foundations до фінального Django-застосунку з нотатками, списками, груповим доступом і WebSocket-чатом.
Notes Chat App показує, як виростає Django-застосунок:
- від URL routing і function-based views;
- до models, migrations, ORM і оптимізації запитів;
- до forms, templates, Bootstrap і Crispy Forms;
- до services/selectors, authentication, permissions і tests;
- до ASGI, Django Channels і WebSocket-чату;
- до мислення про Docker, Redis, PostgreSQL і deployment.
UI проєкту використовує назву CrispyNotes. Django project package - notes_project, Django app - notes_app.
| Напрям | Реалізація |
|---|---|
| Notes | CRUD, пошук, notebooks, tags, priority, pinned |
| Todo lists | списки, items, toggle, direct sharing |
| Shopping lists | товари, кількість, estimated price, sharing |
| Groups | створення груп, учасники, group-owned notes/shopping lists |
| Chat | real-time group chat через Django Channels |
| Auth | registration, login/logout, password change/reset templates |
| Tests | models, services, forms, views, consumers, Selenium |
- Python 3.12 у середовищі аудиту.
- Django
>=5.2,<6.0. - Bootstrap 5 і Bootstrap Icons.
django-crispy-forms+crispy-bootstrap5.- Django Channels, Daphne, Uvicorn,
channels-redis. - Тільки PostgreSQL: без
DATABASE_URLsettings.pyпіднімає виняток (SQLite не використовується). - PostgreSQL і Redis через environment variables.
- Selenium, coverage, GitHub Actions.
git clone https://github.com/NikoriakViktot/notes_chat_app.git
cd notes_chat_app
python3 -m venv .venv
source .venv/bin/activate
python -m pip install --upgrade pip
pip install -r requirements.txt
python manage.py migrate
python manage.py createsuperuser
python manage.py runserverWindows PowerShell:
py -3.12 -m venv .venv
.\.venv\Scripts\Activate.ps1
python -m pip install --upgrade pip
pip install -r requirements.txt
python manage.py migrate
python manage.py runserver| URL | Призначення |
|---|---|
/ |
стартова сторінка |
/register/ |
реєстрація |
/accounts/login/ |
login |
/notes/ |
нотатки |
/todo/ |
списки справ |
/shopping/ |
списки покупок |
/groups/ |
групи |
/groups/<pk>/chat/ |
HTML-сторінка чату |
/ws/groups/<pk>/chat/ |
WebSocket endpoint |
/api/notes/ |
REST API нотаток (DRF): список, ?search=, створення; /api/notes/<id>/, /api/notes/<id>/pin/ |
/admin/ |
Django admin |
flowchart TD
Browser["Browser"] --> URLs["notes_project/urls.py"]
URLs --> AppURLs["notes_app/urls.py"]
AppURLs --> Views["notes_app/views.py"]
Views --> Forms["notes_app/forms.py"]
Views --> Selectors["notes_app/selectors.py"]
Views --> Services["notes_app/services.py"]
Selectors --> Models["notes_app/models.py"]
Services --> Models
Models --> DB["PostgreSQL"]
Browser --> JS["group_chat.js"]
JS --> ASGI["notes_project/asgi.py"]
ASGI --> Consumer["notes_app/consumers.py"]
Consumer --> ChannelLayer["InMemory або Redis channel layer"]
Документація побудована на MkDocs + Material.
Онлайн: https://nikoriakviktot.github.io/notes_chat_app/
source .venv/bin/activate
pip install -r requirements-docs.txt
mkdocs serveВідкрий у браузері: http://localhost:8000
mkdocs serve автоматично перезавантажує при зміні будь-якого .md файлу.
git add mkdocs.yml requirements-docs.txt docs/ .github/workflows/docs.yml
git commit -m "docs: update documentation"
git pushGitHub Actions автоматично збудує сайт і задеплоїть у гілку gh-pages.
Статус: https://github.com/NikoriakViktot/notes_chat_app/actions
Перший деплой: зайди в Settings → Pages, вибери Source =
gh-pages// (root), натисни Save.
| Розділ | Опис |
|---|---|
| Книга | 12 модулів: Web → Django → DB → Forms → Frontend → Architecture → Auth → Testing → Async → Linux → Deploy |
| Notes Chat App | Архітектура, моделі, тести, деплоймент фінального проєкту |
| Практика | Туторіали та labs |
| Довідник | Cheatsheets, глосарій, troubleshooting |
| Викладачу | Teaching guide, learning path |
- Getting started
- Web foundations
- Django core
- Database and ORM
- Forms and validation
- Frontend and templates
- Application architecture
- Auth and security
- Testing and quality
- Async and realtime
- Linux and DevOps
- Deployment
- Final project
Команда заповнює базу даних реалістичними прикладами для швидкого старту та демонстрації.
# Звичайний запуск (ідемпотентний — не дублює якщо вже є)
python manage.py seed_demo_data
# Очистити всі demo-дані і створити заново
python manage.py seed_demo_data --reset
# Дозволити запуск при DEBUG=False (production-guard bypass)
python manage.py seed_demo_data --force
# Через Docker
docker compose run --rm web python manage.py seed_demo_data
docker compose run --rm web python manage.py seed_demo_data --resetSEED_DEMO_DATA=1 в docker-compose.yml → сідер запускається автоматично при старті контейнера через entrypoint.sh з прапором --force (обходить production-guard при DEBUG=False).
Пароль для всіх: demo1234
| Логін | Ім'я | |
|---|---|---|
demo_alice |
Аліса Шевченко | alice@demo.example.com |
demo_bob |
Боб Коваленко | bob@demo.example.com |
demo_carol |
Кароль Мельник | carol@demo.example.com |
| Назва групи | Учасники |
|---|---|
| Команда розробки | demo_alice, demo_bob, demo_carol |
| Сімейний чат | demo_alice, demo_carol |
| Об'єкт | Кількість | Деталі |
|---|---|---|
| Користувачі | 3 | alice, bob, carol |
| Групи | 2 | Команда розробки, Сімейний чат |
| Теги | 18 | 6 тегів × 3 юзери (робота, особисте, навчання, важливо, ідеї, перечитати) |
| Записники | 9 | 3 записники × 3 юзери (Робочі нотатки, Особисте, Навчання Python) |
| Нотатки | 30 | 10 нотаток × 3 юзери, з тегами, пріоритетами і прикріпленими |
| Нагадування | 12 | 4 нагадування × 3 юзери |
| Списки справ | 9 | 3 Todo-списки × 3 юзери, з items і sharing між юзерами |
| Список покупок | 9 | 3 shopping-списки × 3 юзери, з цінами і кількостями |
| Повідомлення чату | 30 | Реалістичний діалог у групі «Команда розробки» |
робота · особисте · навчання · важливо · ідеї · перечитати
- Архітектура нового модуля (робота, важливо — pinned, shared з групою)
- Docker Compose + PostgreSQL (робота, навчання)
- Django Channels: channel layer (навчання — pinned)
- Ідея: фільтрація нотаток за датою (ідеї, робота)
- Книги до прочитання (навчання, перечитати)
- Конспект: asyncio event loop (навчання)
- Зворотний зв'язок після демо (робота, shared з групою)
- Рефакторинг selectors.py (робота, важливо)
- Плани на вихідні (особисте)
- WebSocket: оптимізація history (ідеї, навчання — pinned, shared з групою)
Повторний запуск seed_demo_data (без --reset) не дублює дані — використовується update_or_create за username / title. Безпечно запускати декілька разів.
Для повного скидання демо-даних (тільки demo_* об'єкти, без торкання даних реальних юзерів):
python manage.py seed_demo_data --resetngrok створює захищений тунель від публічного URL до твого локального порту 80 (nginx). Зручно щоб показати проєкт без деплою або протестувати вебхуки.
Твій статичний домен: https://fawn-natural-mayfly.ngrok-free.app
Додай у .env:
NGROK_AUTHTOKEN=your_ngrok_authtoken_here
NGROK_DOMAIN=fawn-natural-mayfly.ngrok-free.appВажливо: якщо ngrok вже запущений локально (
ngrok http 80) — зупини його передdocker compose up. Один статичний домен не може бути активним двічі (помилкаERR_NGROK_334).
Запусти:
docker compose up -dngrok-сервіс підніметься автоматично і прокине тунель до nginx:80. Веб-інтерфейс ngrok: http://localhost:4040
Архітектура мережі: всі сервіси знаходяться в одній явній Docker-мережі app-net. ngrok стартує тільки після того, як nginx пройде health check (GET /accounts/login/ → 200), що усуває помилку ERR_NGROK_8012 (не міг резолвити hostname nginx).
Спочатку запусти стек (docker compose up -d), потім у окремому терміналі:
# Встановлення
curl -sSL https://ngrok-agent.s3.amazonaws.com/ngrok.asc \
| sudo tee /etc/apt/trusted.gpg.d/ngrok.asc >/dev/null \
&& echo "deb https://ngrok-agent.s3.amazonaws.com bookworm main" \
| sudo tee /etc/apt/sources.list.d/ngrok.list \
&& sudo apt update && sudo apt install ngrok
# Авторизація
ngrok config add-authtoken YOUR_AUTHTOKEN
# Запуск
ngrok http --url=fawn-natural-mayfly.ngrok-free.app 80# Встановлення
brew install ngrok
# Авторизація
ngrok config add-authtoken YOUR_AUTHTOKEN
# Запуск
ngrok http --url=fawn-natural-mayfly.ngrok-free.app 80# Встановлення через winget
winget install ngrok
# Авторизація
ngrok config add-authtoken YOUR_AUTHTOKEN
# Запуск
ngrok http --url=fawn-natural-mayfly.ngrok-free.app 80Токен знаходиться в ngrok Dashboard → Your Authtoken. Зберігай його як пароль, не комітти в git.
docker compose run --rm web python manage.py check
docker compose run --rm web python manage.py testAsync HTTP demo modules у поточному working tree відсутні і не описуються як активна feature. Реальний async-компонент проєкту - WebSocket chat через ASGI, Channels і GroupChatConsumer.
Повний стек працює через docker compose up --build:
| Сервіс | Роль |
|---|---|
db (PostgreSQL 16) |
база даних |
redis (Redis 7) |
channel layer для WebSocket і broker для Celery |
web (Uvicorn/ASGI) |
Django-застосунок на порту 8001 |
nginx (1.27) |
reverse proxy на порту 80, роздає staticfiles |
celery-worker |
Celery worker для фонових задач (notes_app/tasks.py) |
celery-beat |
Celery beat — планувальник періодичних задач |
ngrok |
публічний тунель → nginx:80 (profile tunnel) |
selenium |
Chrome для E2E-тестів (profile test) |
selenium-tests |
одноразовий запуск Selenium E2E-тестів (profile test) |
Всі сервіси підключені до спільної bridge-мережі app-net. Ланцюг залежностей зі health checks: db → redis → web → nginx → ngrok.
- Винести
SECRET_KEYіALLOWED_HOSTSу environment variables. - Додати production-ready logging і monitoring.
- Якщо потрібно повернути async HTTP demo, відновити
async_views.py,async_selectors.py,async_services.pyразом із routes.