From 21f3570b894b8ba6ab4aad18c810e19d622b5f08 Mon Sep 17 00:00:00 2001 From: Dmitry Dementev Date: Mon, 19 Oct 2026 09:48:24 +0200 Subject: [PATCH] docs: clarify learner workflow and resource requirements --- README.md | 19 +- START_HERE.md | 263 ++++++++++-------- docs/course_program.md | 31 ++- docs/maintainer_guide.md | 2 + docs/mentor_notes.md | 9 +- docs/stack_reference.md | 43 ++- docs/study_workflow.md | 153 ++++++++++ notebooks/01_environment_and_smoke_test.ipynb | 17 +- 8 files changed, 399 insertions(+), 138 deletions(-) create mode 100644 docs/study_workflow.md diff --git a/README.md b/README.md index ee63f4a..9fe4e08 100755 --- a/README.md +++ b/README.md @@ -63,17 +63,23 @@ graph TB ## С чего начать -1. Открой [START_HERE.md](./START_HERE.md) — запуск стенда, диагностика, первый ноутбук. -2. Пройди `notebooks/01_environment_and_smoke_test.ipynb`. -3. Дальше по порядку: [docs/course_program.md](./docs/course_program.md). +1. Открой [START_HERE.md](./START_HERE.md) — подготовка, запуск и первый ноутбук + с ожидаемым результатом. +2. Продолжи по [маршруту из восьми модулей](./docs/course_program.md#маршрут-по-модулям). +3. Между занятиями используй [памятку учащегося](./docs/study_workflow.md): + остановка, продолжение работы и диагностика. -Краткий запуск из корня репозитория: +Для одного учащегося рекомендуем компьютер с 16 ГБ RAM, не менее 4 CPU и +10 ГБ памяти, доступных Docker, а также от 20 ГБ свободного места перед сборкой. +Подробности и границы проверки — в [системных требованиях](./START_HERE.md#системные-требования). + +Краткий запуск из корня репозитория после подготовки по `START_HERE`: ```bash docker compose pull minio minio-init postgres trino docker compose build docker compose up -d -docker compose ps +docker compose ps -a ``` MinIO скачивается готовым из GHCR, его версия и digest закреплены. Если какой-то @@ -96,7 +102,8 @@ Python и venv не нужны. Оба интерфейса доступны т ## Документы для прохождения -- [START_HERE.md](./START_HERE.md) — первый маршрут: prerequisites, запуск, диагностика. +- [START_HERE.md](./START_HERE.md) — подготовка компьютера, запуск и первый результат. +- [docs/study_workflow.md](./docs/study_workflow.md) — памятка для каждого занятия и помощь при ошибках. - [docs/course_program.md](./docs/course_program.md) — модульная структура и состав учебных материалов. - [docs/stack_reference.md](./docs/stack_reference.md) — порты, команды, конфиги, шпаргалка. - [docs/glossary.md](./docs/glossary.md) — справочник терминов (storage, catalog, compute, snapshot и др.). diff --git a/START_HERE.md b/START_HERE.md index 325fbe7..9fed560 100644 --- a/START_HERE.md +++ b/START_HERE.md @@ -1,39 +1,82 @@ # START HERE -Этот документ нужен для первого входа в курс: поднять стенд, проверить сервисы, открыть интерфейсы, выполнить базовый smoke test и подготовить локальный data bundle для следующих модулей. +Здесь ты подготовишь окружение и выполнишь первое вычисление в Spark. +К концу запуска в ноутбуке появится `Spark cluster smoke test passed.`, а результат +сохранится в файле на твоем компьютере. Smoke test — короткая проверка, что +основные компоненты работают вместе. + +Если стенд уже собран, открой [памятку для следующего занятия](./docs/study_workflow.md). +Она объясняет, как продолжить работу, что сохраняется и куда смотреть при ошибках. ## Маршрут прохождения -1. Проверить prerequisites. -2. Собрать и поднять стенд. -3. Убедиться, что контейнеры живы. -4. Открыть основные UI. -5. Открыть VS Code в браузере и выполнить `notebooks/01_environment_and_smoke_test.ipynb`. -6. Перед Модулем 3 подготовить учебный датасет в `./data/nyc_taxi`. -7. При проблемах использовать логи и шаги диагностики из этого документа. +1. Подготовь Docker, ресурсы и локальную копию репозитория. +2. Скачай образы, собери окружение и проверь запуск сервисов. +3. Открой первый ноутбук в браузерном VS Code и проверь результат вычисления. +4. Продолжи по [программе курса](./docs/course_program.md#маршрут-по-модулям). -## Prerequisites +Датасет Taxi понадобится перед Модулем 3, DBeaver необязателен и понадобится +только перед Модулем 6. Для первого ноутбука их готовить не нужно. -Нужно заранее установить: + -- Docker; -- Docker Compose 2.17+ с BuildKit (`docker compose version`); -- современный браузер для UI; -- свободные порты на хосте. +## Что подготовить -Рекомендуемые ресурсы хоста: +- Docker с запущенным движком и Docker Compose 2.17+ с BuildKit. +- Современный браузер; основной интерфейс курса — VS Code на `localhost:8889`. +- Git для скачивания репозитория или его распакованную ZIP-копию. +- Свободные порты из таблицы ниже и доступ к источникам образов и зависимостей. -- не менее `4 vCPU`; -- не менее `10 GB RAM`, иначе `Spark`, `Trino` и IDE могут стартовать нестабильно; -- хотя бы `20 GB` свободного места под образы, кэш первой сборки и контейнеры. +Команды ниже рассчитаны на Bash: терминал Linux/macOS или терминал Linux +в WSL2 на Windows с включенной интеграцией Docker Desktop. Выполняй их на +машине, где работает Docker. Терминал внутри браузерного VS Code для запуска +`docker compose` не подходит. -Python, Java, Jupyter и расширения VS Code устанавливаются при сборке Docker-образов. -На хосте не нужно создавать venv или устанавливать Python-пакеты. +### Системные требования -Для первой сборки нужен доступ к внешним репозиториям. Если ты работаешь из РФ -или сети с ограничениями, при ошибке скачивания используй -[инструкцию по доступу к репозиториям](./docs/network_access.md): в ней есть -резервный источник MinIO и отдельные шаги для Docker и сборки зависимостей. +Ориентир для одного учащегося и основного набора Taxi за три месяца: + +| Ресурс | Рекомендация | Что проверить | +| --- | --- | --- | +| Процессор | Не менее 4 CPU, доступных Docker | В Docker Desktop/WSL2 может стоять меньший лимит | +| Память Docker | Не менее 10 ГБ RAM | Это память для контейнеров, а не общий объем памяти компьютера | +| Память компьютера | 16 ГБ RAM или больше | Оставь память ОС, браузеру и другим приложениям | +| Свободное место | Не менее 20 ГБ перед первой сборкой; 30 ГБ с запасом | На диске Docker и в папке репозитория: образы, кэш сборки, исходные данные и таблицы | + +Это рекомендуемый бюджет, а не измеренный минимальный порог. Полный курс на +машине с 8 ГБ RAM не проверен. В Docker Desktop проверь +[лимиты ресурсов](https://docs.docker.com/desktop/settings-and-maintenance/settings/#resources); +для режима WSL2 лимиты задаются у виртуальной машины WSL2. Место внутри диска +Docker и свободное место на диске компьютера — отдельные ограничения. + +С добавлением VS Code образ окружения вырос примерно на 1,2 ГБ относительно +Jupyter; базовые слои у них общие. MinIO скачивается готовым, компилировать его +не нужно. [Основания оценок и границы проверки](./docs/stack_reference.md#ресурсы-и-проверенная-среда). + +Python, Java, Jupyter и расширения VS Code устанавливаются при сборке образов. +На компьютере не нужно создавать venv или устанавливать Python-пакеты. + +Для первой сборки нужен интернет. Если ты работаешь из РФ или сети с +ограничениями, при ошибке скачивания используй +[инструкцию по доступу к репозиториям](./docs/network_access.md). Она различает +проблемы скачивания образов и зависимостей внутри сборки. + +### Проверка до сборки + +Открой терминал в папке репозитория — там, где лежит `docker-compose.yml`: + +```bash +docker version +docker compose version +docker info --format 'CPUs={{.NCPU}} MemoryBytes={{.MemTotal}}' +docker compose config --quiet +``` + +В `docker version` должны быть разделы Client и Server, версия Compose — не +ниже 2.17. `docker info` показывает ресурсы, которые видит Docker; память дана +в байтах (10 ГБ — примерно 10 000 000 000 байт). Последняя команда при успехе +ничего не печатает. Если Docker не отвечает или конфигурация не читается, +исправь эту ошибку до сборки. ## Порты стенда @@ -53,14 +96,26 @@ Python, Java, Jupyter и расширения VS Code устанавливают Все команды выполняются из корня репозитория. -На Linux пользователь контейнера должен иметь доступ к файлам ноутбуков. Если -твой UID отличается от `1000`, перед сборкой задай его в текущем терминале: +На Linux и в WSL2 проверь владельца файлов: ```bash -export NB_UID=$(id -u) NB_GID=$(id -g) +id -u +id -g ``` -Для Docker Desktop на macOS и Windows обычно подходят значения по умолчанию. +Это UID и GID — числовые идентификаторы пользователя и группы. В контейнере по +умолчанию используются `1000` и `100`. Если значения отличаются, до сборки +создай `.env` в корне репозитория и укажи `NB_UID` и `NB_GID` со своими числами. +Например, для вывода `1001` и `1001`: + +```dotenv +NB_UID=1001 +NB_GID=1001 +``` + +Если `.env` уже есть, измени только эти строки, сохранив остальные настройки. +Файл остается между занятиями. Образец — [`.env.example`](./.env.example). +На macOS с Docker Desktop обычно подходят значения по умолчанию. ### 1. Скачать готовые образы и собрать окружение @@ -71,7 +126,8 @@ docker compose build Первая команда проверяет загрузку готовых сервисов до сборки окружения. MinIO уже собран; для Spark, Jupyter и IDE первая сборка скачивает зависимости -и может занять несколько минут. Повторная сборка использует кэш Docker. +и зависит по времени от сети и компьютера. Дождись завершения без ошибок; +не переходи к запуску после неудачной сборки. Повторная сборка использует кэш Docker. ### 2. Поднять стенд @@ -82,33 +138,36 @@ docker compose up -d ### 3. Проверить статус контейнеров ```bash -docker compose ps +docker compose ps -a ``` Ожидаемое состояние: -- контейнеры `spark-master`, `spark-worker-1`, `spark-worker-2`, `minio`, `postgres-iceberg`, `trino`, `jupyter`, `ide` находятся в состоянии `Up`, у `ide` появляется статус `healthy`; -- однократные init-контейнеры вроде `minio-init` и `iceberg-catalog-init` могут завершиться после успешной инициализации. +- `spark-master`, `spark-worker-1`, `spark-worker-2`, `minio`, `postgres-iceberg`, + `trino`, `jupyter`, `ide` работают (`Up`); у `postgres-iceberg`, `trino` и `ide` + дождись `healthy`; +- `minio-init` и `iceberg-catalog-init` заканчивают работу со статусом `Exited (0)`. + Это успешная разовая подготовка хранилища и каталога. `Exited (1)` и другой + ненулевой код требуют проверки логов. + +Флаг `-a` показывает и завершившиеся контейнеры. Сам по себе статус `Up` еще +не доказывает, что вычисления работают: дальше проверим их в ноутбуке. ## Куда заходить после старта -Открой в браузере: +| Что открыть | Что должно быть видно | +| --- | --- | +| [Spark Master](http://localhost:8080) | Два worker-а в состоянии `ALIVE` | +| [MinIO Console](http://localhost:9001) | После входа `minioadmin` / `minioadmin` виден бакет `lakehouse` — контейнер для файлов курса | +| [VS Code](http://localhost:8889) | Слева папки **Ноутбуки**, **Примеры (только чтение)**, **Документация (только чтение)** | -- `http://localhost:8080` для `Spark Master UI`; -- `http://localhost:8090` для `Trino UI`; -- `http://localhost:9001` для `MinIO Console`; -- `http://localhost:8889` для `VS Code в браузере`. +В [Trino UI](http://localhost:8090) для входа достаточно имени, например `student`; +пароль в стенде не задан. Сейчас достаточно проверить, что интерфейс открывается. +Чтение общих таблиц через Trino разберем в Модуле 6. -Для входа в `MinIO Console` используй: - -- логин: `minioadmin`; -- пароль: `minioadmin`. - -Если интерфейсы открываются, переходи в VS Code и запускай: - -```text -notebooks/01_environment_and_smoke_test.ipynb -``` +Этот маршрут предполагает Docker на твоем компьютере: `localhost` относится +к машине с браузером. Доступ к VS Code на удаленном сервере описан отдельно +в [инструкции по SSH-туннелю](./docs/stack_reference.md#vs-code-в-браузере). ## Роли сервисов в стенде @@ -122,6 +181,9 @@ notebooks/01_environment_and_smoke_test.ipynb ## Как работать с ноутбуками +Ноутбук — файл с пояснениями, кодом и сохраненным выводом. Ядро — процесс Python, +который исполняет код и хранит переменные до остановки. + 1. Открой `http://localhost:8889` в отдельной вкладке браузера. 2. Если сверху виден **Restricted Mode**, нажми **Manage → Trust** и закрой окно Workspace Trust. Подтверди доверие только к своей копии этого учебного @@ -131,83 +193,60 @@ notebooks/01_environment_and_smoke_test.ipynb `/usr/bin/python3`. Он находится внутри контейнера `ide`, где уже есть зависимости курса. Пункт **Existing Jupyter Server** здесь не нужен. 5. Запусти первую кодовую ячейку кнопкой слева или `Shift+Enter`, затем остальные - ячейки по порядку. Результат появится под ячейкой. Сохрани ноутбук через `Ctrl+S`. + ячейки по порядку. Результат появится под ячейкой. Сохрани ноутбук через + **File → Save** (`Ctrl+S`; на macOS — `Cmd+S`). Терминал VS Code тоже работает внутри контейнера. Команды `docker compose` выполняй в терминале хоста, откуда запускал стенд. -Файлы доступны в IDE так: +### Как понять, что первый запуск прошел -- `./notebooks` смонтирован в контейнер как `/opt/work`; -- `./src` смонтирован read-only как `/opt/src`; -- весь репозиторий доступен read-only в `/opt/course`; его папка `notebooks/` - доступна для записи, поэтому правки из IDE сохраняются на хосте; -- `./data` смонтирован read-only как `/opt/data`; -- `PYTHONPATH=/opt/src`, поэтому helper-скрипты из `src/` доступны для импорта в ноутбуках; -- учебный data bundle для Модуля 3 доступен по пути `/opt/data/nyc_taxi`. +В третьей кодовой ячейке первого ноутбука появится отчет, содержащий: + +```text +Spark cluster smoke test passed. +master_url=spark://spark-master:7077 +result_sum=499999500000 +expected_sum=499999500000 +``` + +В отчете есть и другие строки; значения выше должны совпасть. Затем выполни +самостоятельное задание: замени `TODO` в словаре `service_roles` ролями сервисов. +Сам факт запуска ячейки с `TODO` не означает, что задание выполнено. + +В конце выполни ячейку `spark.stop()`, сохрани ноутбук и проверь, что его изменения +видны в `notebooks/01_environment_and_smoke_test.ipynb` на хосте. После повторного +открытия сохраненный вывод остается виден. Такой вывод — запись прошлого запуска; +он не означает, что ядро Python и Spark-сессия продолжают работать. + +Правила запуска ячеек, перехода между модулями и сохранения данных собраны в +[памятке учащегося](./docs/study_workflow.md). Запасной интерфейс — JupyterLab на `http://localhost:8888`. Файлы ноутбуков общие, -а ядра и переменные Python отдельные. Перед переходом сохрани ноутбук и останови -его ядро. Подключение с удалённой машины описано в -[техническом reference](./docs/stack_reference.md#vs-code-в-браузере). - -Ноутбуки берут адрес кластера из -[`spark/spark-defaults.conf`](./spark/spark-defaults.conf). Если изменил его, -перезапусти ядро и заново создай Spark-сессию. Повторный запуск ячейки с -`getOrCreate()` использует текущую сессию. При перезапуске ядра переменные Python -сбрасываются, а учебные таблицы и файлы сохраняются. +а ядра и переменные Python отдельные. Перед переходом сохрани ноутбук и заверши +Spark-сессию через `spark.stop()`; не редактируй один файл в двух интерфейсах +одновременно. ## Базовая диагностика -### Посмотреть список контейнеров +Начни с `docker compose ps -a` и логов проблемного сервиса, например: ```bash -docker compose ps +docker compose logs --tail=100 ide ``` -### Посмотреть логи конкретного сервиса - -```bash -docker compose logs -f spark-master -docker compose logs -f trino -docker compose logs -f minio -docker compose logs -f jupyter -docker compose logs -f ide -``` - -### Типовые первые проверки - -- Ошибка скачивания образа или зависимостей: найди имя недоступного источника - в сообщении и открой [диагностику сети](./docs/network_access.md). -- `Spark UI` не открывается: проверь `docker compose ps` и логи `spark-master`. -- `Trino UI` не открывается: проверь `docker compose ps` и логи `trino`. -- `JupyterLab` не открывается: проверь `docker compose ps` и логи `jupyter`. -- VS Code не открывается: проверь `docker compose ps ide` и логи `ide`. -- Вместо ноутбука ошибка webview/service worker: открой `http://localhost:8889` - в отдельной вкладке, без IP сервера и без встраивания в другой сайт. -- Ядро не выбирается: убедись, что рабочая область доверенная, и выбери - `/usr/bin/python3` в **Python Environments**. Для подробностей открой - **View → Output → Jupyter**. -- `MinIO Console` не открывается: проверь `docker compose ps` и логи `minio`. -- smoke test падает из ноутбука: сначала убедись, что `spark-master` и worker-ы видны в `Spark UI`. +Выбери свой симптом в [таблице диагностики](./docs/study_workflow.md#если-что-то-не-работает). +При ошибке скачивания сразу открой [диагностику сети](./docs/network_access.md). ## Restart и reset -### Мягкий перезапуск стенда +Для обычной паузы используй `docker compose stop`, на следующем занятии — +`docker compose up -d`. Порядок действий и последствия удаления контейнеров +описаны в [памятке](./docs/study_workflow.md#закончить-занятие). -```bash -docker compose down -docker compose up -d -``` - -### Полный reset с удалением данных - -```bash -docker compose down -v -docker compose up -d -``` - -Используй полный reset, если хочешь пройти практику заново с чистого состояния. +Полный сброс удаляет учебные таблицы и каталог. Его команда вынесена в +[отдельный раздел](./docs/study_workflow.md#начать-с-чистых-данных), чтобы не путать +с окончанием занятия. ## Подготовка учебного датасета (перед Модулем 3) @@ -216,6 +255,7 @@ docker compose up -d Скачай каноническое учебное подмножество `NYC TLC Yellow Taxi Trip Records`: ```bash +mkdir -p data/nyc_taxi curl -fLo data/nyc_taxi/yellow_tripdata_2024-01.parquet \ https://d37ci6vzurychx.cloudfront.net/trip-data/yellow_tripdata_2024-01.parquet curl -fLo data/nyc_taxi/yellow_tripdata_2024-02.parquet \ @@ -246,13 +286,12 @@ ls -lh data/nyc_taxi/ - Зачем: в Модуле 6 можно работать с Trino через DBeaver параллельно с ноутбуком — привычный SQL-интерфейс. - Предусловие: DBeaver установлен (ссылка на [dbeaver.io/download](https://dbeaver.io/download/)). Необязателен — ноутбук работает без DBeaver. - Шаги: New Database Connection -> Trino. Host: `localhost`. Port: `8090`. Database/Catalog: `lakehouse`. Username: любая строка (напр. `student`). Password: пусто. Test Connection -> Finish. -- Проверка: `SHOW SCHEMAS FROM lakehouse;`. Ожидаем: `bronze`, `default`, `information_schema`, `silver`. +- Проверка: `SHOW SCHEMAS FROM lakehouse;`. После модулей 4–5 должны быть видны `bronze` и `silver`; до их прохождения этих схем может еще не быть. - Troubleshooting: стенд поднят? контейнер `trino` Up? порт 8090 свободен? ## Что делать дальше -- пройти `notebooks/01_environment_and_smoke_test.ipynb`; -- пройти `notebooks/02_lakehouse_mental_model.ipynb`; -- подготовить data bundle по инструкции выше и пройти `notebooks/03_raw_ingest_and_first_read.ipynb`; -- свериться с программой курса в `docs/course_program.md`; -- после прохождения первых модулей переходить к следующим учебным материалам. +После первого ноутбука открой [маршрут по модулям](./docs/course_program.md#маршрут-по-модулям). +В нем есть ссылки на все восемь уроков и результат, который нужно получить +перед переходом дальше. Для следующего занятия сохрани ссылку на +[памятку учащегося](./docs/study_workflow.md). diff --git a/docs/course_program.md b/docs/course_program.md index 74602b4..6f9802c 100644 --- a/docs/course_program.md +++ b/docs/course_program.md @@ -1,6 +1,29 @@ # Программа учебного курса: Lakehouse без магии -Этот документ заменяет предыдущий черновой план и выравнивает программу с PRD из [course_prd.md](./course_prd.md). +Здесь собраны порядок модулей, ссылки на ноутбуки и результаты, по которым можно +проверить свою работу. Рамки курса и learning outcomes описаны в [course_prd.md](./course_prd.md). + +## Маршрут по модулям + +Перед первым уроком подготовь стенд по [START_HERE](../START_HERE.md). +Дальше проходи ноутбуки по порядку: файлы и таблицы из ранних модулей нужны в +следующих. Пауза между занятиями описана в [памятке учащегося](./study_workflow.md). + +| Модуль и ноутбук | Что понадобится | Результат перед переходом дальше | +| --- | --- | --- | +| [1. Вход в стенд](../notebooks/01_environment_and_smoke_test.ipynb) | Работающий стенд | Smoke test вернул `499999500000`; ты можешь показать два worker-а и объяснить роли сервисов | +| [2. Модель Lakehouse](../notebooks/02_lakehouse_mental_model.ipynb) | Модуль 1 | Ты нашел файлы демо-таблицы в MinIO и запись каталога в PostgreSQL; выполнил очистку демо по ноутбуку | +| [3. Исходные данные](../notebooks/03_raw_ingest_and_first_read.ipynb) | [Четыре файла Taxi](../START_HERE.md#подготовка-учебного-датасета-перед-модулем-3) на хосте | Файлы загружены в raw-зону MinIO, Spark читает их; проверены схема и основные метрики | +| [4. Bronze и Iceberg](../notebooks/04_bronze_with_iceberg.ipynb) | Raw-файлы из Модуля 3 | Созданы bronze-таблица поездок и таблица зон из самостоятельного задания; видны их данные и metadata-файлы | +| [5. Silver](../notebooks/05_silver_layer.ipynb) | Обе bronze-таблицы | Создана silver-таблица, проверены правила очистки и качество результата | +| [6. Spark и Trino](../notebooks/06_spark_and_trino_on_same_table.ipynb) | Silver из Модуля 5; DBeaver по желанию | Одна таблица читается обоими движками; ты можешь объяснить, какие компоненты у них общие | +| [7. Изменения таблиц](../notebooks/07_safe_table_changes.ipynb) | Результаты предыдущих модулей | На демо-таблице проверены изменение схемы, чтение прошлого состояния и rollback; silver сохранена | +| [8. Обслуживание и финальная практика](../notebooks/08_maintenance_and_final_lab.ipynb) | Raw, bronze и silver | Проверено обслуживание таблиц; самостоятельно пройден поток от исходных файлов до чтения и проверок результата | + +В каждом ноутбуке сначала прочитай объяснение, затем выполни демонстрацию и +самостоятельное задание. Checkpoint в конце урока — вопросы и проверки для +самопроверки. Сохраненный вывод помогает вернуться к результату, но не заменяет +собственный запуск и объяснение. ## 1. Рамка курса @@ -40,7 +63,9 @@ * пошаговый гайд по запуску стенда: `build`, `up`, проверка сервисов, открытие UI; * краткое объяснение, как запускать Jupyter-ноутбуки в браузерном VS Code, где лежат ноутбуки и как читать структуру урока; * troubleshooting по типовым проблемам старта; -* инструкция по reset/restart стенда для повторного прохождения практик. +* [памятка учащегося](./study_workflow.md): продолжение занятия, сохранение данных, + перезапуск ядра и диагностика; +* отдельная инструкция по сбросу учебных данных для повторного прохождения практик. **Что должен закрывать этот слой:** @@ -85,7 +110,7 @@ **Содержание:** -* запуск `docker compose build` и `docker compose up -d`; +* скачивание готовых образов, сборка окружения и запуск по `START_HERE.md`; * проверка сервисов и веб-интерфейсов; * базовый smoke test для Spark; * первый обзор того, где в стенде `MinIO`, `PostgreSQL`, `Spark`, `Trino` и IDE. diff --git a/docs/maintainer_guide.md b/docs/maintainer_guide.md index ca011c1..ee2d768 100644 --- a/docs/maintainer_guide.md +++ b/docs/maintainer_guide.md @@ -34,6 +34,7 @@ | `spark/`, `trino/`, `jupyter/`, `ide/` | Конкретные runtime-конфиги и образы | Описание программы курса | | `README.md` | Верхнеуровневое объяснение репозитория, архитектуры и точек входа | Пошаговый student onboarding во всех деталях и low-level runtime reference | | `START_HERE.md` | Первый маршрут студента: prerequisites, запуск, первые UI, первый ноутбук, базовая диагностика | Полный PRD курса или подробный бэклог модулей | +| `docs/study_workflow.md` | Повседневный маршрут: продолжить и закончить занятие, сохранить результат, восстановиться после ошибки | Состав модулей, установка окружения с нуля | | `docs/stack_reference.md` | Технический reference стенда: сервисы, порты, доступ, reset, smoke-тесты | Роль основного onboarding-документа или описание всей программы курса | | `docs/course_prd.md` | Product scope, аудитория, learning outcomes, dataset strategy, out of scope | Технические мелочи запуска контейнеров | | `docs/course_program.md` | Модульная структура курса, состав материалов, checkpoints | Подробные docker-команды и legacy-лабы | @@ -75,6 +76,7 @@ - `START_HERE.md`; - `docs/course_program.md`; +- `docs/study_workflow.md`; - соответствующие `notebooks/`; - `README.md`, если меняется верхнеуровневый вход в репозиторий. diff --git a/docs/mentor_notes.md b/docs/mentor_notes.md index 2bafb70..8df920c 100644 --- a/docs/mentor_notes.md +++ b/docs/mentor_notes.md @@ -17,9 +17,9 @@ | Модуль | Тема | Самостоятельная работа | Обсуждение с ментором | Комментарий | | --- | --- | --- | --- | --- | -| 1 | Вход в стенд | 30-40 мин | 10-15 мин | Если Docker знаком, идёт быстро | +| 1 | Вход в стенд | 30-40 мин | 10-15 мин | Без учета первой сборки: ее время зависит от сети и компьютера | | 2 | Ментальная модель | 40-60 мин | 15-20 мин | Ключевой модуль; убедись, что студент заходил в MinIO | -| 3 | Raw-данные | 40-50 мин | 10 мин | Зависит от скорости загрузки данных | +| 3 | Raw-данные | Около 2 часов | 10 мин | Включая 20–30 минут на практику со Spark-сессией; датасет скачивается заранее | | 4 | Bronze + Iceberg | 60-80 мин | 15-20 мин | Первая таблица — много новых концепций | | 5 | Silver | 50-70 мин | 15 мин | Трансформации + проверки качества | | 6 | Spark + Trino | 40-60 мин | 15 мин | Если DBeaver настроен заранее — быстрее | @@ -34,8 +34,9 @@ ### Модуль 1. Вход в стенд -- **Docker не хватает ресурсов.** Сверься с [требованиями в START_HERE](../START_HERE.md#prerequisites). Проверь отдельно память компьютера и лимит памяти Docker Desktop/WSL2: контейнерам может быть доступна лишь часть RAM хоста. -- **Порты заняты.** Проверь 8080, 8889, 9000 и остальные [порты стенда](../START_HERE.md#порты-стенда). `docker compose ps` покажет, какой сервис не стартовал. Решение: остановить конфликтующий процесс или (крайний вариант) поменять порт в `docker-compose.yml`. +- **Docker не хватает ресурсов.** Сверься с [системными требованиями](../START_HERE.md#системные-требования). Проверь отдельно память компьютера и лимит памяти Docker Desktop/WSL2: контейнерам может быть доступна лишь часть RAM хоста. +- **После паузы виден старый вывод, но переменные пропали.** Разбери разницу между файлом ноутбука и ядром Python по [памятке учащегося](./study_workflow.md). Передай студенту ее до второго занятия; для обращения за помощью там есть список нужных сведений. +- **Порты заняты.** Проверь 8080, 8889, 9000 и остальные [порты стенда](../START_HERE.md#порты-стенда). `docker compose ps -a` покажет, какой сервис не стартовал. Решение: остановить конфликтующий процесс или (крайний вариант) поменять порт в `docker-compose.yml`. - **Студент не читает `START_HERE.md`.** Начинает с ноутбуков до поднятия стенда. Направь обратно к стартовому документу. ### Модуль 2. Ментальная модель diff --git a/docs/stack_reference.md b/docs/stack_reference.md index 105ff17..84f97cd 100644 --- a/docs/stack_reference.md +++ b/docs/stack_reference.md @@ -20,14 +20,17 @@ ## Основные команды -Все команды выполняются из корня репозитория. +Все команды выполняются в терминале хоста из корня репозитория. +Для первого запуска и настройки прав используй [START_HERE](../START_HERE.md), +для продолжения работы — [памятку учащегося](./study_workflow.md). ### Сборка и запуск ```bash +docker compose pull minio minio-init postgres trino docker compose build docker compose up -d -docker compose ps +docker compose ps -a ``` ### Логи @@ -42,12 +45,36 @@ docker compose logs -f ide ### Остановка и reset -```bash -docker compose down -docker compose down -v -``` +| Действие | Команда | Что происходит с данными | +| --- | --- | --- | +| Пауза до следующего занятия | `docker compose stop` | Контейнеры остановлены, файлы и volumes сохранены | +| Продолжение | `docker compose up -d` | Сервисы запускаются с прежними данными | +| Удаление контейнеров и сети | `docker compose down` | Volumes и файлы на хосте сохраняются, состояние внутри удаленных контейнеров теряется | +| Полный сброс учебных данных | См. [отдельную инструкцию](./study_workflow.md#начать-с-чистых-данных) | Удаляются MinIO volume и каталог PostgreSQL | -`down -v` удаляет volumes и возвращает стенд в чистое состояние. +Переменные Python и живые Spark-сессии после остановки нужно создать заново. + +## Ресурсы и проверенная среда + +Актуальный бюджет для учащегося приведен в +[системных требованиях](../START_HERE.md#системные-требования). +Он учитывает одновременную работу двух Spark worker-ов, драйвера в IDE, Trino, +MinIO и PostgreSQL. У каждого worker-а в Compose указаны 2 CPU и 2 ГБ для +приложений Spark; это не предел потребления всей JVM или контейнера. +Потребление при простое не показывает пик во время урока. + +Проверка 19 октября 2026 года: Linux x86_64, Docker Engine, 6 CPU и около +11,1 ГиБ памяти, видимых Docker. Выполнены первый ноутбук в Chromium и проверка +Spark → Iceberg → Trino. Прогона всех восьми модулей с измерением пиков памяти +и диска не было; минимальный объем RAM не установлен. Docker Desktop и ARM64 +в этой проверке не запускались. + +Размеры локально собранных образов на этой машине: Spark — около 3,37 ГБ, +Jupyter — 3,72 ГБ, IDE — 4,90 ГБ. Jupyter включает слои Spark, IDE включает слои +Jupyter: складывать эти три числа для оценки места неправильно. IDE добавляет +около 1,18 ГБ. IDE вместе с отдельными образами Trino, PostgreSQL и MinIO дает +около 8,1 ГБ до учета кэша сборки, данных и особенностей хранилища Docker. +Поэтому перед первой сборкой нужен запас места сверх размера готовых образов. ## Доступ к сервисам @@ -218,6 +245,7 @@ JupyterLab остаётся запасным интерфейсом. Он ред | `ide/Dockerfile` | code-server и расширения на базе образа Jupyter | | `ide/lakehouse.code-workspace` | папки рабочей области и настройки Python | | `docs/network_access.md` | источники образов и зависимостей, резервный registry и диагностика сети | +| `docs/study_workflow.md` | повседневная работа, сохранение состояния и диагностика ошибок | ## Smoke-тесты @@ -336,6 +364,7 @@ SELECT * FROM FOR VERSION AS OF ; - `README.md` — чтобы понять, что это за репозиторий и куда идти дальше. - `START_HERE.md` — чтобы впервые поднять стенд и пройти Модуль 1. +- `study_workflow.md` — чтобы продолжить занятие, сохранить результат и разобраться с ошибкой. - `stack_reference.md` — чтобы быстро вспомнить порты, команды, точки доступа, шпаргалку и smoke-тесты. - `course_program.md` — чтобы понять учебную траекторию дальше первого модуля. - `glossary.md` — чтобы вернуться к определению термина (storage, catalog, compute, snapshot и др.). diff --git a/docs/study_workflow.md b/docs/study_workflow.md new file mode 100644 index 0000000..273b8d1 --- /dev/null +++ b/docs/study_workflow.md @@ -0,0 +1,153 @@ +# Как заниматься со стендом + +Для первой сборки используй [START_HERE](../START_HERE.md), для выбора урока — +[маршрут по модулям](./course_program.md#маршрут-по-модулям). Эта памятка нужна, +когда окружение уже готово. + +## Начать следующее занятие + +1. Запусти Docker и открой терминал хоста в той же папке репозитория. +2. Выполни: + + ```bash + docker compose up -d + docker compose ps -a + ``` + + Дождись `healthy` у `ide`, `trino` и `postgres-iceberg`. У двух init-контейнеров + нормальное состояние — `Exited (0)`. Повторять сборку перед каждым занятием + не нужно; она понадобится после изменения образов или зависимостей. +3. Открой [VS Code в браузере](http://localhost:8889) и нужный ноутбук. + При запросе ядра выбери **Select Kernel → Python Environments → /usr/bin/python3**. +4. После остановки стенда переменные Python нужно создать заново: выполни + импорты, создание Spark-сессии и подключений в начале текущего ноутбука. + Сохраненный вывод ячеек может быть виден еще до их запуска. +5. Продолжи с места, на котором остановился. Перед повтором ячеек с записью + данных, `INSERT`, `CREATE OR REPLACE`, `DROP` или очисткой истории прочитай + пояснение: повторный запуск может изменить таблицу или создать новый snapshot. + +Используй прежнюю папку репозитория: имя Compose-проекта определяет, какие +Docker volumes подключаются. После переименования папки или запуска с другим +`-p` можно получить новый пустой набор данных вместо предыдущего. + +## Как проходить ноутбук + +Ноутбук состоит из пояснений и кодовых ячеек. Ядро Python выполняет код и хранит +переменные в памяти. Spark-сессия связывает этот Python-процесс с кластером. + +- Прочитай пояснение, запусти ячейку через `Shift+Enter`, дождись окончания и + сравни результат с описанием. Следующая ячейка может использовать предыдущие + переменные, поэтому порядок важен. +- В самостоятельном задании заполни `TODO` и проверь результат. **Run All** + запускает код, но не выполняет задание за тебя. +- Checkpoint — вопросы и проверки в конце урока. Покажи результат в своем + стенде и объясни его своими словами перед переходом к следующему модулю. +- Сохраняй изменения через **File → Save** (`Ctrl+S`; на macOS — `Cmd+S`). + Файл ноутбука вместе с ответами и выводом записывается в `notebooks/` на хосте. +- Перед следующим модулем выполни завершающую ячейку `spark.stop()`, если она + есть; иначе вызови `spark.stop()` после окончания вычислений. Это освобождает + ресурсы Spark для следующего приложения. Закрытие вкладки браузера само по + себе не останавливает вычисления. + +Держи одну активную Spark-сессию: если несколько ноутбуков одновременно занимают +все ядра worker-ов, новое задание может ждать ресурсы. Для своих SQL/Python-опытов +можно создать дополнительный ноутбук в папке **Ноутбуки**. `src/`, документация +и конфиги в IDE доступны только для чтения; их меняют в копии репозитория на хосте. + +### Если нужно перезапустить ядро + +Сначала сохрани ноутбук. В верхней панели нажми **Restart** и подтверди перезапуск. +Затем заново выполни импорты и создание Spark-сессии. Переменные Python исчезнут; +файлы и записанные учебные таблицы сохранятся. + +Перезапуск нужен, например, после изменения адреса кластера в +`spark/spark-defaults.conf` или после остановки Spark-сессии, с которой хочешь +продолжить работу. Повторный `getOrCreate()` при живой сессии использует ее; +подробнее это разбирается в Модуле 3. + +## Закончить занятие + +Сохрани ноутбук, дождись завершения вычислений и запиши для себя номер модуля +и следующую ячейку. Затем в терминале хоста выполни: + +```bash +docker compose stop +``` + +Контейнеры остановятся и освободят занятую ими оперативную память. Файлы +ноутбуков, исходные данные и таблицы останутся. На следующем занятии используй +`docker compose up -d` из начала этой памятки. + +## Что и где сохраняется + +Docker volume — хранилище вне файловой системы контейнера. В этом стенде два +таких хранилища: `minio-data` с объектами и `postgres-data` с каталогом Iceberg. +Имена volumes в Docker обычно имеют префикс Compose-проекта. + +| Что | Где находится | После `stop` или `down` без `-v` | +| --- | --- | --- | +| Код, ответы и сохраненный вывод ноутбуков | `notebooks/` на хосте; `/opt/work` и `/opt/course/notebooks` в IDE | Сохраняются | +| Скачанные Parquet и CSV | `data/nyc_taxi/` на хосте; `/opt/data/nyc_taxi` в контейнере | Сохраняются | +| Raw-файлы, данные и metadata-файлы Iceberg | Бакет `lakehouse`, volume `minio-data` | Сохраняются | +| Записи каталога Iceberg | PostgreSQL, volume `postgres-data` | Сохраняются | +| Переменные Python и живая Spark-сессия | Память процессов | Теряются; создай заново | +| Настройки IDE, доверие рабочей области | Файловая система контейнера `ide` | При `stop` сохраняются; при удалении или пересоздании контейнера могут сброситься | + +`docker compose down` удаляет контейнеры и сеть проекта. Именованные volumes +остаются, поэтому после `up -d` таблицы доступны снова. Для обычного окончания +занятия достаточно `stop`. Поведение команд описано также в документации Docker: +[stop](https://docs.docker.com/reference/cli/docker/compose/stop/), +[down](https://docs.docker.com/reference/cli/docker/compose/down/). + +### Начать с чистых данных + +Этот шаг нужен только для осознанного повторного прохождения с пустым +хранилищем. Он удалит оба volumes: raw-данные в MinIO, таблицы, их историю +и записи каталога PostgreSQL. Сохраненные ноутбуки и скачанные файлы в `data/` +на хосте останутся. + +```bash +docker compose down -v +docker compose up -d +``` + +После сброса в ноутбуках еще может быть старый вывод. Заново создай raw в +Модуле 3, bronze в Модуле 4 и silver в Модуле 5, прежде чем продолжать модули, +которые используют эти данные. Сброс не является способом исправить сеть +или выбор ядра. + +## Если что-то не работает + +Все `docker compose` команды ниже выполняются в терминале хоста из корня +репозитория. Имя сервиса для логов берется из колонки `SERVICE` в `ps`: +например, `postgres`, хотя контейнер называется `postgres-iceberg`. + +| Симптом | Первая проверка | Что сделать дальше | +| --- | --- | --- | +| Docker не отвечает | `docker version`: есть ли раздел Server? | Запусти Docker; при `permission denied` проверь доступ своего пользователя к Docker | +| Образ или зависимость не скачивается | Найди адрес источника и сервис в ошибке | Пройди [диагностику сети](./network_access.md) | +| `port is already allocated` / `address already in use` | Какой порт занят, не запущена ли другая копия стенда? | Освободи нужный порт; [список портов](../START_HERE.md#порты-стенда) | +| Сервис завершился, `unhealthy` или долго `starting` | `docker compose ps -a`, затем `docker compose logs --tail=100 ` | Для `postgres-iceberg` используй сервис `postgres`; проверь первую ошибку в логах | +| VS Code не открывается | `docker compose ps -a ide`, логи `ide` | Дождись `healthy`, открой `http://localhost:8889`; для сервера используй [SSH-туннель](./stack_reference.md#vs-code-в-браузере) | +| Ошибка notebook webview / service worker | Адрес в браузере и отдельная вкладка | Открой `http://localhost:8889`, без IP удаленного сервера и без встраивания в другой сайт | +| Не выбирается ядро, нет `pyspark` | Рабочая область доверенная? Выбран `/usr/bin/python3`? | Повтори [выбор ядра](../START_HERE.md#как-работать-с-ноутбуками); детали в **View → Output → Jupyter** | +| `NameError`, потерялась переменная | Ядро перезапускалось или выбран другой ноутбук? | Выполни импорты и подготовительные ячейки по порядку | +| Spark долго ждет, `Initial job has not accepted any resources` | В Spark UI два worker-а `ALIVE`? Есть другие приложения в `Running Applications`? | Заверши свою предыдущую сессию через `spark.stop()`; проверь логи worker-ов | +| Ядро умерло, контейнер убит, подозрение на память | `docker stats --no-stream`, лимит памяти Docker/WSL2 | Сверь [системные требования](../START_HERE.md#системные-требования), закрой другие вычисления; одного кода 137 недостаточно для вывода об OOM | +| Ноутбук не сохраняется (`Permission denied`) | Это файл в папке **Ноутбуки**? Совпадает UID? | Проверь `.env` и [настройку прав перед сборкой](../START_HERE.md#быстрый-запуск); после изменения UID/GID повтори `docker compose build`, затем `docker compose up -d` | +| Нет файлов Taxi или таблицы из прошлого модуля | Файлы в `data/nyc_taxi`, предыдущие модули, прежняя папка проекта | Для raw нужен Модуль 3, для bronze — 4, для silver — 5; после сброса восстанови их по порядку | + +### Что передать ментору + +Укажи ОС, модуль, ячейку или команду, ожидаемый результат и полный текст ошибки. +Приложи вывод: + +```bash +docker compose version +docker compose ps -a +docker compose logs --tail=100 ide +``` + +В последней команде замени `ide` на проблемный сервис, если ошибка в другом компоненте. +Для ошибки ноутбука добавь выбранный путь Python и вывод ячейки. Пароли, токены +и адреса прокси с учетными данными в сообщение не включай. diff --git a/notebooks/01_environment_and_smoke_test.ipynb b/notebooks/01_environment_and_smoke_test.ipynb index bfafc9d..8880453 100644 --- a/notebooks/01_environment_and_smoke_test.ipynb +++ b/notebooks/01_environment_and_smoke_test.ipynb @@ -15,7 +15,7 @@ "- подключиться к Spark-кластеру из ноутбука;\n", "- выполнить базовый smoke test;\n", "- сопоставить сервисы стенда с их ролями;\n", - "- знать первый маршрут диагностики через `docker compose ps`, логи и UI.\n" + "- знать первый маршрут диагностики через `docker compose ps -a`, логи и UI.\n" ] }, { @@ -25,9 +25,10 @@ "source": [ "## Перед стартом\n", "\n", - "Перед запуском этого ноутбука пройди шаги из `START_HERE.md`.\n", + "Если стенд еще не готов, выполни подготовку и запуск по [START_HERE](../START_HERE.md#быстрый-запуск).\n", + "Если возвращаешься после паузы, используй [памятку учащегося](../docs/study_workflow.md).\n", "\n", - "Важно: `docker compose build`, `docker compose up -d`, `docker compose ps` и просмотр логов выполняются в терминале хоста; терминал браузерного VS Code работает внутри контейнера.\n", + "Важно: `docker compose build`, `docker compose up -d`, `docker compose ps -a` и просмотр логов выполняются в терминале хоста; терминал браузерного VS Code работает внутри контейнера.\n", "\n", "Ожидаемое состояние перед началом:\n", "\n", @@ -149,7 +150,7 @@ "1. Открой `Spark UI`, `Trino UI`, `MinIO Console` и браузерный VS Code.\n", "2. Сопоставь каждый сервис с одной из ролей: `storage`, `catalog`, `compute`, `entrypoint`.\n", "3. Объясни, почему этот smoke test не должен работать в `local[*]` режиме.\n", - "4. На хосте выполни `docker compose ps` и посмотри, какие контейнеры должны быть в состоянии `Up`.\n", + "4. На хосте выполни `docker compose ps -a` и посмотри, какие контейнеры должны быть в состоянии `Up`.\n", "5. На хосте выполни `docker compose logs -f trino` или `docker compose logs -f spark-master`, чтобы посмотреть, где начинается первичная диагностика.\n" ] }, @@ -182,9 +183,13 @@ "\n", "- стенд поднят и основные контейнеры живы;\n", "- `Spark UI`, `MinIO Console`, `Trino UI` и браузерный VS Code открываются;\n", - "- smoke test завершился успешно и вернул ожидаемый результат;\n", + "- smoke test напечатал `Spark cluster smoke test passed.` и `result_sum=499999500000`;\n", "- ты понимаешь назначение `MinIO`, `PostgreSQL`, `Spark`, `Trino` и IDE;\n", - "- ты знаешь, что первый маршрут диагностики начинается с `docker compose ps`, `docker compose logs -f ` и проверки UI.\n" + "- ты знаешь, что первый маршрут диагностики начинается с `docker compose ps -a`, `docker compose logs -f ` и проверки UI.\n", + "\n", + "После последней ячейки `spark.stop()` сохрани ноутбук. Дальше — [Модуль 2](./02_lakehouse_mental_model.ipynb)\n", + "или [завершение занятия](../docs/study_workflow.md#закончить-занятие).\n", + "Все уроки собраны в [маршруте по модулям](../docs/course_program.md#маршрут-по-модулям)." ] }, {