304 lines
20 KiB
Markdown
304 lines
20 KiB
Markdown
# START HERE
|
||
|
||
Здесь ты подготовишь окружение и выполнишь первое вычисление в Spark.
|
||
К концу запуска в ноутбуке появится `Spark cluster smoke test passed.`, а результат
|
||
сохранится в файле на твоем компьютере. Smoke test — короткая проверка, что
|
||
основные компоненты работают вместе.
|
||
|
||
Если стенд уже собран, открой [памятку для следующего занятия](./docs/study_workflow.md).
|
||
Она объясняет, как продолжить работу, что сохраняется и куда смотреть при ошибках.
|
||
|
||
## Маршрут прохождения
|
||
|
||
1. Подготовь Docker, ресурсы и локальную копию репозитория.
|
||
2. Скачай образы, собери окружение и проверь запуск сервисов.
|
||
3. Открой первый ноутбук в браузерном VS Code и проверь результат вычисления.
|
||
4. Продолжи по [программе курса](./docs/course_program.md#маршрут-по-модулям).
|
||
|
||
Датасет Taxi понадобится перед Модулем 3, DBeaver необязателен и понадобится
|
||
только перед Модулем 6. Для первого ноутбука их готовить не нужно.
|
||
|
||
<a id="prerequisites"></a>
|
||
|
||
## Что подготовить
|
||
|
||
- 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](https://learn.microsoft.com/en-us/windows/wsl/wsl-config#main-wsl-settings)
|
||
и [ресурсы Docker Desktop](https://docs.docker.com/desktop/settings-and-maintenance/settings/#resources).
|
||
|
||
Trino ограничен 2 ГиБ памяти контейнера и 1 ГиБ Java heap. Проверка запросов
|
||
на данных курса описана в [справочнике](./docs/stack_reference.md#ресурсы-и-проверенная-среда).
|
||
Полный курс под общим жестким лимитом Docker 8 ГБ пока не проверен. В WSL2 часть
|
||
памяти также нужна самой Linux-среде; закрой другие тяжелые задачи на время урока.
|
||
Место внутри диска 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; память дана
|
||
в байтах (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 проверь владельца файлов:
|
||
|
||
```bash
|
||
id -u
|
||
id -g
|
||
```
|
||
|
||
Это 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. Скачать готовые образы и собрать окружение
|
||
|
||
```bash
|
||
docker compose pull minio minio-init postgres trino
|
||
docker compose build
|
||
```
|
||
|
||
Первая команда проверяет загрузку готовых сервисов до сборки окружения.
|
||
MinIO уже собран; для Spark, Jupyter и IDE первая сборка скачивает зависимости
|
||
и зависит по времени от сети и компьютера. Дождись завершения без ошибок;
|
||
не переходи к запуску после неудачной сборки. Повторная сборка использует кэш Docker.
|
||
|
||
### 2. Поднять стенд
|
||
|
||
```bash
|
||
docker compose up -d
|
||
```
|
||
|
||
### 3. Проверить статус контейнеров
|
||
|
||
```bash
|
||
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](http://localhost:8080) | Два worker-а в состоянии `ALIVE` |
|
||
| [MinIO Console](http://localhost:9001) | После входа `minioadmin` / `minioadmin` виден бакет `lakehouse` — контейнер для файлов курса |
|
||
| [VS Code](http://localhost:8889) | Слева папки **Ноутбуки**, **Примеры (только чтение)**, **Документация (только чтение)** |
|
||
|
||
В [Trino UI](http://localhost:8090) для входа достаточно имени, например `student`;
|
||
пароль в стенде не задан. Сейчас достаточно проверить, что интерфейс открывается.
|
||
Чтение общих таблиц через Trino разберем в Модуле 6.
|
||
|
||
Этот маршрут предполагает Docker на твоем компьютере: `localhost` относится
|
||
к машине с браузером. Доступ к VS Code на удаленном сервере описан отдельно
|
||
в [инструкции по SSH-туннелю](./docs/stack_reference.md#vs-code-в-браузере).
|
||
|
||
## Роли сервисов в стенде
|
||
|
||
| Сервис | Роль в модуле |
|
||
| --- | --- |
|
||
| `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`
|
||
выполняй в терминале хоста, откуда запускал стенд.
|
||
|
||
### Как понять, что первый запуск прошел
|
||
|
||
В третьей кодовой ячейке первого ноутбука появится отчет, содержащий:
|
||
|
||
```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 отдельные. Перед переходом сохрани ноутбук и заверши
|
||
Spark-сессию через `spark.stop()`; не редактируй один файл в двух интерфейсах
|
||
одновременно.
|
||
|
||
## Базовая диагностика
|
||
|
||
Начни с `docker compose ps -a` и логов проблемного сервиса, например:
|
||
|
||
```bash
|
||
docker compose logs --tail=100 ide
|
||
```
|
||
|
||
Выбери свой симптом в [таблице диагностики](./docs/study_workflow.md#если-что-то-не-работает).
|
||
При ошибке скачивания сразу открой [диагностику сети](./docs/network_access.md).
|
||
|
||
## Restart и reset
|
||
|
||
Для обычной паузы используй `docker compose stop`, на следующем занятии —
|
||
`docker compose up -d`. Порядок действий и последствия удаления контейнеров
|
||
описаны в [памятке](./docs/study_workflow.md#закончить-занятие).
|
||
|
||
Полный сброс удаляет учебные таблицы и каталог. Его команда вынесена в
|
||
[отдельный раздел](./docs/study_workflow.md#начать-с-чистых-данных), чтобы не путать
|
||
с окончанием занятия.
|
||
|
||
## Подготовка учебного датасета (перед Модулем 3)
|
||
|
||
Перед `notebooks/03_raw_ingest_and_first_read.ipynb` нужно заранее скачать учебный data bundle на хост, а не изнутри ноутбука.
|
||
|
||
Скачай каноническое учебное подмножество `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 \
|
||
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
|
||
```
|
||
|
||
Проверь, что файлы на месте:
|
||
|
||
```bash
|
||
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](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;`. После модулей 4–5 должны быть видны `bronze` и `silver`; до их прохождения этих схем может еще не быть.
|
||
- Troubleshooting: стенд поднят? контейнер `trino` Up? порт 8090 свободен?
|
||
|
||
## Что делать дальше
|
||
|
||
После первого ноутбука открой [маршрут по модулям](./docs/course_program.md#маршрут-по-модулям).
|
||
В нем есть ссылки на все восемь уроков и результат, который нужно получить
|
||
перед переходом дальше. Для следующего занятия сохрани ссылку на
|
||
[памятку учащегося](./docs/study_workflow.md).
|