Files
mtusi2026lab2/HOW_TO_SUBMIT.md
T
2026-11-05 01:43:30 +03:00

169 lines
17 KiB
Markdown
Raw Blame History

This file contains ambiguous Unicode characters
This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.
# Как запустить и сдать лабораторную
Это решение с целевой оценкой 5: все требования уровней 3–4 и исследовательский трек 2. Окончательную оценку ставит преподаватель после проверки и защиты. Сначала прочитайте REPORT.md и DEFENSE.md. Не сдавайте решение, которое не можете объяснить. Возможности вашей lab1 сравнены, собственные тесты адаптированы к новой авторизации. В LAB1_TRANSITION.md описано, что сохранено и изменено.
## 1. Аккаунт и своя копия на Gitea
1. Откройте https://gitea.privcloud.tech в браузере.
2. Нажмите «Регистрация» / Register. Если этой кнопки нет, спросите преподавателя, как получить аккаунт: самостоятельно включить регистрацию нельзя.
3. Введите свой логин, почту и придумайте пароль. Пароль и коды подтверждения никому не отправляйте, включая чат с ИИ. Если пришло письмо, подтвердите почту.
4. Войдите. Откройте https://gitea.privcloud.tech/mtusi2026/mtusi2026lab2 .
5. Нажмите «Fork» / «Создать ответвление» вверху страницы. Владельцем выберите свой аккаунт. Не создавайте вместо fork пустой независимый репозиторий: тогда оформить запрос на слияние труднее.
6. В своей копии нажмите «Код» / Code и скопируйте HTTPS-адрес. Он будет вида `https://gitea.privcloud.tech/ВАШ_ЛОГИН/mtusi2026lab2.git`.
Названия кнопок зависят от языка и версии Gitea. Сюда загружен ZIP, поэтому в нём нет истории Git и нет связи с вашим аккаунтом. Историю нужно взять из fork.
## 2. Программы на компьютере
Понадобятся Git, Python 3.9+ для публичных тестов и Docker с Compose v2. На Windows установите Git for Windows, Python и Docker Desktop с Linux containers/WSL2. После установки откройте Docker Desktop и дождитесь запуска движка. В установщике Python включите добавление Python в PATH.
Дальнейшие команды на Windows выполняйте в Git Bash (пункт «Git Bash Here» в папке). На Linux/macOS — в терминале. Для Windows, если `python3` не найден, заменяйте его на `python`; для Makefile используйте `make test PYTHON=python` либо приведённую ниже команду без make. На Linux требуется доступ пользователя к Docker согласно инструкции вашей ОС; не меняйте права сокета на 777.
Если у вас **Mac**, установите Docker Desktop для своего процессора (Apple Silicon для M1/M2/M3/M4, Intel для старых Intel Mac) и запустите его из «Программы». Откройте приложение «Терминал». Проверьте `python3 --version` и `git --version`; при предложении macOS установить Command Line Tools согласитесь. Основные команды ниже подходят для терминала macOS. Python и Git при необходимости установите из официальных дистрибутивов. Если make недоступен, для функционального run_all всё же нужен make (обычно входит в Command Line Tools); сначала завершите установку инструментов.
Проверьте:
```sh
git --version
python3 --version
docker --version
docker compose version
docker info
```
Если `docker info` пишет, что не может подключиться к daemon, сначала запустите Docker Desktop. Не переходите к тестам с неработающим Docker.
## 3. Ветка и файлы
Откройте терминал в папке, где хотите хранить работу:
```sh
git clone https://gitea.privcloud.tech/ВАШ_ЛОГИН/mtusi2026lab2.git
cd mtusi2026lab2
git switch -c solution/bvi2302-karpova
```
Ветка уже названа для вашей группы и фамилии. Для clone замените только ВАШ_ЛОГИН на логин вашего аккаунта Gitea.
Распакуйте архив решения В ДРУГУЮ папку. Скопируйте из него файлы и папки внутрь только что клонированного репозитория. Вложенной папки `mtusi2026lab2/mtusi2026lab2` получиться не должно: `compose.yaml`, `REPORT.md` и `Makefile` должны лежать рядом.
Никогда не копируйте чужую папку `.git`, `.env`, `secrets`, `.venv` или данные БД. В выданном архиве решения их нет. Исходный README преподавателя, contracts и публичные tests сохранены. ФИО и группа уже внесены: Карпова Надежда Сергеевна, БВИ2302. После создания запроса останется вписать ссылку на него в REPORT.md. Помощь ИИ указана, ваша lab1 учтена.
## 4. Запуск
Все команды выполняются из папки с `compose.yaml`:
```sh
python3 scripts/init-local.py
docker compose config --quiet
docker compose up -d --build --wait
```
Первая команда создаёт случайные локальные учебные пароли в `secrets/`; она не печатает их и не меняет уже существующие. Эти файлы не отправляются в Git. При обычном запуске `.env` не обязателен: TTL по умолчанию 3600 секунд.
На первом запуске Docker скачает образы и зависимости. Дождитесь завершения команды. Проверьте:
```sh
docker compose ps
curl http://localhost:8080/health/ready
```
Ожидается `{"status":"ok"}`. Это REST API, отдельного красивого сайта/интерфейса у него нет — по заданию он не нужен.
Если порт 8080 занят, остановите своё приложение, которое его использует, либо измените только левый порт в `127.0.0.1:8080:8080` и передавайте тестам новый BASE_URL. Если контейнер unhealthy:
```sh
docker compose logs --tail 80 api db
```
Не публикуйте полный лог без проверки на секреты. Если ошибка `password authentication failed` после самостоятельной замены secrets, в старом volume остался прежний пароль. Верните исходные локальные секреты. Не удаляйте volume с нужными данными.
## 5. Проверки и доказательства
В решении уже приложены реальные результаты проверок облачного стенда. Перед сдачей повторите проверки у себя; это поможет на защите. Текстовые результаты подходят по заданию, скриншоты необязательны.
```sh
python3 scripts/capture.py evidence/check-local.txt -- python3 scripts/check_contract.py
python3 scripts/capture.py evidence/smoke-local.txt -- python3 tests/smoke.py
python3 scripts/capture.py evidence/security-local.txt -- python3 student-tests/security.py
```
Сохранность данных и прежней сессии:
```sh
chmod +x scripts/restart.sh
docker compose ps
python3 scripts/capture.py evidence/persistence-local.txt -- python3 tests/resilience.py --mode persistence --action-script scripts/restart.sh
docker compose ps
```
На Windows для persistence рекомендуется WSL2 с Git и Python внутри WSL: Windows Python может не запустить shell-script hook. Откройте папку через терминал WSL и повторите команды там.
Если установлен make, эквивалентные обязательные команды: `make check`, `make test`, `make test-persistence ACTION_SCRIPT=scripts/restart.sh`. Скрипт перезапускает API, PostgreSQL и Redis; не удаляет volume.
При скриншотах покажите команду, PASS и состояния контейнеров, не раскрывайте пароли/токены. Сохраните небольшие изображения в `evidence/` и добавьте ссылки в REPORT.md. Не заменяйте проваленный результат словом PASS.
### Полная проверка на 5
После запуска трёх healthy-сервисов выполните ПОСЛЕДОВАТЕЛЬНО, не одновременно:
```sh
python3 scripts/capture.py evidence/grade5-functional-local.txt -- python3 student-tests/run_all.py
python3 scripts/capture.py evidence/grade5-study-local.txt -- python3 student-tests/research.py
```
Первая команда включает публичные и собственные проверки, перенесённые тесты lab1, Redis/БД-отказы, rollback и полный restart. Она временно останавливает только сервисы этого учебного проекта. Не запускайте её против чужой или production БД. Требуются свободный порт 8081 и отсутствие контейнера lab2-expiry.
Вторая создаёт отдельную исследовательскую БД с 120 000 синтетических сообщений, сравнивает индексы, измеряет записи, делает backup и восстановление в НОВЫЙ PostgreSQL-контейнер и НОВЫЙ volume. Нужны свободные ресурсы Docker (ориентировочно 1–2 ГБ дополнительного диска). Скрипт использует образ PostgreSQL из задания и локальный secrets/db_password, секреты не печатает. Рабочую messenger не удаляет. Не останавливайте/пересобирайте API и БД до завершения эксперимента.
Ожидайте PASS обоих запусков. Исследовательский скрипт обновляет evidence/query-study.json реальными измерениями вашего компьютера. Таблица в RESEARCH.md описывает приложенный облачный прогон — если заменяете JSON своими данными, обновите и таблицу либо сохраните собственный JSON отдельно перед повтором. Не называйте облачные цифры измерениями вашего ноутбука.
После исследования временный recovery-контейнер удаляется, исходная исследовательская БД и новый volume остаются для осмотра. Их случайные имена выводятся/пишутся в evidence/query-study.json. Новый запуск использует новые имена. Для уборки удаляйте только перечисленные исследовательские объекты, когда они больше не нужны; основной postgres_data не трогайте. Обычный `docker compose down -v` не удаляет отдельный исследовательский volume.
## 6. Отправка в свой fork
```sh
git status --short
git diff -- README.md contracts tests
```
Последняя команда должна ничего не вывести: материалы преподавателя не менялись. Проверьте, что среди добавляемых файлов нет `.env`, `secrets/`, токенов и дампов. Затем:
```sh
git add src migrations student-tests scripts/init-local.py scripts/capture.py scripts/restart.sh Dockerfile compose.yaml requirements.txt REPORT.md HOW_TO_SUBMIT.md DEFENSE.md MR_DESCRIPTION.md LAB1_TRANSITION.md RESEARCH.md evidence
git diff --cached --stat
git diff --cached
```
Просмотрите изменения. В отчёте должны быть ваши ФИО, группа, результаты, использование ИИ. Если всё правильно:
```sh
git commit -m "Реализовать lab2: PostgreSQL и постоянные Bearer-сессии"
git push -u origin solution/bvi2302-karpova
```
Если Git просит представиться, один раз в этом репозитории выполните `git config user.name "Ваше имя"` и `git config user.email "Ваша почта"`, затем повторите commit. Если Gitea требует токен вместо пароля, создайте его в настройках своего аккаунта по инструкции Gitea и используйте только в окне авторизации Git/менеджере учётных данных. Не вставляйте токен в URL, код, отчёт или чат.
## 7. Запрос на слияние (PR / merge request)
1. Откройте свой fork в браузере.
2. Нажмите предложение создать Pull Request после push либо вкладку «Запросы на слияние» → «Новый запрос».
3. Базовый репозиторий: `mtusi2026/mtusi2026lab2`, базовая ветка: исходная ветка преподавателя (в скачанном архиве она названа master; проверьте в интерфейсе).
4. Репозиторий-источник: ваш fork; ветка-источник: `solution/…`.
5. Посмотрите сравнение: должны быть исходники, инфраструктура, ваши тесты, отчёт, RESEARCH.md и evidence. Контракт/публичные тесты не должны изменяться.
6. Заголовок: `ЛР 2 — БВИ2302 — Карпова — на 5`.
7. В описание вставьте MR_DESCRIPTION.md, добавив фактические результаты проверок на своём компьютере. Не отмечайте непроверенные пункты.
8. Нажмите «Создать запрос». **Не нажимайте Merge/«Слить» самостоятельно**: запрос проверяет преподаватель.
9. Скопируйте ссылку на запрос в REPORT.md, сделайте ещё commit и push в ту же ветку.
10. При замечаниях меняйте эту же ветку и делайте commit/push: запрос обновится. Новую заявку на каждую правку создавать не нужно.
Создание запроса означает готовность сдавать. Сначала добейтесь проходящих тестов и разберитесь в коде.
## Остановка
```sh
docker compose down
```
Данные остаются в именованном volume. Следующий `docker compose up -d --wait` их восстановит. Команда `docker compose down -v` **намеренно удаляет все данные рабочего PostgreSQL** (отдельные исследовательские volumes остаются); не используйте её во время проверки сохранности и не запускайте, если данные нужны.