Skip to content

Repository files navigation

Notes Chat App

Українська · 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_URL settings.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 runserver

Windows 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

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"]
Loading

Документація

Документація побудована на 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 файлу.

Публікація на GitHub Pages

git add mkdocs.yml requirements-docs.txt docs/ .github/workflows/docs.yml
git commit -m "docs: update documentation"
git push

GitHub 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

Навчальний маршрут

  1. Getting started
  2. Web foundations
  3. Django core
  4. Database and ORM
  5. Forms and validation
  6. Frontend and templates
  7. Application architecture
  8. Auth and security
  9. Testing and quality
  10. Async and realtime
  11. Linux and DevOps
  12. Deployment
  13. Final project

Демо-дані (seed_demo_data)

Команда заповнює базу даних реалістичними прикладами для швидкого старту та демонстрації.

Команди

# Звичайний запуск (ідемпотентний — не дублює якщо вже є)
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 --reset

Автоматичний запуск у Docker

SEED_DEMO_DATA=1 в docker-compose.yml → сідер запускається автоматично при старті контейнера через entrypoint.sh з прапором --force (обходить production-guard при DEBUG=False).

Демо-користувачі

Пароль для всіх: demo1234

Логін Ім'я Email
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 Реалістичний діалог у групі «Команда розробки»

Теги (у кожного юзера)

робота · особисте · навчання · важливо · ідеї · перечитати

Нотатки (10 тем, однакові для всіх юзерів)

  • Архітектура нового модуля (робота, важливо — 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 --reset

ngrok — публічний доступ ззовні

ngrok створює захищений тунель від публічного URL до твого локального порту 80 (nginx). Зручно щоб показати проєкт без деплою або протестувати вебхуки.

Твій статичний домен: https://fawn-natural-mayfly.ngrok-free.app

Варіант 1: через Docker Compose (рекомендовано)

Додай у .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 -d

ngrok-сервіс підніметься автоматично і прокине тунель до nginx:80. Веб-інтерфейс ngrok: http://localhost:4040

Архітектура мережі: всі сервіси знаходяться в одній явній Docker-мережі app-net. ngrok стартує тільки після того, як nginx пройде health check (GET /accounts/login/ → 200), що усуває помилку ERR_NGROK_8012 (не міг резолвити hostname nginx).

Варіант 2: локально (без Docker)

Спочатку запусти стек (docker compose up -d), потім у окремому терміналі:

Linux

# Встановлення
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

macOS

# Встановлення
brew install ngrok

# Авторизація
ngrok config add-authtoken YOUR_AUTHTOKEN

# Запуск
ngrok http --url=fawn-natural-mayfly.ngrok-free.app 80

Windows

# Встановлення через 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 test

Async HTTP demo modules у поточному working tree відсутні і не описуються як активна feature. Реальний async-компонент проєкту - WebSocket chat через ASGI, Channels і GroupChatConsumer.

Docker stack

Повний стек працює через 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.

Releases

Packages

Contributors

Languages