17 KiB
Как запустить и сдать лабораторную
Это решение с целевой оценкой 5: все требования уровней 3–4 и исследовательский трек 2. Окончательную оценку ставит преподаватель после проверки и защиты. Сначала прочитайте REPORT.md и DEFENSE.md. Не сдавайте решение, которое не можете объяснить. Возможности вашей lab1 сравнены, собственные тесты адаптированы к новой авторизации. В LAB1_TRANSITION.md описано, что сохранено и изменено.
1. Аккаунт и своя копия на Gitea
- Откройте https://gitea.privcloud.tech в браузере.
- Нажмите «Регистрация» / Register. Если этой кнопки нет, спросите преподавателя, как получить аккаунт: самостоятельно включить регистрацию нельзя.
- Введите свой логин, почту и придумайте пароль. Пароль и коды подтверждения никому не отправляйте, включая чат с ИИ. Если пришло письмо, подтвердите почту.
- Войдите. Откройте https://gitea.privcloud.tech/mtusi2026/mtusi2026lab2 .
- Нажмите «Fork» / «Создать ответвление» вверху страницы. Владельцем выберите свой аккаунт. Не создавайте вместо fork пустой независимый репозиторий: тогда оформить запрос на слияние труднее.
- В своей копии нажмите «Код» / 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); сначала завершите установку инструментов.
Проверьте:
git --version
python3 --version
docker --version
docker compose version
docker info
Если docker info пишет, что не может подключиться к daemon, сначала запустите Docker Desktop. Не переходите к тестам с неработающим Docker.
3. Ветка и файлы
Откройте терминал в папке, где хотите хранить работу:
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:
python3 scripts/init-local.py
docker compose config --quiet
docker compose up -d --build --wait
Первая команда создаёт случайные локальные учебные пароли в secrets/; она не печатает их и не меняет уже существующие. Эти файлы не отправляются в Git. При обычном запуске .env не обязателен: TTL по умолчанию 3600 секунд.
На первом запуске Docker скачает образы и зависимости. Дождитесь завершения команды. Проверьте:
docker compose ps
curl http://localhost:8080/health/ready
Ожидается {"status":"ok"}. Это REST API, отдельного красивого сайта/интерфейса у него нет — по заданию он не нужен.
Если порт 8080 занят, остановите своё приложение, которое его использует, либо измените только левый порт в 127.0.0.1:8080:8080 и передавайте тестам новый BASE_URL. Если контейнер unhealthy:
docker compose logs --tail 80 api db
Не публикуйте полный лог без проверки на секреты. Если ошибка password authentication failed после самостоятельной замены secrets, в старом volume остался прежний пароль. Верните исходные локальные секреты. Не удаляйте volume с нужными данными.
5. Проверки и доказательства
В решении уже приложены реальные результаты проверок облачного стенда. Перед сдачей повторите проверки у себя; это поможет на защите. Текстовые результаты подходят по заданию, скриншоты необязательны.
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
Сохранность данных и прежней сессии:
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-сервисов выполните ПОСЛЕДОВАТЕЛЬНО, не одновременно:
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
git status --short
git diff -- README.md contracts tests
Последняя команда должна ничего не вывести: материалы преподавателя не менялись. Проверьте, что среди добавляемых файлов нет .env, secrets/, токенов и дампов. Затем:
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
Просмотрите изменения. В отчёте должны быть ваши ФИО, группа, результаты, использование ИИ. Если всё правильно:
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)
- Откройте свой fork в браузере.
- Нажмите предложение создать Pull Request после push либо вкладку «Запросы на слияние» → «Новый запрос».
- Базовый репозиторий:
mtusi2026/mtusi2026lab2, базовая ветка: исходная ветка преподавателя (в скачанном архиве она названа master; проверьте в интерфейсе). - Репозиторий-источник: ваш fork; ветка-источник:
solution/…. - Посмотрите сравнение: должны быть исходники, инфраструктура, ваши тесты, отчёт, RESEARCH.md и evidence. Контракт/публичные тесты не должны изменяться.
- Заголовок:
ЛР 2 — БВИ2302 — Карпова — на 5. - В описание вставьте MR_DESCRIPTION.md, добавив фактические результаты проверок на своём компьютере. Не отмечайте непроверенные пункты.
- Нажмите «Создать запрос». Не нажимайте Merge/«Слить» самостоятельно: запрос проверяет преподаватель.
- Скопируйте ссылку на запрос в REPORT.md, сделайте ещё commit и push в ту же ветку.
- При замечаниях меняйте эту же ветку и делайте commit/push: запрос обновится. Новую заявку на каждую правку создавать не нужно.
Создание запроса означает готовность сдавать. Сначала добейтесь проходящих тестов и разберитесь в коде.
Остановка
docker compose down
Данные остаются в именованном volume. Следующий docker compose up -d --wait их восстановит. Команда docker compose down -v намеренно удаляет все данные рабочего PostgreSQL (отдельные исследовательские volumes остаются); не используйте её во время проверки сохранности и не запускайте, если данные нужны.