Files

T

ddadmin 688c46c68b feat(module-1): доработаны материалы модуля 1 и удалён legacy-ноутбук

- Зачем:
  - нужен воспроизводимый вход в курс и единое место хранения планов по модулям.
- Что:
  - добавлены `plans/README.md`, living plan Модуля 1, `START_HERE.md` и канонический ноутбук `01_environment_and_smoke_test.ipynb`, а `cluster_smoke.py` расширен до reusable helper и CLI smoke test.
  - уточнены onboarding-материалы и окружение: добавлены Spark UI в `README.md`, ресурсы хоста и креды MinIO в `START_HERE.md`, использован `NB_GID` в `jupyter/Dockerfile`, в ноутбуке усилены самостоятельные задания и добавлены `cell id`, а пояснения в `cluster_smoke.py` переведены на русский для студентов.
  - обновлены `README.md`, `AGENTS.md` и archive howto, удалены устаревшие `spark-basic-test.ipynb` и `03_partitioning_and_schema_evolution.ipynb`.
- Проверка:
  - `python3 -m py_compile src/spark/cluster_smoke.py src/spark/__init__.py`.
  - `docker compose build spark-master` и `docker compose build jupyter`.
  - `docker compose up -d`, `docker compose exec jupyter python3 -c "from spark.cluster_smoke import create_spark_session, run_cluster_smoke; spark=create_spark_session(app_name='module-01-validation'); print(run_cluster_smoke(spark)); spark.stop()"` и `docker compose exec jupyter jupyter nbconvert --to notebook --execute /opt/work/01_environment_and_smoke_test.ipynb --output-dir /tmp --output module1-validation-2.ipynb`.

2026-03-07 00:24:40 +03:00

5.9 KiB

Raw Blame History

START HERE

Этот документ нужен для первого входа в курс и прохождения Модуля 1: поднять стенд, проверить сервисы, открыть интерфейсы и выполнить базовый smoke test.

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

Проверить prerequisites.
Собрать и поднять стенд.
Убедиться, что контейнеры живы.
Открыть основные UI.
Зайти в Jupyter и выполнить notebooks/01_environment_and_smoke_test.ipynb.
При проблемах использовать логи и шаги диагностики из этого документа.

Prerequisites

Нужно заранее установить:

Docker;
Docker Compose;
современный браузер для UI;
свободные порты на хосте.

Рекомендуемые ресурсы хоста:

не менее 4 vCPU;
не менее 10 GB RAM, иначе Spark, Trino и Jupyter могут стартовать нестабильно;
хотя бы 8-10 GB свободного места под образы и контейнеры.

Порты стенда

Сервис	Адрес	Зачем нужен
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`	Просмотр бакетов и файлов
JupyterLab	`http://localhost:8888`	Основная точка входа в практику
PostgreSQL	`localhost:5432`	JDBC-каталог Iceberg, нужен для диагностики

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

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

1. Собрать образы

docker compose build

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

docker compose up -d

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

docker compose ps

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

сервисы spark-master, spark-worker-1, spark-worker-2, minio, postgres-iceberg, trino, jupyter находятся в состоянии Up;
однократные init-контейнеры вроде minio-init и iceberg-catalog-init могут завершиться после успешной инициализации.

Куда заходить после старта

Открой в браузере:

http://localhost:8080 для Spark Master UI;
http://localhost:8090 для Trino UI;
http://localhost:9001 для MinIO Console;
http://localhost:8888 для JupyterLab.

Для входа в MinIO Console используй:

логин: minioadmin;
пароль: minioadmin.

Если интерфейсы открываются, переходи в Jupyter и запускай:

notebooks/01_environment_and_smoke_test.ipynb

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

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

Как работать в Jupyter

./notebooks смонтирован в контейнер как /opt/work;
./src смонтирован read-only как /opt/src;
PYTHONPATH=/opt/src, поэтому helper-скрипты из src/ доступны для импорта в ноутбуках;
первый ноутбук курса: 01_environment_and_smoke_test.ipynb.

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

Посмотреть список контейнеров

docker compose ps

Посмотреть логи конкретного сервиса

docker compose logs -f spark-master
docker compose logs -f trino
docker compose logs -f minio
docker compose logs -f jupyter

Типовые первые проверки

Spark UI не открывается: проверь docker compose ps и логи spark-master.
Trino UI не открывается: проверь docker compose ps и логи trino.
JupyterLab не открывается: проверь docker compose ps и логи jupyter.
MinIO Console не открывается: проверь docker compose ps и логи minio.
smoke test падает из ноутбука: сначала убедись, что spark-master и worker-ы видны в Spark UI.

Restart и reset

Мягкий перезапуск стенда

docker compose down
docker compose up -d

Полный reset с удалением данных

docker compose down -v
docker compose up -d

Используй полный reset, если хочешь пройти практику заново с чистого состояния.

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

пройти notebooks/01_environment_and_smoke_test.ipynb;
свериться с программой курса в docs/course_program.md;
после прохождения Модуля 1 переходить к следующим учебным материалам.

5.9 KiB Raw Blame History