169 lines
17 KiB
Markdown
169 lines
17 KiB
Markdown
# Как запустить и сдать лабораторную
|
||
|
||
Это решение с целевой оценкой 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 остаются); не используйте её во время проверки сохранности и не запускайте, если данные нужны.
|