mini-lakehouse-lab/START_HERE.md

START HERE

Здесь ты подготовишь окружение и выполнишь первое вычисление в Spark. К концу запуска в ноутбуке появится Spark cluster smoke test passed., а результат сохранится в файле на твоем компьютере. Smoke test — короткая проверка, что основные компоненты работают вместе.

Если стенд уже собран, открой памятку для следующего занятия. Она объясняет, как продолжить работу, что сохраняется и куда смотреть при ошибках.

Маршрут прохождения

1. Подготовь Docker, ресурсы и локальную копию репозитория.
2. Скачай образы, собери окружение и проверь запуск сервисов.
3. Открой первый ноутбук в браузерном VS Code и проверь результат вычисления.
4. Продолжи по программе курса.

Датасет Taxi понадобится перед Модулем 3, DBeaver необязателен и понадобится только перед Модулем 6. Для первого ноутбука их готовить не нужно.

Что подготовить

• Docker с запущенным движком и Docker Compose 2.17+ с BuildKit.
• Современный браузер; основной интерфейс курса — VS Code на localhost:8889.
• Git для скачивания репозитория или его распакованную ZIP-копию.
• Свободные порты из таблицы ниже и доступ к источникам образов и зависимостей.

Команды ниже рассчитаны на Bash: терминал Linux/macOS или терминал Linux в WSL2 на Windows с включенной интеграцией Docker Desktop. Выполняй их на машине, где работает Docker. Терминал внутри браузерного VS Code для запуска docker compose не подходит.

Системные требования

Ориентир для одного учащегося и основного набора Taxi за три месяца:

Ресурс	Рекомендация	Что проверить
Процессор	Не менее 4 CPU, доступных Docker	В Docker Desktop/WSL2 может стоять меньший лимит
Память Docker	Ориентир — 8 ГБ RAM; 10 ГБ дают дополнительный запас	Это память для среды Docker, а не общий объем памяти компьютера
Память компьютера	16 ГБ RAM или больше	Оставь память ОС, браузеру и другим приложениям
Свободное место	Не менее 20 ГБ перед первой сборкой; 30 ГБ с запасом	На диске Docker и в папке репозитория: образы, кэш сборки, исходные данные и таблицы

Это рекомендуемый бюджет для одного активного ноутбука, а не измеренный минимум. На Windows с WSL2 по умолчанию доступно 50% RAM компьютера: при 16 ГБ это 8 ГБ для всей WSL2, включая Docker. Лимит можно настроить, это не аппаратное ограничение. См. настройки WSL2 и ресурсы Docker Desktop.

Trino ограничен 2 ГиБ памяти контейнера и 1 ГиБ Java heap. Проверка запросов на данных курса описана в справочнике. Полный курс под общим жестким лимитом Docker 8 ГБ пока не проверен. В WSL2 часть памяти также нужна самой Linux-среде; закрой другие тяжелые задачи на время урока. Место внутри диска Docker и свободное место на диске компьютера — отдельные ограничения.

С добавлением VS Code образ окружения вырос примерно на 1,2 ГБ относительно Jupyter; базовые слои у них общие. MinIO скачивается готовым, компилировать его не нужно. Основания оценок и границы проверки.

Python, Java, Jupyter и расширения VS Code устанавливаются при сборке образов. На компьютере не нужно создавать venv или устанавливать Python-пакеты.

Для первой сборки нужен интернет. Если ты работаешь из РФ или сети с ограничениями, при ошибке скачивания используй инструкцию по доступу к репозиториям. Она различает проблемы скачивания образов и зависимостей внутри сборки.

Проверка до сборки

Открой терминал в папке репозитория — там, где лежит docker-compose.yml:

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; память дана в байтах (8 ГиБ — 8 589 934 592 байта). Последняя команда при успехе ничего не печатает. Если Docker не отвечает или конфигурация не читается, исправь эту ошибку до сборки.

Порты стенда

Сервис	Адрес	Зачем нужен
Spark Master UI	http://localhost:8080	Проверка мастера Spark и подключённых worker-ов
Spark Worker 1 UI	http://localhost:8081	Проверка первого worker-а
Spark Worker 2 UI	http://localhost:8082	Проверка второго worker-а
Trino UI	http://localhost:8090	Проверка координатора Trino
MinIO API	http://localhost:9000	S3-compatible endpoint
MinIO Console	http://localhost:9001	Просмотр бакетов и файлов
VS Code в браузере	http://localhost:8889	Основная точка входа в практику
JupyterLab	http://localhost:8888	Запасной интерфейс для ноутбуков
PostgreSQL	localhost:5432	JDBC-каталог Iceberg, нужен для диагностики

Быстрый запуск

Все команды выполняются из корня репозитория.

На Linux и в WSL2 проверь владельца файлов:

id -u
id -g

Это UID и GID — числовые идентификаторы пользователя и группы. В контейнере по умолчанию используются 1000 и 100. Если значения отличаются, до сборки создай .env в корне репозитория и укажи NB_UID и NB_GID со своими числами. Например, для вывода 1001 и 1001:

NB_UID=1001
NB_GID=1001

Если .env уже есть, измени только эти строки, сохранив остальные настройки. Файл остается между занятиями. Образец — .env.example. На macOS с Docker Desktop обычно подходят значения по умолчанию.

1. Скачать готовые образы и собрать окружение

docker compose pull minio minio-init postgres trino
docker compose build

