mini-lakehouse-lab/docs/study_workflow.md

Как заниматься со стендом

Для первой сборки используй START_HERE, для выбора урока — маршрут по модулям. Эта памятка нужна, когда окружение уже готово.

Начать следующее занятие

1. Запусти Docker и открой терминал хоста в той же папке репозитория.

2. Выполни:

   docker compose up -d
   docker compose ps -a
   

   Дождись healthy у ide, trino и postgres-iceberg. У двух init-контейнеров нормальное состояние — Exited (0). Повторять сборку перед каждым занятием не нужно; она понадобится после изменения образов или зависимостей.

3. Открой JupyterLab и нужный ноутбук в списке файлов слева. При запросе ядра выбери Python 3 (ipykernel).

4. После остановки стенда переменные Python нужно создать заново: выполни импорты, создание Spark-сессии и подключений в начале текущего ноутбука. Сохраненный вывод ячеек может быть виден еще до их запуска.

5. Продолжи с места, на котором остановился. Перед повтором ячеек с записью данных, INSERT, CREATE OR REPLACE, DROP или очисткой истории прочитай пояснение: повторный запуск может изменить таблицу или создать новый snapshot.

Используй прежнюю папку репозитория: имя Compose-проекта определяет, какие Docker volumes подключаются. После переименования папки или запуска с другим -p можно получить новый пустой набор данных вместо предыдущего.

Вместе с JupyterLab доступен VS Code в браузере. Там же описаны выбор ядра и ограничения совместимости. Перед сменой интерфейса сохрани файл, выполни spark.stop() и останови ядро. Файлы общие, переменные Python — нет; не редактируй один ноутбук в двух интерфейсах одновременно.

Как проходить ноутбук

Ноутбук состоит из пояснений и кодовых ячеек. Ядро Python выполняет код и хранит переменные в памяти. Spark-сессия связывает этот Python-процесс с кластером.

• Прочитай пояснение, запусти ячейку через Shift+Enter, дождись окончания и сравни результат с описанием. Следующая ячейка может использовать предыдущие переменные, поэтому порядок важен.
• В самостоятельном задании заполни TODO и проверь результат. Run → Run All Cells запускает код, но не выполняет задание за тебя.
• Checkpoint — вопросы и проверки в конце урока. Покажи результат в своем стенде и объясни его своими словами перед переходом к следующему модулю.
• Сохраняй изменения через File → Save Notebook (Ctrl+S; на macOS — Cmd+S). Файл ноутбука вместе с ответами и выводом записывается в notebooks/ на хосте.
• Перед следующим модулем выполни завершающую ячейку spark.stop(), если она есть; иначе вызови spark.stop() после окончания вычислений. Это освобождает ресурсы Spark для следующего приложения. Закрытие вкладки браузера само по себе не останавливает вычисления.

Держи одну активную Spark-сессию: если несколько ноутбуков одновременно занимают все ядра worker-ов, новое задание может ждать ресурсы. Для своих SQL/Python-опытов можно создать дополнительный ноутбук через File → New → Notebook. Он появится в notebooks/ на хосте. Примеры src/ доступны Python по пути /opt/src только для чтения; документацию и конфиги открывай в копии репозитория на хосте.

Если нужно перезапустить ядро

Сначала сохрани ноутбук. Выбери Kernel → Restart Kernel… и подтверди перезапуск. Затем заново выполни импорты и создание Spark-сессии. Переменные Python исчезнут; файлы и записанные учебные таблицы сохранятся.

Перезапуск нужен, например, после изменения адреса кластера в spark/spark-defaults.conf или после остановки Spark-сессии, с которой хочешь продолжить работу. Повторный getOrCreate() при живой сессии использует ее; подробнее это разбирается в Модуле 3.

Закончить занятие

Сохрани ноутбук, дождись завершения вычислений и запиши для себя номер модуля и следующую ячейку. Затем в терминале хоста выполни:

docker compose stop

Контейнеры остановятся и освободят занятую ими оперативную память. Файлы ноутбуков, исходные данные и таблицы останутся. На следующем занятии используй docker compose up -d из начала этой памятки.

Что и где сохраняется

Docker volume — хранилище вне файловой системы контейнера. В этом стенде два таких хранилища: minio-data с объектами и postgres-data с каталогом Iceberg. Имена volumes в Docker обычно имеют префикс Compose-проекта.

Что	Где находится	После stop или down без -v
Код, ответы и сохраненный вывод ноутбуков	notebooks/ на хосте; /opt/work в JupyterLab	Сохраняются
Скачанные Parquet и CSV	data/nyc_taxi/ на хосте; /opt/data/nyc_taxi в контейнере	Сохраняются
Raw-файлы, данные и metadata-файлы Iceberg	Бакет lakehouse, volume minio-data	Сохраняются
Записи каталога Iceberg	PostgreSQL, volume postgres-data	Сохраняются
Переменные Python и живая Spark-сессия	Память процессов	Теряются; создай заново
Настройки интерфейса JupyterLab	Файловая система контейнера jupyter	При stop сохраняются; при удалении или пересоздании контейнера могут сброситься
Настройки VS Code, доверие рабочей области	Файловая система контейнера ide	При stop сохраняются; при удалении или пересоздании контейнера могут сброситься

docker compose down удаляет контейнеры и сеть проекта. Именованные volumes остаются, поэтому после up -d таблицы доступны снова. Для обычного окончания занятия достаточно stop. Поведение команд описано также в документации Docker: stop, down.

Начать с чистых данных

Этот шаг нужен только для осознанного повторного прохождения с пустым хранилищем. Он удалит оба volumes: raw-данные в MinIO, таблицы, их историю и записи каталога PostgreSQL. Сохраненные ноутбуки и скачанные файлы в data/ на хосте останутся.

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
Образ или зависимость не скачивается	Найди адрес источника и сервис в ошибке	Пройди диагностику сети
port is already allocated / address already in use	Какой порт занят, не запущена ли другая копия стенда?	Освободи нужный порт; список портов
Сервис завершился, unhealthy или долго starting	docker compose ps -a, затем docker compose logs --tail=100 <service>	Для postgres-iceberg используй сервис postgres; проверь первую ошибку в логах
JupyterLab не открывается	docker compose ps -a jupyter, логи jupyter	Открой http://localhost:8888; для сервера используй SSH-туннель
VS Code не открывает ноутбук или сообщает об ошибке webview / service worker	Адрес http://localhost:8889, отдельная вкладка	Проверь ограничения совместимости; продолжи в JupyterLab
Не выбирается ядро, нет pyspark	Выбрано Python 3 (ipykernel) в JupyterLab стенда?	Повтори выбор ядра; проверь логи 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	Сверь системные требования, закрой другие вычисления; одного кода 137 недостаточно для вывода об OOM
Ноутбук не сохраняется (Permission denied)	Это файл из notebooks/? Совпадает UID?	Проверь .env и настройку прав перед сборкой; после изменения UID/GID повтори docker compose build, затем docker compose up -d
Нет файлов Taxi или таблицы из прошлого модуля	Файлы в data/nyc_taxi, предыдущие модули, прежняя папка проекта	Для raw нужен Модуль 3, для bronze — 4, для silver — 5; после сброса восстанови их по порядку

Что передать ментору

Укажи ОС, модуль, ячейку или команду, ожидаемый результат и полный текст ошибки. Приложи вывод:

docker compose version
docker compose ps -a
docker compose logs --tail=100 jupyter

В последней команде замени jupyter на проблемный сервис, если ошибка в другом компоненте. Для ошибки ноутбука добавь имя выбранного ядра и вывод ячейки. Пароли, токены и адреса прокси с учетными данными в сообщение не включай.