docs: clarify learner workflow and resource requirements
This commit is contained in:
ddadmin committed
1 parent
78cf7b5fae
commit
21f3570b89
8 files changed
+399
-138
No files matched your search
+151
-112
@@ -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. Для первого ноутбука их готовить не нужно.
|
||||
|
||||
Нужно заранее установить:
|
||||
<a id="prerequisites"></a>
|
||||
|
||||
- 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).
|
||||
Reference in new issue
Block a user