Первая команда проверяет загрузку готовых сервисов до сборки окружения. MinIO уже собран; для Spark, Jupyter и IDE первая сборка скачивает зависимости и зависит по времени от сети и компьютера. Дождись завершения без ошибок; не переходи к запуску после неудачной сборки. Повторная сборка использует кэш Docker.

2. Поднять стенд

docker compose up -d

3. Проверить статус контейнеров

docker compose ps -a

Ожидаемое состояние:

• 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	Два worker-а в состоянии ALIVE
MinIO Console	После входа minioadmin / minioadmin виден бакет lakehouse — контейнер для файлов курса
VS Code	Слева папки Ноутбуки, Примеры (только чтение), Документация (только чтение)

В Trino UI для входа достаточно имени, например student; пароль в стенде не задан. Сейчас достаточно проверить, что интерфейс открывается. Чтение общих таблиц через Trino разберем в Модуле 6.

Этот маршрут предполагает Docker на твоем компьютере: localhost относится к машине с браузером. Доступ к VS Code на удаленном сервере описан отдельно в инструкции по SSH-туннелю.

Роли сервисов в стенде

Сервис	Роль в модуле
MinIO	storage: объектное хранилище для данных и файлов Iceberg
PostgreSQL	catalog: хранит метаданные JDBC-каталога Iceberg
Spark	compute: выполняет PySpark и Spark SQL задания
Trino	compute: читает те же таблицы через общий каталог
VS Code / JupyterLab	Интерфейсы для учебных ноутбуков

Как работать с ноутбуками

Ноутбук — файл с пояснениями, кодом и сохраненным выводом. Ядро — процесс Python, который исполняет код и хранит переменные до остановки.

1. Открой http://localhost:8889 в отдельной вкладке браузера.
2. Если сверху виден Restricted Mode, нажми Manage → Trust и закрой окно Workspace Trust. Подтверди доверие только к своей копии этого учебного репозитория: в Restricted Mode запуск ноутбуков ограничен.
3. В папке Ноутбуки открой 01_environment_and_smoke_test.ipynb.
4. Нажми Select Kernel → Python Environments и выбери Python с путём /usr/bin/python3. Он находится внутри контейнера ide, где уже есть зависимости курса. Пункт Existing Jupyter Server здесь не нужен.
5. Запусти первую кодовую ячейку кнопкой слева или Shift+Enter, затем остальные ячейки по порядку. Результат появится под ячейкой. Сохрани ноутбук через File → Save (Ctrl+S; на macOS — Cmd+S).

Терминал VS Code тоже работает внутри контейнера. Команды docker compose выполняй в терминале хоста, откуда запускал стенд.

Как понять, что первый запуск прошел

В третьей кодовой ячейке первого ноутбука появится отчет, содержащий:

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-сессия продолжают работать.

Правила запуска ячеек, перехода между модулями и сохранения данных собраны в памятке учащегося.

Запасной интерфейс — JupyterLab на http://localhost:8888. Файлы ноутбуков общие, а ядра и переменные Python отдельные. Перед переходом сохрани ноутбук и заверши Spark-сессию через spark.stop(); не редактируй один файл в двух интерфейсах одновременно.

Базовая диагностика

Начни с docker compose ps -a и логов проблемного сервиса, например:

docker compose logs --tail=100 ide

Выбери свой симптом в таблице диагностики. При ошибке скачивания сразу открой диагностику сети.

Restart и reset

Для обычной паузы используй docker compose stop, на следующем занятии — docker compose up -d. Порядок действий и последствия удаления контейнеров описаны в памятке.

Полный сброс удаляет учебные таблицы и каталог. Его команда вынесена в отдельный раздел, чтобы не путать с окончанием занятия.

Подготовка учебного датасета (перед Модулем 3)

Перед notebooks/03_raw_ingest_and_first_read.ipynb нужно заранее скачать учебный data bundle на хост, а не изнутри ноутбука.

Скачай каноническое учебное подмножество NYC TLC Yellow Taxi Trip Records:

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 \
  https://d37ci6vzurychx.cloudfront.net/trip-data/yellow_tripdata_2024-02.parquet
curl -fLo data/nyc_taxi/yellow_tripdata_2024-03.parquet \
  https://d37ci6vzurychx.cloudfront.net/trip-data/yellow_tripdata_2024-03.parquet
curl -fLo data/nyc_taxi/taxi_zone_lookup.csv \
  https://d37ci6vzurychx.cloudfront.net/misc/taxi_zone_lookup.csv

Проверь, что файлы на месте:

ls -lh data/nyc_taxi/

Минимальный набор для курса:

• yellow_tripdata_2024-01.parquet
• yellow_tripdata_2024-02.parquet
• yellow_tripdata_2024-03.parquet
• taxi_zone_lookup.csv

Если хочешь расширенный режим, можешь скачать все 12 месяцев 2024, но основной маршрут курса и примеры опираются на первые 3 месяца.

Подключение DBeaver к Trino (перед Модулем 6)

• Зачем: в Модуле 6 можно работать с Trino через DBeaver параллельно с ноутбуком — привычный SQL-интерфейс.
• Предусловие: DBeaver установлен (ссылка на 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;. После модулей 4–5 должны быть видны bronze и silver; до их прохождения этих схем может еще не быть.
• Troubleshooting: стенд поднят? контейнер trino Up? порт 8090 свободен?

Что делать дальше

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